depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Leonov Artur (Depish)
2025-10-25 03:02:53 +03:00
commit 043225d523
3416 changed files with 681196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

506
cppdraft/fs/class/directory/entry.md Normal file
View File

@@ -0,0 +1,506 @@
[fs.class.directory.entry]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.directory.entry)
### 31.12.10 Class directory_entry [fs.class.directory.entry]
#### [31.12.10.1](#general) General [[fs.class.directory.entry.general]](fs.class.directory.entry.general)
[🔗](#lib:directory_entry)
namespace std::filesystem {class directory_entry {public:// [[fs.dir.entry.cons]](#fs.dir.entry.cons "31.12.10.2 Constructors"), constructors and destructor directory_entry() noexcept = default;
directory_entry(const directory_entry&) = default;
directory_entry(directory_entry&&) noexcept = default; explicit directory_entry(const filesystem::path& p);
directory_entry(const filesystem::path& p, error_code& ec); ~directory_entry(); // assignments directory_entry& operator=(const directory_entry&) = default;
directory_entry& operator=(directory_entry&&) noexcept = default; // [[fs.dir.entry.mods]](#fs.dir.entry.mods "31.12.10.3 Modifiers"), modifiersvoid assign(const filesystem::path& p); void assign(const filesystem::path& p, error_code& ec); void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec); void refresh(); void refresh(error_code& ec) noexcept; // [[fs.dir.entry.obs]](#fs.dir.entry.obs "31.12.10.4 Observers"), observersconst filesystem::path& path() const noexcept; operator const filesystem::path&() const noexcept; bool exists() const; bool exists(error_code& ec) const noexcept; bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept; bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept; bool is_directory() const; bool is_directory(error_code& ec) const noexcept; bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept; bool is_other() const; bool is_other(error_code& ec) const noexcept; bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept; bool is_socket() const; bool is_socket(error_code& ec) const noexcept; bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept;
uintmax_t file_size() const;
uintmax_t file_size(error_code& ec) const noexcept;
uintmax_t hard_link_count() const;
uintmax_t hard_link_count(error_code& ec) const noexcept;
file_time_type last_write_time() const;
file_time_type last_write_time(error_code& ec) const noexcept;
file_status status() const;
file_status status(error_code& ec) const noexcept;
file_status symlink_status() const;
file_status symlink_status(error_code& ec) const noexcept; bool operator==(const directory_entry& rhs) const noexcept;
strong_ordering operator<=>(const directory_entry& rhs) const noexcept; // [[fs.dir.entry.io]](#fs.dir.entry.io "31.12.10.5 Inserter"), insertertemplate<class charT, class traits>friend basic_ostream<charT, traits>&operator<<(basic_ostream<charT, traits>& os, const directory_entry& d); private: filesystem::path *path-object*; // *exposition only*};}
[1](#general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16110)
A directory_entry object stores a path object
and may store additional objects for file attributes
such as hard link count, status, symlink status, file size, and last write time[.](#general-1.sentence-1)
[2](#general-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16116)
Implementations should store such additional file attributes
during directory iteration if their values are available
and storing the values would allow the implementation to eliminate file system accesses
by directory_entry observer functions ([[fs.op.funcs]](fs.op.funcs "31.12.13 Filesystem operation functions"))[.](#general-2.sentence-1)
Such stored file attribute values are said to be [*cached*](#def:file_attributes,cached "31.12.10.1 General [fs.class.directory.entry.general]")[.](#general-2.sentence-2)
[3](#general-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16123)
[*Note [1](#general-note-1)*:
directory_iterator can cache
already available attribute values
directly into a directory_entry object
without the cost of a call to refresh()[.](#general-3.sentence-1)
— *end note*]
[4](#general-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16131)
[*Example [1](#general-example-1)*: using namespace std::filesystem;
// use possibly cached last write time to minimize disk accessesfor (auto&& x : directory_iterator(".")){ std::cout << x.path() << " " << x.last_write_time() << std::endl;}// call refresh() to refresh a stale cachefor (auto&& x : directory_iterator(".")){ lengthy_function(x.path()); // cache becomes stale x.refresh();
std::cout << x.path() << " " << x.last_write_time() << std::endl;}
On implementations that do not cache the last write time,
both loops will result in a potentially expensive call
to the std​::​filesystem​::​last_write_time function[.](#general-4.sentence-1)
On implementations that do cache the last write time,
the first loop will use the cached value and so
will not result in a potentially expensive call
to the std​::​filesystem​::​last_write_time function[.](#general-4.sentence-2)
The code is portable to any implementation,
regardless of whether or not it employs caching[.](#general-4.sentence-3)
— *end example*]
#### [31.12.10.2](#fs.dir.entry.cons) Constructors [[fs.dir.entry.cons]](fs.dir.entry.cons)
[🔗](#lib:directory_entry,constructor)
`explicit directory_entry(const filesystem::path& p);
directory_entry(const filesystem::path& p, error_code& ec);
`
[1](#fs.dir.entry.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16172)
*Effects*: Calls refresh() or refresh(ec), respectively[.](#fs.dir.entry.cons-1.sentence-1)
[2](#fs.dir.entry.cons-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16176)
*Postconditions*: path() == p if no error occurs,
otherwise path() == filesystem​::​path()[.](#fs.dir.entry.cons-2.sentence-1)
[3](#fs.dir.entry.cons-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16181)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.cons-3.sentence-1)
#### [31.12.10.3](#fs.dir.entry.mods) Modifiers [[fs.dir.entry.mods]](fs.dir.entry.mods)
[🔗](#lib:assign,directory_entry)
`void assign(const filesystem::path& p);
void assign(const filesystem::path& p, error_code& ec);
`
[1](#fs.dir.entry.mods-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16195)
*Effects*: Equivalent to *path-object* = p,
then refresh() or refresh(ec), respectively[.](#fs.dir.entry.mods-1.sentence-1)
If an error occurs, the values of any cached attributes are unspecified[.](#fs.dir.entry.mods-1.sentence-2)
[2](#fs.dir.entry.mods-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16201)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.mods-2.sentence-1)
[🔗](#lib:replace_filename,directory_entry)
`void replace_filename(const filesystem::path& p);
void replace_filename(const filesystem::path& p, error_code& ec);
`
[3](#fs.dir.entry.mods-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16213)
*Effects*: Equivalent to *path-object*.replace_filename(p),
then refresh() or refresh(ec), respectively[.](#fs.dir.entry.mods-3.sentence-1)
If an error occurs, the values of any cached attributes are unspecified[.](#fs.dir.entry.mods-3.sentence-2)
[4](#fs.dir.entry.mods-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16219)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.mods-4.sentence-1)
[🔗](#lib:refresh,directory_entry)
`void refresh();
void refresh(error_code& ec) noexcept;
`
[5](#fs.dir.entry.mods-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16231)
*Effects*: Stores the current values of any cached attributes of the file p resolves to[.](#fs.dir.entry.mods-5.sentence-1)
If an error occurs, an error is reported ([[fs.err.report]](fs.err.report "31.12.5 Error reporting"))
and the values of any cached attributes are unspecified[.](#fs.dir.entry.mods-5.sentence-2)
[6](#fs.dir.entry.mods-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16237)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.mods-6.sentence-1)
[7](#fs.dir.entry.mods-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16241)
[*Note [1](#fs.dir.entry.mods-note-1)*:
Implementations of directory_iterator ([[fs.class.directory.iterator]](fs.class.directory.iterator "31.12.11 Class directory_­iterator"))
are prohibited from directly or indirectly calling the refresh function
as described in [[fs.class.directory.iterator.general]](fs.class.directory.iterator.general "31.12.11.1 General")[.](#fs.dir.entry.mods-7.sentence-1)
— *end note*]
#### [31.12.10.4](#fs.dir.entry.obs) Observers [[fs.dir.entry.obs]](fs.dir.entry.obs)
[1](#fs.dir.entry.obs-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16251)
Unqualified function names in the *Returns*: elements of thedirectory_entry observers described below refer to members of thestd​::​filesystem namespace[.](#fs.dir.entry.obs-1.sentence-1)
[🔗](#lib:path,directory_entry)
`const filesystem::path& path() const noexcept;
operator const filesystem::path&() const noexcept;
`
[2](#fs.dir.entry.obs-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16264)
*Returns*: *path-object*[.](#fs.dir.entry.obs-2.sentence-1)
[🔗](#lib:exists,directory_entry)
`bool exists() const;
bool exists(error_code& ec) const noexcept;
`
[3](#fs.dir.entry.obs-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16276)
*Returns*: exists(this->status()) or exists(this->status(ec)), respectively[.](#fs.dir.entry.obs-3.sentence-1)
[4](#fs.dir.entry.obs-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16280)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-4.sentence-1)
[🔗](#lib:is_block_file,directory_entry)
`bool is_block_file() const;
bool is_block_file(error_code& ec) const noexcept;
`
[5](#fs.dir.entry.obs-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16292)
*Returns*: is_block_file(this->status()) or is_block_file(this->status(ec)), respectively[.](#fs.dir.entry.obs-5.sentence-1)
[6](#fs.dir.entry.obs-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16296)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-6.sentence-1)
[🔗](#lib:is_character_file,directory_entry)
`bool is_character_file() const;
bool is_character_file(error_code& ec) const noexcept;
`
[7](#fs.dir.entry.obs-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16308)
*Returns*: is_character_file(this->status()) or is_character_file(this->status(ec)), respectively[.](#fs.dir.entry.obs-7.sentence-1)
[8](#fs.dir.entry.obs-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16312)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-8.sentence-1)
[🔗](#lib:is_directory,directory_entry)
`bool is_directory() const;
bool is_directory(error_code& ec) const noexcept;
`
[9](#fs.dir.entry.obs-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16324)
*Returns*: is_directory(this->status()) or is_directory(this->status(ec)), respectively[.](#fs.dir.entry.obs-9.sentence-1)
[10](#fs.dir.entry.obs-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16328)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-10.sentence-1)
[🔗](#lib:is_fifo,directory_entry)
`bool is_fifo() const;
bool is_fifo(error_code& ec) const noexcept;
`
[11](#fs.dir.entry.obs-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16340)
*Returns*: is_fifo(this->status()) or is_fifo(this->status(ec)), respectively[.](#fs.dir.entry.obs-11.sentence-1)
[12](#fs.dir.entry.obs-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16344)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-12.sentence-1)
[🔗](#lib:is_other,directory_entry)
`bool is_other() const;
bool is_other(error_code& ec) const noexcept;
`
[13](#fs.dir.entry.obs-13)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16356)
*Returns*: is_other(this->status()) or is_other(this->status(ec)), respectively[.](#fs.dir.entry.obs-13.sentence-1)
[14](#fs.dir.entry.obs-14)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16360)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-14.sentence-1)
[🔗](#lib:is_regular_file,directory_entry)
`bool is_regular_file() const;
bool is_regular_file(error_code& ec) const noexcept;
`
[15](#fs.dir.entry.obs-15)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16372)
*Returns*: is_regular_file(this->status()) or is_regular_file(this->status(ec)), respectively[.](#fs.dir.entry.obs-15.sentence-1)
[16](#fs.dir.entry.obs-16)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16376)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-16.sentence-1)
[🔗](#lib:is_socket,directory_entry)
`bool is_socket() const;
bool is_socket(error_code& ec) const noexcept;
`
[17](#fs.dir.entry.obs-17)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16388)
*Returns*: is_socket(this->status()) or is_socket(this->status(ec)), respectively[.](#fs.dir.entry.obs-17.sentence-1)
[18](#fs.dir.entry.obs-18)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16392)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-18.sentence-1)
[🔗](#lib:is_symlink,directory_entry)
`bool is_symlink() const;
bool is_symlink(error_code& ec) const noexcept;
`
[19](#fs.dir.entry.obs-19)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16404)
*Returns*: is_symlink(this->symlink_status()) or is_symlink(this->symlink_status(ec)), respectively[.](#fs.dir.entry.obs-19.sentence-1)
[20](#fs.dir.entry.obs-20)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16408)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-20.sentence-1)
[🔗](#lib:file_size,directory_entry)
`uintmax_t file_size() const;
uintmax_t file_size(error_code& ec) const noexcept;
`
[21](#fs.dir.entry.obs-21)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16420)
*Returns*: If cached, the file size attribute value[.](#fs.dir.entry.obs-21.sentence-1)
Otherwise, file_size(path()) or file_size(path(), ec), respectively[.](#fs.dir.entry.obs-21.sentence-2)
[22](#fs.dir.entry.obs-22)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16425)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-22.sentence-1)
[🔗](#lib:hard_link_count,directory_entry)
`uintmax_t hard_link_count() const;
uintmax_t hard_link_count(error_code& ec) const noexcept;
`
[23](#fs.dir.entry.obs-23)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16437)
*Returns*: If cached, the hard link count attribute value[.](#fs.dir.entry.obs-23.sentence-1)
Otherwise, hard_link_count(path()) or hard_link_count(path(), ec), respectively[.](#fs.dir.entry.obs-23.sentence-2)
[24](#fs.dir.entry.obs-24)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16442)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-24.sentence-1)
[🔗](#lib:last_write_time,directory_entry)
`file_time_type last_write_time() const;
file_time_type last_write_time(error_code& ec) const noexcept;
`
[25](#fs.dir.entry.obs-25)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16454)
*Returns*: If cached, the last write time attribute value[.](#fs.dir.entry.obs-25.sentence-1)
Otherwise, last_write_time(path()) or last_write_time(path(), ec), respectively[.](#fs.dir.entry.obs-25.sentence-2)
[26](#fs.dir.entry.obs-26)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16459)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-26.sentence-1)
[🔗](#lib:status,directory_entry)
`file_status status() const;
file_status status(error_code& ec) const noexcept;
`
[27](#fs.dir.entry.obs-27)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16471)
*Returns*: If cached, the status attribute value[.](#fs.dir.entry.obs-27.sentence-1)
Otherwise, status(path()) or status(path(), ec), respectively[.](#fs.dir.entry.obs-27.sentence-2)
[28](#fs.dir.entry.obs-28)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16476)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-28.sentence-1)
[🔗](#lib:symlink_status,directory_entry)
`file_status symlink_status() const;
file_status symlink_status(error_code& ec) const noexcept;
`
[29](#fs.dir.entry.obs-29)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16488)
*Returns*: If cached, the symlink status attribute value[.](#fs.dir.entry.obs-29.sentence-1)
Otherwise, symlink_status(path()) or symlink_status(path(), ec), respectively[.](#fs.dir.entry.obs-29.sentence-2)
[30](#fs.dir.entry.obs-30)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16493)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.entry.obs-30.sentence-1)
[🔗](#lib:operator==,directory_entry)
`bool operator==(const directory_entry& rhs) const noexcept;
`
[31](#fs.dir.entry.obs-31)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16504)
*Returns*: *path-object* == rhs.*path-object*[.](#fs.dir.entry.obs-31.sentence-1)
[🔗](#lib:operator%3c=%3e,directory_entry)
`strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
`
[32](#fs.dir.entry.obs-32)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16515)
*Returns*: *path-object* <=> rhs.*path-object*[.](#fs.dir.entry.obs-32.sentence-1)
#### [31.12.10.5](#fs.dir.entry.io) Inserter [[fs.dir.entry.io]](fs.dir.entry.io)
[🔗](#lib:operator%3c%3c,directory_entry)
`template<class charT, class traits>
friend basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
`
[1](#fs.dir.entry.io-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16530)
*Effects*: Equivalent to: return os << d.path();

83
cppdraft/fs/class/directory/entry/general.md Normal file
View File

@@ -0,0 +1,83 @@
[fs.class.directory.entry.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.directory.entry.general)
### 31.12.10 Class directory_entry [[fs.class.directory.entry]](fs.class.directory.entry#general)
#### 31.12.10.1 General [fs.class.directory.entry.general]
[🔗](#lib:directory_entry)
namespace std::filesystem {class directory_entry {public:// [[fs.dir.entry.cons]](fs.dir.entry.cons "31.12.10.2 Constructors"), constructors and destructor directory_entry() noexcept = default;
directory_entry(const directory_entry&) = default;
directory_entry(directory_entry&&) noexcept = default; explicit directory_entry(const filesystem::path& p);
directory_entry(const filesystem::path& p, error_code& ec); ~directory_entry(); // assignments directory_entry& operator=(const directory_entry&) = default;
directory_entry& operator=(directory_entry&&) noexcept = default; // [[fs.dir.entry.mods]](fs.dir.entry.mods "31.12.10.3 Modifiers"), modifiersvoid assign(const filesystem::path& p); void assign(const filesystem::path& p, error_code& ec); void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec); void refresh(); void refresh(error_code& ec) noexcept; // [[fs.dir.entry.obs]](fs.dir.entry.obs "31.12.10.4 Observers"), observersconst filesystem::path& path() const noexcept; operator const filesystem::path&() const noexcept; bool exists() const; bool exists(error_code& ec) const noexcept; bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept; bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept; bool is_directory() const; bool is_directory(error_code& ec) const noexcept; bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept; bool is_other() const; bool is_other(error_code& ec) const noexcept; bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept; bool is_socket() const; bool is_socket(error_code& ec) const noexcept; bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept;
uintmax_t file_size() const;
uintmax_t file_size(error_code& ec) const noexcept;
uintmax_t hard_link_count() const;
uintmax_t hard_link_count(error_code& ec) const noexcept;
file_time_type last_write_time() const;
file_time_type last_write_time(error_code& ec) const noexcept;
file_status status() const;
file_status status(error_code& ec) const noexcept;
file_status symlink_status() const;
file_status symlink_status(error_code& ec) const noexcept; bool operator==(const directory_entry& rhs) const noexcept;
strong_ordering operator<=>(const directory_entry& rhs) const noexcept; // [[fs.dir.entry.io]](fs.dir.entry.io "31.12.10.5 Inserter"), insertertemplate<class charT, class traits>friend basic_ostream<charT, traits>&operator<<(basic_ostream<charT, traits>& os, const directory_entry& d); private: filesystem::path *path-object*; // *exposition only*};}
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16110)
A directory_entry object stores a path object
and may store additional objects for file attributes
such as hard link count, status, symlink status, file size, and last write time[.](#1.sentence-1)
[2](#2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16116)
Implementations should store such additional file attributes
during directory iteration if their values are available
and storing the values would allow the implementation to eliminate file system accesses
by directory_entry observer functions ([[fs.op.funcs]](fs.op.funcs "31.12.13 Filesystem operation functions"))[.](#2.sentence-1)
Such stored file attribute values are said to be [*cached*](#def:file_attributes,cached "31.12.10.1 General [fs.class.directory.entry.general]")[.](#2.sentence-2)
[3](#3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16123)
[*Note [1](#note-1)*:
directory_iterator can cache
already available attribute values
directly into a directory_entry object
without the cost of a call to refresh()[.](#3.sentence-1)
— *end note*]
[4](#4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16131)
[*Example [1](#example-1)*: using namespace std::filesystem;
// use possibly cached last write time to minimize disk accessesfor (auto&& x : directory_iterator(".")){ std::cout << x.path() << " " << x.last_write_time() << std::endl;}// call refresh() to refresh a stale cachefor (auto&& x : directory_iterator(".")){ lengthy_function(x.path()); // cache becomes stale x.refresh();
std::cout << x.path() << " " << x.last_write_time() << std::endl;}
On implementations that do not cache the last write time,
both loops will result in a potentially expensive call
to the std​::​filesystem​::​last_write_time function[.](#4.sentence-1)
On implementations that do cache the last write time,
the first loop will use the cached value and so
will not result in a potentially expensive call
to the std​::​filesystem​::​last_write_time function[.](#4.sentence-2)
The code is portable to any implementation,
regardless of whether or not it employs caching[.](#4.sentence-3)
— *end example*]

281
cppdraft/fs/class/directory/iterator.md Normal file
View File

@@ -0,0 +1,281 @@
[fs.class.directory.iterator]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.directory.iterator)
### 31.12.11 Class directory_iterator [fs.class.directory.iterator]
#### [31.12.11.1](#general) General [[fs.class.directory.iterator.general]](fs.class.directory.iterator.general)
[1](#general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16540)
An object of type directory_iterator provides an iterator for a
sequence of directory_entry elements representing the
path and any cached attribute values ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
for each file in a directory
or in an implementation-defined directory-like file type[.](#general-1.sentence-1)
[*Note [1](#general-note-1)*:
For iteration into subdirectories, see class recursive_directory_iterator ([[fs.class.rec.dir.itr]](fs.class.rec.dir.itr "31.12.12 Class recursive_­directory_­iterator"))[.](#general-1.sentence-2)
— *end note*]
namespace std::filesystem {class directory_iterator {public:using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [[fs.dir.itr.members]](#fs.dir.itr.members "31.12.11.2 Members"), member functions directory_iterator() noexcept; explicit directory_iterator(const path& p);
directory_iterator(const path& p, directory_options options);
directory_iterator(const path& p, error_code& ec);
directory_iterator(const path& p, directory_options options,
error_code& ec);
directory_iterator(const directory_iterator& rhs);
directory_iterator(directory_iterator&& rhs) noexcept; ~directory_iterator();
directory_iterator& operator=(const directory_iterator& rhs);
directory_iterator& operator=(directory_iterator&& rhs) noexcept; const directory_entry& operator*() const; const directory_entry* operator->() const;
directory_iterator& operator++();
directory_iterator& increment(error_code& ec); bool operator==(default_sentinel_t) const noexcept {return *this == directory_iterator(); }// other members as required by [[input.iterators]](input.iterators "24.3.5.3 Input iterators"), input iterators};}
[2](#general-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16588)
directory_iterator meets the[*Cpp17InputIterator*](input.iterators#:Cpp17InputIterator "24.3.5.3 Input iterators [input.iterators]") requirements ([[input.iterators]](input.iterators "24.3.5.3 Input iterators"))[.](#general-2.sentence-1)
[3](#general-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16592)
If an iterator of type directory_iterator reports an error or
is advanced past the last directory element,
that iterator shall become equal to the end iterator
value[.](#general-3.sentence-1)
The directory_iterator default constructor shall
create an iterator equal to the end iterator value, and this shall be the only
valid iterator for the end condition[.](#general-3.sentence-2)
[4](#general-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16600)
The end iterator is not dereferenceable[.](#general-4.sentence-1)
[5](#general-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16603)
Two end iterators are always equal[.](#general-5.sentence-1)
An end iterator shall not be equal to a non-end
iterator[.](#general-5.sentence-2)
[6](#general-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16607)
The result of calling the path() member of the directory_entry object obtained by dereferencing a directory_iterator is a reference to a path object composed of the directory argument from which the iterator was
constructed with the filename of the directory entry appended as if by operator/=[.](#general-6.sentence-1)
[7](#general-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16611)
Directory iteration shall not yield directory entries for the current (dot)
and parent (dot-dot) directories[.](#general-7.sentence-1)
[8](#general-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16615)
The order of directory entries obtained by dereferencing successive
increments of a directory_iterator is unspecified[.](#general-8.sentence-1)
[9](#general-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16619)
Constructors and non-const directory_iterator member functions
store the values of any cached attributes ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
in the directory_entry element returned by operator*()[.](#general-9.sentence-1)
directory_iterator member functions shall not directly or indirectly call
any directory_entry refresh function[.](#general-9.sentence-2)
[*Note [2](#general-note-2)*:
The exact mechanism for storing cached attribute values is not exposed to users[.](#general-9.sentence-3)
— *end note*]
[10](#general-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16629)
[*Note [3](#general-note-3)*:
A path obtained by dereferencing a directory iterator might not actually exist;
it could be a symbolic link to a non-existent file[.](#general-10.sentence-1)
Recursively walking directory trees
for purposes of removing and renaming entries
might invalidate symbolic links that are being followed[.](#general-10.sentence-2)
— *end note*]
[11](#general-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16638)
[*Note [4](#general-note-4)*:
If a file is removed from or added to a directory after the
construction of a directory_iterator for the directory, it is
unspecified whether or not subsequently incrementing the iterator will ever
result in an iterator referencing the removed or added directory entry[.](#general-11.sentence-1)
See
POSIX [readdir](http://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html)[.](#general-11.sentence-2)
— *end note*]
#### [31.12.11.2](#fs.dir.itr.members) Members [[fs.dir.itr.members]](fs.dir.itr.members)
[🔗](#lib:directory_iterator,constructor)
`directory_iterator() noexcept;
`
[1](#fs.dir.itr.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16655)
*Effects*: Constructs the end iterator[.](#fs.dir.itr.members-1.sentence-1)
[🔗](#lib:directory_iterator,constructor_)
`explicit directory_iterator(const path& p);
directory_iterator(const path& p, directory_options options);
directory_iterator(const path& p, error_code& ec);
directory_iterator(const path& p, directory_options options, error_code& ec);
`
[2](#fs.dir.itr.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16669)
*Effects*: For the directory that p resolves to, constructs an
iterator for the first element in a sequence of directory_entry elements representing the files in the directory, if any; otherwise the end
iterator[.](#fs.dir.itr.members-2.sentence-1)
However, if(options & directory_options::skip_permission_denied) != directory_options::none and construction encounters an error indicating
that permission to access p is denied, constructs the end iterator
and does not report an error[.](#fs.dir.itr.members-2.sentence-2)
[3](#fs.dir.itr.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16682)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.itr.members-3.sentence-1)
[4](#fs.dir.itr.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16686)
[*Note [1](#fs.dir.itr.members-note-1)*:
To iterate over the current directory, use directory_iterator(".") rather than directory_iterator("")[.](#fs.dir.itr.members-4.sentence-1)
— *end note*]
[🔗](#lib:directory_iterator,constructor__)
`directory_iterator(const directory_iterator& rhs);
directory_iterator(directory_iterator&& rhs) noexcept;
`
[5](#fs.dir.itr.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16699)
*Postconditions*: *this has the original value of rhs[.](#fs.dir.itr.members-5.sentence-1)
[🔗](#lib:operator=,directory_iterator)
`directory_iterator& operator=(const directory_iterator& rhs);
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
`
[6](#fs.dir.itr.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16711)
*Effects*: If *this and rhs are the same
object, the member has no effect[.](#fs.dir.itr.members-6.sentence-1)
[7](#fs.dir.itr.members-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16716)
*Postconditions*: *this has the original value of rhs[.](#fs.dir.itr.members-7.sentence-1)
[8](#fs.dir.itr.members-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16720)
*Returns*: *this[.](#fs.dir.itr.members-8.sentence-1)
[🔗](#lib:increment,directory_iterator)
`directory_iterator& operator++();
directory_iterator& increment(error_code& ec);
`
[9](#fs.dir.itr.members-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16733)
*Effects*: As specified for the prefix increment operation of[Input iterators](input.iterators "24.3.5.3 Input iterators [input.iterators]")[.](#fs.dir.itr.members-9.sentence-1)
[10](#fs.dir.itr.members-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16738)
*Returns*: *this[.](#fs.dir.itr.members-10.sentence-1)
[11](#fs.dir.itr.members-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16742)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.dir.itr.members-11.sentence-1)
#### [31.12.11.3](#fs.dir.itr.nonmembers) Non-member functions [[fs.dir.itr.nonmembers]](fs.dir.itr.nonmembers)
[1](#fs.dir.itr.nonmembers-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16749)
These functions enable range access for directory_iterator[.](#fs.dir.itr.nonmembers-1.sentence-1)
[🔗](#lib:begin,directory_iterator)
`directory_iterator begin(directory_iterator iter) noexcept;
`
[2](#fs.dir.itr.nonmembers-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16758)
*Returns*: iter[.](#fs.dir.itr.nonmembers-2.sentence-1)
[🔗](#lib:end,directory_iterator)
`directory_iterator end(directory_iterator) noexcept;
`
[3](#fs.dir.itr.nonmembers-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16769)
*Returns*: directory_iterator()[.](#fs.dir.itr.nonmembers-3.sentence-1)

141
cppdraft/fs/class/directory/iterator/general.md Normal file
View File

@@ -0,0 +1,141 @@
[fs.class.directory.iterator.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.directory.iterator.general)
### 31.12.11 Class directory_iterator [[fs.class.directory.iterator]](fs.class.directory.iterator#general)
#### 31.12.11.1 General [fs.class.directory.iterator.general]
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16540)
An object of type directory_iterator provides an iterator for a
sequence of directory_entry elements representing the
path and any cached attribute values ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
for each file in a directory
or in an implementation-defined directory-like file type[.](#1.sentence-1)
[*Note [1](#note-1)*:
For iteration into subdirectories, see class recursive_directory_iterator ([[fs.class.rec.dir.itr]](fs.class.rec.dir.itr "31.12.12 Class recursive_­directory_­iterator"))[.](#1.sentence-2)
— *end note*]
namespace std::filesystem {class directory_iterator {public:using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [[fs.dir.itr.members]](fs.dir.itr.members "31.12.11.2 Members"), member functions directory_iterator() noexcept; explicit directory_iterator(const path& p);
directory_iterator(const path& p, directory_options options);
directory_iterator(const path& p, error_code& ec);
directory_iterator(const path& p, directory_options options,
error_code& ec);
directory_iterator(const directory_iterator& rhs);
directory_iterator(directory_iterator&& rhs) noexcept; ~directory_iterator();
directory_iterator& operator=(const directory_iterator& rhs);
directory_iterator& operator=(directory_iterator&& rhs) noexcept; const directory_entry& operator*() const; const directory_entry* operator->() const;
directory_iterator& operator++();
directory_iterator& increment(error_code& ec); bool operator==(default_sentinel_t) const noexcept {return *this == directory_iterator(); }// other members as required by [[input.iterators]](input.iterators "24.3.5.3 Input iterators"), input iterators};}
[2](#2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16588)
directory_iterator meets the[*Cpp17InputIterator*](input.iterators#:Cpp17InputIterator "24.3.5.3 Input iterators [input.iterators]") requirements ([[input.iterators]](input.iterators "24.3.5.3 Input iterators"))[.](#2.sentence-1)
[3](#3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16592)
If an iterator of type directory_iterator reports an error or
is advanced past the last directory element,
that iterator shall become equal to the end iterator
value[.](#3.sentence-1)
The directory_iterator default constructor shall
create an iterator equal to the end iterator value, and this shall be the only
valid iterator for the end condition[.](#3.sentence-2)
[4](#4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16600)
The end iterator is not dereferenceable[.](#4.sentence-1)
[5](#5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16603)
Two end iterators are always equal[.](#5.sentence-1)
An end iterator shall not be equal to a non-end
iterator[.](#5.sentence-2)
[6](#6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16607)
The result of calling the path() member of the directory_entry object obtained by dereferencing a directory_iterator is a reference to a path object composed of the directory argument from which the iterator was
constructed with the filename of the directory entry appended as if by operator/=[.](#6.sentence-1)
[7](#7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16611)
Directory iteration shall not yield directory entries for the current (dot)
and parent (dot-dot) directories[.](#7.sentence-1)
[8](#8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16615)
The order of directory entries obtained by dereferencing successive
increments of a directory_iterator is unspecified[.](#8.sentence-1)
[9](#9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16619)
Constructors and non-const directory_iterator member functions
store the values of any cached attributes ([[fs.class.directory.entry]](fs.class.directory.entry "31.12.10 Class directory_­entry"))
in the directory_entry element returned by operator*()[.](#9.sentence-1)
directory_iterator member functions shall not directly or indirectly call
any directory_entry refresh function[.](#9.sentence-2)
[*Note [2](#note-2)*:
The exact mechanism for storing cached attribute values is not exposed to users[.](#9.sentence-3)
— *end note*]
[10](#10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16629)
[*Note [3](#note-3)*:
A path obtained by dereferencing a directory iterator might not actually exist;
it could be a symbolic link to a non-existent file[.](#10.sentence-1)
Recursively walking directory trees
for purposes of removing and renaming entries
might invalidate symbolic links that are being followed[.](#10.sentence-2)
— *end note*]
[11](#11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16638)
[*Note [4](#note-4)*:
If a file is removed from or added to a directory after the
construction of a directory_iterator for the directory, it is
unspecified whether or not subsequently incrementing the iterator will ever
result in an iterator referencing the removed or added directory entry[.](#11.sentence-1)
See
POSIX [readdir](http://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html)[.](#11.sentence-2)
— *end note*]

86
cppdraft/fs/class/file/status.md Normal file
View File

@@ -0,0 +1,86 @@
[fs.class.file.status]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.file.status)
### 31.12.9 Class file_status [fs.class.file.status]
#### [31.12.9.1](#general) General [[fs.class.file.status.general]](fs.class.file.status.general)
[🔗](#lib:file_status)
namespace std::filesystem {class file_status {public:// [[fs.file.status.cons]](#fs.file.status.cons "31.12.9.2 Constructors"), constructors and destructor file_status() noexcept : file_status(file_type::none) {}explicit file_status(file_type ft,
perms prms = perms::unknown) noexcept;
file_status(const file_status&) noexcept = default;
file_status(file_status&&) noexcept = default; ~file_status(); // assignments file_status& operator=(const file_status&) noexcept = default;
file_status& operator=(file_status&&) noexcept = default; // [[fs.file.status.mods]](#fs.file.status.mods "31.12.9.4 Modifiers"), modifiersvoid type(file_type ft) noexcept; void permissions(perms prms) noexcept; // [[fs.file.status.obs]](#fs.file.status.obs "31.12.9.3 Observers"), observers file_type type() const noexcept;
perms permissions() const noexcept; friend bool operator==(const file_status& lhs, const file_status& rhs) noexcept{ return lhs.type() == rhs.type() && lhs.permissions() == rhs.permissions(); }};}
[1](#general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15970)
An object of type file_status stores information about the type
and permissions of a file[.](#general-1.sentence-1)
#### [31.12.9.2](#fs.file.status.cons) Constructors [[fs.file.status.cons]](fs.file.status.cons)
[🔗](#lib:file_status,constructor)
`explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
`
[1](#fs.file.status.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15981)
*Postconditions*: type() == ft and permissions() == prms[.](#fs.file.status.cons-1.sentence-1)
#### [31.12.9.3](#fs.file.status.obs) Observers [[fs.file.status.obs]](fs.file.status.obs)
[🔗](#lib:type,file_status)
`file_type type() const noexcept;
`
[1](#fs.file.status.obs-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15994)
*Returns*: The value of type() specified by the postconditions of the most recent call to a constructor, operator=, or type(file_type) function[.](#fs.file.status.obs-1.sentence-1)
[🔗](#lib:permissions,file_status)
`perms permissions() const noexcept;
`
[2](#fs.file.status.obs-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16006)
*Returns*: The value of permissions() specified by the postconditions of the most recent call to a constructor, operator=, or permissions(perms) function[.](#fs.file.status.obs-2.sentence-1)
#### [31.12.9.4](#fs.file.status.mods) Modifiers [[fs.file.status.mods]](fs.file.status.mods)
[🔗](#lib:type,file_status_)
`void type(file_type ft) noexcept;
`
[1](#fs.file.status.mods-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16020)
*Postconditions*: type() == ft[.](#fs.file.status.mods-1.sentence-1)
[🔗](#lib:permissions,file_status_)
`void permissions(perms prms) noexcept;
`
[2](#fs.file.status.mods-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16031)
*Postconditions*: permissions() == prms[.](#fs.file.status.mods-2.sentence-1)

25
cppdraft/fs/class/file/status/general.md Normal file
View File

@@ -0,0 +1,25 @@
[fs.class.file.status.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.file.status.general)
### 31.12.9 Class file_status [[fs.class.file.status]](fs.class.file.status#general)
#### 31.12.9.1 General [fs.class.file.status.general]
[🔗](#lib:file_status)
namespace std::filesystem {class file_status {public:// [[fs.file.status.cons]](fs.file.status.cons "31.12.9.2 Constructors"), constructors and destructor file_status() noexcept : file_status(file_type::none) {}explicit file_status(file_type ft,
perms prms = perms::unknown) noexcept;
file_status(const file_status&) noexcept = default;
file_status(file_status&&) noexcept = default; ~file_status(); // assignments file_status& operator=(const file_status&) noexcept = default;
file_status& operator=(file_status&&) noexcept = default; // [[fs.file.status.mods]](fs.file.status.mods "31.12.9.4 Modifiers"), modifiersvoid type(file_type ft) noexcept; void permissions(perms prms) noexcept; // [[fs.file.status.obs]](fs.file.status.obs "31.12.9.3 Observers"), observers file_type type() const noexcept;
perms permissions() const noexcept; friend bool operator==(const file_status& lhs, const file_status& rhs) noexcept{ return lhs.type() == rhs.type() && lhs.permissions() == rhs.permissions(); }};}
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15970)
An object of type file_status stores information about the type
and permissions of a file[.](#1.sentence-1)

155
cppdraft/fs/class/filesystem/error.md Normal file
View File

@@ -0,0 +1,155 @@
[fs.class.filesystem.error]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.filesystem.error)
### 31.12.7 Class filesystem_error [fs.class.filesystem.error]
#### [31.12.7.1](#general) General [[fs.class.filesystem.error.general]](fs.class.filesystem.error.general)
[🔗](#lib:filesystem_error)
namespace std::filesystem {class filesystem_error : public system_error {public: filesystem_error(const string& what_arg, error_code ec);
filesystem_error(const string& what_arg, const path& p1, error_code ec);
filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec); const path& path1() const noexcept; const path& path2() const noexcept; const char* what() const noexcept override; };}
[1](#general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15591)
The class filesystem_error defines the type of
objects thrown as exceptions to report file system errors from functions described in
subclause [[filesystems]](filesystems "31.12 File systems")[.](#general-1.sentence-1)
#### [31.12.7.2](#fs.filesystem.error.members) Members [[fs.filesystem.error.members]](fs.filesystem.error.members)
[1](#fs.filesystem.error.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15598)
Constructors are provided that store zero, one, or two paths associated with
an error[.](#fs.filesystem.error.members-1.sentence-1)
[🔗](#lib:filesystem_error,constructor)
`filesystem_error(const string& what_arg, error_code ec);
`
[2](#fs.filesystem.error.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15608)
*Postconditions*:
- [(2.1)](#fs.filesystem.error.members-2.1)
code() == ec is true,
- [(2.2)](#fs.filesystem.error.members-2.2)
path1().empty() is true,
- [(2.3)](#fs.filesystem.error.members-2.3)
path2().empty() is true, and
- [(2.4)](#fs.filesystem.error.members-2.4)
string_view(what()).find(what_arg.c_str()) != string_view​::​npos is true[.](#fs.filesystem.error.members-2.sentence-1)
[🔗](#lib:filesystem_error,constructor_)
`filesystem_error(const string& what_arg, const path& p1, error_code ec);
`
[3](#fs.filesystem.error.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15624)
*Postconditions*:
- [(3.1)](#fs.filesystem.error.members-3.1)
code() == ec is true,
- [(3.2)](#fs.filesystem.error.members-3.2)
path1() returns a reference to the stored copy of p1,
- [(3.3)](#fs.filesystem.error.members-3.3)
path2().empty() is true, and
- [(3.4)](#fs.filesystem.error.members-3.4)
string_view(what()).find(what_arg.c_str()) != string_view​::​npos is true[.](#fs.filesystem.error.members-3.sentence-1)
[🔗](#lib:filesystem_error,constructor__)
`filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
`
[4](#fs.filesystem.error.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15640)
*Postconditions*:
- [(4.1)](#fs.filesystem.error.members-4.1)
code() == ec,
- [(4.2)](#fs.filesystem.error.members-4.2)
path1() returns a reference to the stored copy of p1,
- [(4.3)](#fs.filesystem.error.members-4.3)
path2() returns a reference to the stored copy of p2, and
- [(4.4)](#fs.filesystem.error.members-4.4)
string_view(what()).find(what_arg.c_str()) != string_view​::​npos[.](#fs.filesystem.error.members-4.sentence-1)
[🔗](#lib:path1,filesystem_error)
`const path& path1() const noexcept;
`
[5](#fs.filesystem.error.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15656)
*Returns*: A reference to the copy of p1 stored by the
constructor, or, if none, an empty path[.](#fs.filesystem.error.members-5.sentence-1)
[🔗](#lib:path2,filesystem_error)
`const path& path2() const noexcept;
`
[6](#fs.filesystem.error.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15668)
*Returns*: A reference to the copy of p2 stored by the
constructor, or, if none, an empty path[.](#fs.filesystem.error.members-6.sentence-1)
[🔗](#lib:what,filesystem_error)
`const char* what() const noexcept override;
`
[7](#fs.filesystem.error.members-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15680)
*Returns*: An ntbs that incorporates
the what_arg argument supplied to the constructor[.](#fs.filesystem.error.members-7.sentence-1)
The exact format is unspecified[.](#fs.filesystem.error.members-7.sentence-2)
Implementations should include
the system_error​::​what() string and
the pathnames of path1 and path2 in the native format in the returned string[.](#fs.filesystem.error.members-7.sentence-3)

23
cppdraft/fs/class/filesystem/error/general.md Normal file
View File

@@ -0,0 +1,23 @@
[fs.class.filesystem.error.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.filesystem.error.general)
### 31.12.7 Class filesystem_error [[fs.class.filesystem.error]](fs.class.filesystem.error#general)
#### 31.12.7.1 General [fs.class.filesystem.error.general]
[🔗](#lib:filesystem_error)
namespace std::filesystem {class filesystem_error : public system_error {public: filesystem_error(const string& what_arg, error_code ec);
filesystem_error(const string& what_arg, const path& p1, error_code ec);
filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec); const path& path1() const noexcept; const path& path2() const noexcept; const char* what() const noexcept override; };}
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L15591)
The class filesystem_error defines the type of
objects thrown as exceptions to report file system errors from functions described in
subclause [[filesystems]](filesystems "31.12 File systems")[.](#1.sentence-1)

2162
cppdraft/fs/class/path.md Normal file
View File

File diff suppressed because it is too large Load Diff

170
cppdraft/fs/class/path/general.md Normal file
View File

@@ -0,0 +1,170 @@
[fs.class.path.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.path.general)
### 31.12.6 Class path [[fs.class.path]](fs.class.path#general)
#### 31.12.6.1 General [fs.class.path.general]
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13559)
An object of class path represents a path
and contains a pathname[.](#1.sentence-1)
Such an object is concerned only with the lexical and syntactic aspects
of a path[.](#1.sentence-2)
The path does not necessarily exist in external storage, and the
pathname is not necessarily valid for the current operating
system or for a particular file system[.](#1.sentence-3)
[2](#2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13567)
[*Note [1](#note-1)*:
Class path is used to support the differences
between the string types used by different operating systems
to represent pathnames,
and to perform conversions between encodings when necessary[.](#2.sentence-1)
— *end note*]
[3](#3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13575)
A [*path*](#def:path "31.12.6.1 General [fs.class.path.general]") is
a sequence of elements that identify
the location of a file within a filesystem[.](#3.sentence-1)
The elements are the[*root-name*](fs.path.generic#nt:root-name "31.12.6.2 Generic pathname format [fs.path.generic]")opt,[*root-directory*](fs.path.generic#nt:root-directory "31.12.6.2 Generic pathname format [fs.path.generic]")opt,
and an optional sequence of [*filename*](fs.path.generic#nt:filename "31.12.6.2 Generic pathname format [fs.path.generic]")*s* ([[fs.path.generic]](fs.path.generic "31.12.6.2 Generic pathname format"))[.](#3.sentence-2)
The maximum number of elements in the sequence is
operating system dependent ([[fs.conform.os]](fs.conform.os "31.12.2.3 Operating system dependent behavior conformance"))[.](#3.sentence-3)
[4](#4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13586)
An [*absolute path*](#def:path,absolute "31.12.6.1 General [fs.class.path.general]") is a path that unambiguously
identifies the location of a file without reference to an additional starting
location[.](#4.sentence-1)
The elements of a path that determine if it is absolute are
operating system dependent[.](#4.sentence-2)
A [*relative path*](#def:path,relative "31.12.6.1 General [fs.class.path.general]") is
a path that is not absolute, and as such, only unambiguously
identifies the location of a file when resolved relative to
an implied starting location[.](#4.sentence-3)
The elements of a path that determine if it is
relative are operating system dependent[.](#4.sentence-4)
[*Note [2](#note-2)*:
Pathnames “.” and “..” are relative paths[.](#4.sentence-5)
— *end note*]
[5](#5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13600)
A [*pathname*](#def:pathname "31.12.6.1 General [fs.class.path.general]") is
a character string that represents the name of a path[.](#5.sentence-1)
Pathnames are
formatted according to the generic pathname format grammar ([[fs.path.generic]](fs.path.generic "31.12.6.2 Generic pathname format"))
or according to an
operating system dependent[*native pathname format*](#def:native_pathname_format "31.12.6.1 General [fs.class.path.general]") accepted by the host operating system[.](#5.sentence-2)
[6](#6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13608)
[*Pathname resolution*](#def:pathname_resolution "31.12.6.1 General [fs.class.path.general]") is the operating system dependent mechanism for resolving
a pathname to a particular file in a file hierarchy[.](#6.sentence-1)
There may be multiple
pathnames that resolve to the same file[.](#6.sentence-2)
[*Example [1](#example-1)*:
For POSIX-based operating systems,
this mechanism is specified in POSIX, section 4.12, Pathname resolution[.](#6.sentence-3)
— *end example*]
namespace std::filesystem {class path {public:using value_type = *see below*; using string_type = basic_string<value_type>; static constexpr value_type preferred_separator = *see below*; // [[fs.enum.path.format]](fs.enum.path.format "31.12.8.1 Enum path​::​format"), enumeration formatenum format; // [[fs.path.construct]](fs.path.construct "31.12.6.5.1 Constructors"), constructors and destructor path() noexcept;
path(const path& p);
path(path&& p) noexcept;
path(string_type&& source, format fmt = auto_format); template<class Source> path(const Source& source, format fmt = auto_format); template<class InputIterator> path(InputIterator first, InputIterator last, format fmt = auto_format); template<class Source> path(const Source& source, const locale& loc, format fmt = auto_format); template<class InputIterator> path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format); ~path(); // [[fs.path.assign]](fs.path.assign "31.12.6.5.2 Assignments"), assignments path& operator=(const path& p);
path& operator=(path&& p) noexcept;
path& operator=(string_type&& source);
path& assign(string_type&& source); template<class Source> path& operator=(const Source& source); template<class Source> path& assign(const Source& source); template<class InputIterator> path& assign(InputIterator first, InputIterator last); // [[fs.path.append]](fs.path.append "31.12.6.5.3 Appends"), appends path& operator/=(const path& p); template<class Source> path& operator/=(const Source& source); template<class Source> path& append(const Source& source); template<class InputIterator> path& append(InputIterator first, InputIterator last); // [[fs.path.concat]](fs.path.concat "31.12.6.5.4 Concatenation"), concatenation path& operator+=(const path& x);
path& operator+=(const string_type& x);
path& operator+=(basic_string_view<value_type> x);
path& operator+=(const value_type* x);
path& operator+=(value_type x); template<class Source> path& operator+=(const Source& x); template<class EcharT> path& operator+=(EcharT x); template<class Source> path& concat(const Source& x); template<class InputIterator> path& concat(InputIterator first, InputIterator last); // [[fs.path.modifiers]](fs.path.modifiers "31.12.6.5.5 Modifiers"), modifiersvoid clear() noexcept;
path& make_preferred();
path& remove_filename();
path& replace_filename(const path& replacement);
path& replace_extension(const path& replacement = path()); void swap(path& rhs) noexcept; // [[fs.path.nonmember]](fs.path.nonmember "31.12.6.8 Non-member functions"), non-member operatorsfriend bool operator==(const path& lhs, const path& rhs) noexcept; friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept; friend path operator/(const path& lhs, const path& rhs); // [[fs.path.native.obs]](fs.path.native.obs "31.12.6.5.6 Native format observers"), native format observersconst string_type& native() const noexcept; const value_type* c_str() const noexcept; operator string_type() const; template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;
std::string display_string() const;
std::string system_encoded_string() const;
std::wstring wstring() const;
std::u8string u8string() const;
std::u16string u16string() const;
std::u32string u32string() const; // [[fs.path.generic.obs]](fs.path.generic.obs "31.12.6.5.7 Generic format observers"), generic format observerstemplate<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;
std::string generic_display_string() const;
std::string generic_system_encoded_string() const;
std::wstring generic_wstring() const;
std::u8string generic_u8string() const;
std::u16string generic_u16string() const;
std::u32string generic_u32string() const; // [[fs.path.compare]](fs.path.compare "31.12.6.5.8 Compare"), compareint compare(const path& p) const noexcept; int compare(const string_type& s) const; int compare(basic_string_view<value_type> s) const; int compare(const value_type* s) const; // [[fs.path.decompose]](fs.path.decompose "31.12.6.5.9 Decomposition"), decomposition path root_name() const;
path root_directory() const;
path root_path() const;
path relative_path() const;
path parent_path() const;
path filename() const;
path stem() const;
path extension() const; // [[fs.path.query]](fs.path.query "31.12.6.5.10 Query"), querybool empty() const noexcept; bool has_root_name() const; bool has_root_directory() const; bool has_root_path() const; bool has_relative_path() const; bool has_parent_path() const; bool has_filename() const; bool has_stem() const; bool has_extension() const; bool is_absolute() const; bool is_relative() const; // [[fs.path.gen]](fs.path.gen "31.12.6.5.11 Generation"), generation path lexically_normal() const;
path lexically_relative(const path& base) const;
path lexically_proximate(const path& base) const; // [[fs.path.itr]](fs.path.itr "31.12.6.6 Iterators"), iteratorsclass iterator; using const_iterator = iterator;
iterator begin() const;
iterator end() const; // [[fs.path.io]](fs.path.io "31.12.6.7 Inserter and extractor"), path inserter and extractortemplate<class charT, class traits>friend basic_ostream<charT, traits>&operator<<(basic_ostream<charT, traits>& os, const path& p); template<class charT, class traits>friend basic_istream<charT, traits>&operator>>(basic_istream<charT, traits>& is, path& p); };}
[7](#7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13775)
value_type is a typedef for the
operating system dependent encoded character type used to represent pathnames[.](#7.sentence-1)
[8](#8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13780)
The value of the preferred_separator member
is the operating system dependent [*preferred-separator*](fs.path.generic#nt:preferred-separator "31.12.6.2 Generic pathname format [fs.path.generic]") character ([[fs.path.generic]](fs.path.generic "31.12.6.2 Generic pathname format"))[.](#8.sentence-1)
[9](#9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13784)
[*Example [2](#example-2)*:
For POSIX-based operating systems,value_type is char andpreferred_separator is the slash character ('/')[.](#9.sentence-1)
For Windows-based operating systems,value_type is wchar_t andpreferred_separator is the backslash character (L'\\')[.](#9.sentence-2)
— *end example*]

392
cppdraft/fs/class/rec/dir/itr.md Normal file
View File

@@ -0,0 +1,392 @@
[fs.class.rec.dir.itr]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.rec.dir.itr)
### 31.12.12 Class recursive_directory_iterator [fs.class.rec.dir.itr]
#### [31.12.12.1](#general) General [[fs.class.rec.dir.itr.general]](fs.class.rec.dir.itr.general)
[1](#general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16779)
An object of type recursive_directory_iterator provides an iterator for
a sequence of directory_entry elements representing the files in a
directory or in an implementation-defined directory-like file
type, and its subdirectories[.](#general-1.sentence-1)
namespace std::filesystem {class recursive_directory_iterator {public:using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 Members"), constructors and destructor recursive_directory_iterator() noexcept; explicit recursive_directory_iterator(const path& p);
recursive_directory_iterator(const path& p, directory_options options);
recursive_directory_iterator(const path& p, directory_options options,
error_code& ec);
recursive_directory_iterator(const path& p, error_code& ec);
recursive_directory_iterator(const recursive_directory_iterator& rhs);
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept; ~recursive_directory_iterator(); // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 Members"), observers directory_options options() const; int depth() const; bool recursion_pending() const; const directory_entry& operator*() const; const directory_entry* operator->() const; // [[fs.rec.dir.itr.members]](#fs.rec.dir.itr.members "31.12.12.2 Members"), modifiers recursive_directory_iterator&operator=(const recursive_directory_iterator& rhs);
recursive_directory_iterator&operator=(recursive_directory_iterator&& rhs) noexcept;
recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec); void pop(); void pop(error_code& ec); void disable_recursion_pending(); bool operator==(default_sentinel_t) const noexcept {return *this == recursive_directory_iterator(); }// other members as required by [[input.iterators]](input.iterators "24.3.5.3 Input iterators"), input iterators};}
[2](#general-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16836)
Calling options, depth, recursion_pending,pop or disable_recursion_pending on an iterator that is not dereferenceable results in undefined behavior[.](#general-2.sentence-1)
[3](#general-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16841)
The behavior of a recursive_directory_iterator is the same
as a directory_iterator unless otherwise specified[.](#general-3.sentence-1)
[4](#general-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16845)
[*Note [1](#general-note-1)*:
If the directory structure being iterated over contains cycles
then it is possible that the end iterator is unreachable[.](#general-4.sentence-1)
— *end note*]
#### [31.12.12.2](#fs.rec.dir.itr.members) Members [[fs.rec.dir.itr.members]](fs.rec.dir.itr.members)
[🔗](#lib:recursive_directory_iterator,constructor)
`recursive_directory_iterator() noexcept;
`
[1](#fs.rec.dir.itr.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16859)
*Effects*: Constructs the end iterator[.](#fs.rec.dir.itr.members-1.sentence-1)
[🔗](#lib:recursive_directory_iterator,constructor_)
`explicit recursive_directory_iterator(const path& p);
recursive_directory_iterator(const path& p, directory_options options);
recursive_directory_iterator(const path& p, directory_options options, error_code& ec);
recursive_directory_iterator(const path& p, error_code& ec);
`
[2](#fs.rec.dir.itr.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16873)
*Effects*: Constructs an iterator representing the first
entry in the directory to which p resolves, if any; otherwise, the end iterator[.](#fs.rec.dir.itr.members-2.sentence-1)
However, if(options & directory_options::skip_permission_denied) != directory_options::none and construction encounters an error indicating
that permission to access p is denied, constructs the end iterator
and does not report an error[.](#fs.rec.dir.itr.members-2.sentence-2)
[3](#fs.rec.dir.itr.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16885)
*Postconditions*: options() == options for the signatures with adirectory_options argument, otherwise options() == directory_options​::​none[.](#fs.rec.dir.itr.members-3.sentence-1)
[4](#fs.rec.dir.itr.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16890)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-4.sentence-1)
[5](#fs.rec.dir.itr.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16894)
[*Note [1](#fs.rec.dir.itr.members-note-1)*:
Use recursive_directory_iterator(".") rather than recursive_directory_iterator("") to iterate over the current directory[.](#fs.rec.dir.itr.members-5.sentence-1)
— *end note*]
[6](#fs.rec.dir.itr.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16901)
[*Note [2](#fs.rec.dir.itr.members-note-2)*:
By default, recursive_directory_iterator does not
follow directory symlinks[.](#fs.rec.dir.itr.members-6.sentence-1)
To follow directory symlinks, specify options asdirectory_options​::​follow_directory_symlink[.](#fs.rec.dir.itr.members-6.sentence-2)
— *end note*]
[🔗](#lib:recursive_directory_iterator,constructor__)
`recursive_directory_iterator(const recursive_directory_iterator& rhs);
`
[7](#fs.rec.dir.itr.members-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16915)
*Postconditions*:
- [(7.1)](#fs.rec.dir.itr.members-7.1)
options() == rhs.options()
- [(7.2)](#fs.rec.dir.itr.members-7.2)
depth() == rhs.depth()
- [(7.3)](#fs.rec.dir.itr.members-7.3)
recursion_pending() == rhs.recursion_pending()
[🔗](#lib:recursive_directory_iterator,constructor___)
`recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
`
[8](#fs.rec.dir.itr.members-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16930)
*Postconditions*: options(), depth(),
and recursion_pending() have the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call[.](#fs.rec.dir.itr.members-8.sentence-1)
[🔗](#lib:operator=,recursive_directory_iterator)
`recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
`
[9](#fs.rec.dir.itr.members-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16944)
*Effects*: If *this and rhs are the same
object, the member has no effect[.](#fs.rec.dir.itr.members-9.sentence-1)
[10](#fs.rec.dir.itr.members-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16949)
*Postconditions*:
- [(10.1)](#fs.rec.dir.itr.members-10.1)
options() == rhs.options()
- [(10.2)](#fs.rec.dir.itr.members-10.2)
depth() == rhs.depth()
- [(10.3)](#fs.rec.dir.itr.members-10.3)
recursion_pending() == rhs.recursion_pending()
[11](#fs.rec.dir.itr.members-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16957)
*Returns*: *this[.](#fs.rec.dir.itr.members-11.sentence-1)
[🔗](#lib:operator=,recursive_directory_iterator_)
`recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
`
[12](#fs.rec.dir.itr.members-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16968)
*Effects*: If *this and rhs are the same
object, the member has no effect[.](#fs.rec.dir.itr.members-12.sentence-1)
[13](#fs.rec.dir.itr.members-13)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16973)
*Postconditions*: options(), depth(),
and recursion_pending() have the values that rhs.options(),rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call[.](#fs.rec.dir.itr.members-13.sentence-1)
[14](#fs.rec.dir.itr.members-14)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16979)
*Returns*: *this[.](#fs.rec.dir.itr.members-14.sentence-1)
[🔗](#lib:options,recursive_directory_iterator)
`directory_options options() const;
`
[15](#fs.rec.dir.itr.members-15)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16990)
*Returns*: The value of the argument passed to the constructor for theoptions parameter, if present, otherwisedirectory_options​::​none[.](#fs.rec.dir.itr.members-15.sentence-1)
[16](#fs.rec.dir.itr.members-16)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16996)
*Throws*: Nothing[.](#fs.rec.dir.itr.members-16.sentence-1)
[🔗](#lib:depth,recursive_directory_iterator)
`int depth() const;
`
[17](#fs.rec.dir.itr.members-17)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17007)
*Returns*: The current depth of the directory tree being traversed[.](#fs.rec.dir.itr.members-17.sentence-1)
[*Note [3](#fs.rec.dir.itr.members-note-3)*:
The initial directory is depth 0, its immediate subdirectories are depth 1,
and so forth[.](#fs.rec.dir.itr.members-17.sentence-2)
— *end note*]
[18](#fs.rec.dir.itr.members-18)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17015)
*Throws*: Nothing[.](#fs.rec.dir.itr.members-18.sentence-1)
[🔗](#lib:recursion_pending,recursive_directory_iterator)
`bool recursion_pending() const;
`
[19](#fs.rec.dir.itr.members-19)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17026)
*Returns*: true if disable_recursion_pending() has not been called subsequent to the prior construction or increment
operation, otherwise false[.](#fs.rec.dir.itr.members-19.sentence-1)
[20](#fs.rec.dir.itr.members-20)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17032)
*Throws*: Nothing[.](#fs.rec.dir.itr.members-20.sentence-1)
[🔗](#lib:increment,recursive_directory_iterator)
`recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec);
`
[21](#fs.rec.dir.itr.members-21)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17045)
*Effects*: As specified for the prefix increment operation of[Input iterators](input.iterators "24.3.5.3 Input iterators [input.iterators]"),
except that:
- [(21.1)](#fs.rec.dir.itr.members-21.1)
If there are no more entries at the current depth, then if depth() != 0 iteration over the parent directory resumes; otherwise *this = recursive_directory_iterator().
- [(21.2)](#fs.rec.dir.itr.members-21.2)
Otherwise ifrecursion_pending() && is_directory((*this)->status()) &&(!is_symlink((*this)->symlink_status()) ||(options() & directory_options::follow_directory_symlink) != directory_options::none) then either directory (*this)->path() is recursively iterated into or,
if(options() & directory_options::skip_permission_denied) != directory_options::none and an error occurs indicating that permission to access directory (*this)->path() is denied,
then directory (*this)->path() is
treated as an empty directory and no error is reported.
[22](#fs.rec.dir.itr.members-22)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17070)
*Returns*: *this[.](#fs.rec.dir.itr.members-22.sentence-1)
[23](#fs.rec.dir.itr.members-23)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17074)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-23.sentence-1)
[🔗](#lib:pop,recursive_directory_iterator)
`void pop();
void pop(error_code& ec);
`
[24](#fs.rec.dir.itr.members-24)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17086)
*Effects*: If depth() == 0, set *this to recursive_directory_iterator()[.](#fs.rec.dir.itr.members-24.sentence-1)
Otherwise, cease iteration of the directory currently being
iterated over, and continue iteration over the parent directory[.](#fs.rec.dir.itr.members-24.sentence-2)
[25](#fs.rec.dir.itr.members-25)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17092)
*Throws*: As specified in [[fs.err.report]](fs.err.report "31.12.5 Error reporting")[.](#fs.rec.dir.itr.members-25.sentence-1)
[26](#fs.rec.dir.itr.members-26)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17097)
*Remarks*: Any copies of the previous value of *this are no longer required
to be dereferenceable nor to be in the domain of ==[.](#fs.rec.dir.itr.members-26.sentence-1)
[🔗](#lib:disable_recursion_pending,recursive_directory_iterator)
`void disable_recursion_pending();
`
[27](#fs.rec.dir.itr.members-27)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17109)
*Postconditions*: recursion_pending() == false[.](#fs.rec.dir.itr.members-27.sentence-1)
[28](#fs.rec.dir.itr.members-28)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17113)
[*Note [4](#fs.rec.dir.itr.members-note-4)*:
disable_recursion_pending() is used to prevent
unwanted recursion into a directory[.](#fs.rec.dir.itr.members-28.sentence-1)
— *end note*]
#### [31.12.12.3](#fs.rec.dir.itr.nonmembers) Non-member functions [[fs.rec.dir.itr.nonmembers]](fs.rec.dir.itr.nonmembers)
[1](#fs.rec.dir.itr.nonmembers-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17122)
These functions enable use of recursive_directory_iterator with range-based for statements[.](#fs.rec.dir.itr.nonmembers-1.sentence-1)
[🔗](#lib:begin,recursive_directory_iterator)
`recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
`
[2](#fs.rec.dir.itr.nonmembers-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17132)
*Returns*: iter[.](#fs.rec.dir.itr.nonmembers-2.sentence-1)
[🔗](#lib:end,recursive_directory_iterator)
`recursive_directory_iterator end(recursive_directory_iterator) noexcept;
`
[3](#fs.rec.dir.itr.nonmembers-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L17143)
*Returns*: recursive_directory_iterator()[.](#fs.rec.dir.itr.nonmembers-3.sentence-1)

54
cppdraft/fs/class/rec/dir/itr/general.md Normal file
View File

@@ -0,0 +1,54 @@
[fs.class.rec.dir.itr.general]
# 31 Input/output library [[input.output]](./#input.output)
## 31.12 File systems [[filesystems]](filesystems#fs.class.rec.dir.itr.general)
### 31.12.12 Class recursive_directory_iterator [[fs.class.rec.dir.itr]](fs.class.rec.dir.itr#general)
#### 31.12.12.1 General [fs.class.rec.dir.itr.general]
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16779)
An object of type recursive_directory_iterator provides an iterator for
a sequence of directory_entry elements representing the files in a
directory or in an implementation-defined directory-like file
type, and its subdirectories[.](#1.sentence-1)
namespace std::filesystem {class recursive_directory_iterator {public:using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [[fs.rec.dir.itr.members]](fs.rec.dir.itr.members "31.12.12.2 Members"), constructors and destructor recursive_directory_iterator() noexcept; explicit recursive_directory_iterator(const path& p);
recursive_directory_iterator(const path& p, directory_options options);
recursive_directory_iterator(const path& p, directory_options options,
error_code& ec);
recursive_directory_iterator(const path& p, error_code& ec);
recursive_directory_iterator(const recursive_directory_iterator& rhs);
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept; ~recursive_directory_iterator(); // [[fs.rec.dir.itr.members]](fs.rec.dir.itr.members "31.12.12.2 Members"), observers directory_options options() const; int depth() const; bool recursion_pending() const; const directory_entry& operator*() const; const directory_entry* operator->() const; // [[fs.rec.dir.itr.members]](fs.rec.dir.itr.members "31.12.12.2 Members"), modifiers recursive_directory_iterator&operator=(const recursive_directory_iterator& rhs);
recursive_directory_iterator&operator=(recursive_directory_iterator&& rhs) noexcept;
recursive_directory_iterator& operator++();
recursive_directory_iterator& increment(error_code& ec); void pop(); void pop(error_code& ec); void disable_recursion_pending(); bool operator==(default_sentinel_t) const noexcept {return *this == recursive_directory_iterator(); }// other members as required by [[input.iterators]](input.iterators "24.3.5.3 Input iterators"), input iterators};}
[2](#2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16836)
Calling options, depth, recursion_pending,pop or disable_recursion_pending on an iterator that is not dereferenceable results in undefined behavior[.](#2.sentence-1)
[3](#3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16841)
The behavior of a recursive_directory_iterator is the same
as a directory_iterator unless otherwise specified[.](#3.sentence-1)
[4](#4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L16845)
[*Note [1](#note-1)*:
If the directory structure being iterated over contains cycles
then it is possible that the end iterator is unreachable[.](#4.sentence-1)
— *end note*]