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.
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().
[Example 1: usingnamespace 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.