[fs.class.directory_entry] - C++14 → C++17

Files changed (1) hide show

tmp/tmptyhbcb11/{from.md → to.md} +367 -0

tmp/tmptyhbcb11/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,367 @@

+### Class `directory_entry` <a id="fs.class.directory_entry">[[fs.class.directory_entry]]</a>
+``` cpp
+namespace std::filesystem {
+  class directory_entry {
+  public:
+    // [fs.dir.entry.cons], constructors and destructor
+    directory_entry() noexcept = default;
+    directory_entry(const directory_entry&) = default;
+    directory_entry(directory_entry&&) noexcept = default;
+    explicit directory_entry(const path& p);
+    directory_entry(const 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], modifiers
+    void assign(const path& p);
+    void assign(const path& p, error_code& ec);
+    void replace_filename(const path& p);
+    void replace_filename(const path& p, error_code& ec);
+    void refresh();
+    void refresh(error_code& ec) noexcept;
+    // [fs.dir.entry.obs], observers
+    const path& path() const noexcept;
+    operator const 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;
+    bool operator==(const directory_entry& rhs) const noexcept;
+    bool operator!=(const directory_entry& rhs) const noexcept;
+    bool operator<=(const directory_entry& rhs) const noexcept;
+    bool operator> (const directory_entry& rhs) const noexcept;
+    bool operator>=(const directory_entry& rhs) const noexcept;
+  private:
+    path pathobject;                 // exposition only
+    friend class directory_iterator; // exposition only
+  };
+}
+```
+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.
+Implementations are encouraged to 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]]). Such stored
+file attribute values are said to be *cached*.
+[*Note 1*: For purposes of exposition, class `directory_iterator` (
+[[fs.class.directory_iterator]]) is shown above as a friend of class
+`directory_entry`. Friendship allows the `directory_iterator`
+implementation to cache already available attribute values directly into
+a `directory_entry` object without the cost of an unneeded call to
+`refresh()`. — *end note*]
+[*Example 1*:
+``` cpp
+using namespace std::filesystem;
+// use possibly cached last write time to minimize disk accesses
+for (auto&& x : directory_iterator("."))
+{
+  std::cout << x.path() << " " << x.last_write_time() << std::endl;
+}
+// call refresh() to refresh a stale cache
+for (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. 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. The code is portable to any
+implementation, regardless of whether or not it employs caching.
+— *end example*]
+#### `directory_entry` constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
+``` cpp
+explicit directory_entry(const path& p);
+directory_entry(const path& p, error_code& ec);
+```
+*Effects:* Constructs an object of type `directory_entry`, then
+`refresh()` or `refresh(ec)`, respectively.
+*Postconditions:* `path() == p` if no error occurs, otherwise
+`path() == std::filesystem::path()`.
+*Throws:* As specified in  [[fs.err.report]].
+#### `directory_entry` modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
+``` cpp
+void assign(const path& p);
+void assign(const path& p, error_code& ec);
+```
+*Effects:* Equivalent to `pathobject = p`, then `refresh()` or
+`refresh(ec)`, respectively. If an error occurs, the values of any
+cached attributes are unspecified.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+void replace_filename(const path& p);
+void replace_filename(const path& p, error_code& ec);
+```
+*Effects:* Equivalent to `pathobject.replace_filename(p)`, then
+`refresh()` or `refresh(ec)`, respectively. If an error occurs, the
+values of any cached attributes are unspecified.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+void refresh();
+void refresh(error_code& ec) noexcept;
+```
+*Effects:* Stores the current values of any cached attributes of the
+file `p` resolves to. If an error occurs, an error is
+reported ([[fs.err.report]]) and the values of any cached attributes
+are unspecified.
+*Throws:* As specified in  [[fs.err.report]].
+[*Note 1*: Implementations of
+`directory_iterator` ([[fs.class.directory_iterator]]) are prohibited
+from directly or indirectly calling the `refresh` function since it must
+access the external file system, and the objective of caching is to
+avoid unnecessary file system accesses. — *end note*]
+#### `directory_entry` observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
+Unqualified function names in the *Returns:* elements of the
+`directory_entry` observers described below refer to members of the
+`std::filesystem` namespace.
+``` cpp
+const path& path() const noexcept;
+operator const path&() const noexcept;
+```
+*Returns:* `pathobject`.
+``` cpp
+bool exists() const;
+bool exists(error_code& ec) const noexcept;
+```
+*Returns:* `exists(this->status())` or `exists(this->status(), ec)`,
+respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_block_file() const;
+bool is_block_file(error_code& ec) const noexcept;
+```
+*Returns:* `is_block_file(this->status())` or
+`is_block_file(this->status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_character_file() const;
+bool is_character_file(error_code& ec) const noexcept;
+```
+*Returns:* `is_character_file(this->status())` or
+`is_character_file(this->status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_directory() const;
+bool is_directory(error_code& ec) const noexcept;
+```
+*Returns:* `is_directory(this->status())` or
+`is_directory(this->status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_fifo() const;
+bool is_fifo(error_code& ec) const noexcept;
+```
+*Returns:* `is_fifo(this->status())` or `is_fifo(this->status(), ec)`,
+respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_other() const;
+bool is_other(error_code& ec) const noexcept;
+```
+*Returns:* `is_other(this->status())` or `is_other(this->status(), ec)`,
+respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_regular_file() const;
+bool is_regular_file(error_code& ec) const noexcept;
+```
+*Returns:* `is_regular_file(this->status())` or
+`is_regular_file(this->status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_socket() const;
+bool is_socket(error_code& ec) const noexcept;
+```
+*Returns:* `is_socket(this->status())` or
+`is_socket(this->status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool is_symlink() const;
+bool is_symlink(error_code& ec) const noexcept;
+```
+*Returns:* `is_symlink(this->symlink_status())` or
+`is_symlink(this->symlink_status(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+uintmax_t file_size() const;
+uintmax_t file_size(error_code& ec) const noexcept;
+```
+*Returns:* If cached, the file size attribute value. Otherwise,
+`file_size(path())` or `file_size(path(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+uintmax_t hard_link_count() const;
+uintmax_t hard_link_count(error_code& ec) const noexcept;
+```
+*Returns:* If cached, the hard link count attribute value. Otherwise,
+`hard_link_count(path())` or `hard_link_count(path(), ec)`,
+respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+file_time_type last_write_time() const;
+file_time_type last_write_time(error_code& ec) const noexcept;
+```
+*Returns:* If cached, the last write time attribute value. Otherwise,
+`last_write_time(path())` or `last_write_time(path(), ec)`,
+respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+file_status status() const;
+file_status status(error_code& ec) const noexcept;
+```
+*Returns:* If cached, the status attribute value. Otherwise,
+`status(path())` or `status(path(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+file_status symlink_status() const;
+file_status symlink_status(error_code& ec) const noexcept;
+```
+*Returns:* If cached, the symlink status attribute value. Otherwise,
+`symlink_status(path())` or `symlink_status(path(), ec)`, respectively.
+*Throws:* As specified in  [[fs.err.report]].
+``` cpp
+bool operator==(const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject == rhs.pathobject`.
+``` cpp
+bool operator!=(const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject != rhs.pathobject`.
+``` cpp
+bool operator< (const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject < rhs.pathobject`.
+``` cpp
+bool operator<=(const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject <= rhs.pathobject`.
+``` cpp
+bool operator> (const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject > rhs.pathobject`.
+``` cpp
+bool operator>=(const directory_entry& rhs) const noexcept;
+```
+*Returns:* `pathobject >= rhs.pathobject`.

Diff to HTML by rtfpessoa