cppdraft_translate/cppdraft/fs/class/directory/entry.md

[fs.class.directory.entry]

31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.10 Class directory_entry [fs.class.directory.entry]

31.12.10.1 General [fs.class.directory.entry.general]

🔗

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 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], 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], 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], 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

#

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.

2

#

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]).

Such stored file attribute values are said to be cached.

3

#

[Note 1:

directory_iterator can cache already available attribute values directly into a directory_entry object without the cost of a call to refresh().

— end note]

4

#

[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.

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]

31.12.10.2 Constructors [fs.dir.entry.cons]

🔗

explicit directory_entry(const filesystem::path& p); directory_entry(const filesystem::path& p, error_code& ec);

1

#

Effects: Calls refresh() or refresh(ec), respectively.

2

#

Postconditions: path() == p if no error occurs, otherwise path() == filesystem​::​path().

3

#

Throws: As specified in [fs.err.report].

31.12.10.3 Modifiers [fs.dir.entry.mods]

🔗

void assign(const filesystem::path& p); void assign(const filesystem::path& p, error_code& ec);

1

#

Effects: Equivalent to path-object = p, then refresh() or refresh(ec), respectively.

If an error occurs, the values of any cached attributes are unspecified.

2

#

Throws: As specified in [fs.err.report].

🔗

void replace_filename(const filesystem::path& p); void replace_filename(const filesystem::path& p, error_code& ec);

3

#

Effects: Equivalent to path-object.replace_filename(p), then refresh() or refresh(ec), respectively.

If an error occurs, the values of any cached attributes are unspecified.

4

#

Throws: As specified in [fs.err.report].

🔗

void refresh(); void refresh(error_code& ec) noexcept;

5

#

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.

6

#

Throws: As specified in [fs.err.report].

7

#

[Note 1:

Implementations of directory_iterator ([fs.class.directory.iterator]) are prohibited from directly or indirectly calling the refresh function as described in [fs.class.directory.iterator.general].

— end note]

31.12.10.4 Observers [fs.dir.entry.obs]

1

#

Unqualified function names in the Returns: elements of thedirectory_entry observers described below refer to members of thestd​::​filesystem namespace.

🔗

const filesystem::path& path() const noexcept; operator const filesystem::path&() const noexcept;

2

#

Returns: path-object.

🔗

bool exists() const; bool exists(error_code& ec) const noexcept;

3

#

Returns: exists(this->status()) or exists(this->status(ec)), respectively.

4

#

Throws: As specified in [fs.err.report].

🔗

bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept;

5

#

Returns: is_block_file(this->status()) or is_block_file(this->status(ec)), respectively.

6

#

Throws: As specified in [fs.err.report].

🔗

bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept;

7

#

Returns: is_character_file(this->status()) or is_character_file(this->status(ec)), respectively.

8

#

Throws: As specified in [fs.err.report].

🔗

bool is_directory() const; bool is_directory(error_code& ec) const noexcept;

9

#

Returns: is_directory(this->status()) or is_directory(this->status(ec)), respectively.

10

#

Throws: As specified in [fs.err.report].

🔗

bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept;

11

#

Returns: is_fifo(this->status()) or is_fifo(this->status(ec)), respectively.

12

#

Throws: As specified in [fs.err.report].

🔗

bool is_other() const; bool is_other(error_code& ec) const noexcept;

13

#

Returns: is_other(this->status()) or is_other(this->status(ec)), respectively.

14

#

Throws: As specified in [fs.err.report].

🔗

bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept;

15

#

Returns: is_regular_file(this->status()) or is_regular_file(this->status(ec)), respectively.

16

#

Throws: As specified in [fs.err.report].

🔗

bool is_socket() const; bool is_socket(error_code& ec) const noexcept;

17

#

Returns: is_socket(this->status()) or is_socket(this->status(ec)), respectively.

18

#

Throws: As specified in [fs.err.report].

🔗

bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept;

19

#

Returns: is_symlink(this->symlink_status()) or is_symlink(this->symlink_status(ec)), respectively.

20

#

Throws: As specified in [fs.err.report].

🔗

uintmax_t file_size() const; uintmax_t file_size(error_code& ec) const noexcept;

21

#

Returns: If cached, the file size attribute value.

Otherwise, file_size(path()) or file_size(path(), ec), respectively.

22

#

Throws: As specified in [fs.err.report].

🔗

uintmax_t hard_link_count() const; uintmax_t hard_link_count(error_code& ec) const noexcept;

23

#

Returns: If cached, the hard link count attribute value.

Otherwise, hard_link_count(path()) or hard_link_count(path(), ec), respectively.

24

#

Throws: As specified in [fs.err.report].

🔗

file_time_type last_write_time() const; file_time_type last_write_time(error_code& ec) const noexcept;

25

#

Returns: If cached, the last write time attribute value.

Otherwise, last_write_time(path()) or last_write_time(path(), ec), respectively.

26

#

Throws: As specified in [fs.err.report].

🔗

file_status status() const; file_status status(error_code& ec) const noexcept;

27

#

Returns: If cached, the status attribute value.

Otherwise, status(path()) or status(path(), ec), respectively.

28

#

Throws: As specified in [fs.err.report].

🔗

file_status symlink_status() const; file_status symlink_status(error_code& ec) const noexcept;

29

#

Returns: If cached, the symlink status attribute value.

Otherwise, symlink_status(path()) or symlink_status(path(), ec), respectively.

30

#

Throws: As specified in [fs.err.report].

🔗

bool operator==(const directory_entry& rhs) const noexcept;

31

#

Returns: path-object == rhs.path-object.

🔗

strong_ordering operator<=>(const directory_entry& rhs) const noexcept;

32

#

Returns: path-object <=> rhs.path-object.

31.12.10.5 Inserter [fs.dir.entry.io]

🔗

template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);

1

#

Effects: Equivalent to: return os << d.path();