[fs.class.directory.entry] (original) (raw)

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: 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(); directory_entry& operator=(const directory_entry&) = default; directory_entry& operator=(directory_entry&&) noexcept = default;void 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;const 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;template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);private: filesystem::path path-object; };}

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

[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_]

[Example 1: using namespace std::filesystem;for (auto&& x : directory_iterator(".")) { std::cout << x.path() << " " << x.last_write_time() << std::endl;} for (auto&& x : directory_iterator(".")) { lengthy_function(x.path()); 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);

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

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

31.12.10.3 Modifiers [fs.dir.entry.mods]

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

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

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

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

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.

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.

31.12.10.4 Observers [fs.dir.entry.obs]

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;

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

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

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.

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.

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

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

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

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

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

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

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.

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

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

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.

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.

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.

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.

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.

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.

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

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

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

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);

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