From Jason Turner

[fs.class.directory.entry.general]

C++20 → C++23 5.0 KB 123 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpd3ezu1ei/{from.md → to.md} +120 -0
tmp/tmpd3ezu1ei/{from.md → to.md} RENAMED
@@ -0,0 +1,120 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #### General <a id="fs.class.directory.entry.general">[[fs.class.directory.entry.general]]</a>
2
+
3
+ ``` cpp
4
+ namespace std::filesystem {
5
+ class directory_entry {
6
+ public:
7
+ // [fs.dir.entry.cons], constructors and destructor
8
+ directory_entry() noexcept = default;
9
+ directory_entry(const directory_entry&) = default;
10
+ directory_entry(directory_entry&&) noexcept = default;
11
+ explicit directory_entry(const filesystem::path& p);
12
+ directory_entry(const filesystem::path& p, error_code& ec);
13
+ ~directory_entry();
14
+
15
+ // assignments
16
+ directory_entry& operator=(const directory_entry&) = default;
17
+ directory_entry& operator=(directory_entry&&) noexcept = default;
18
+
19
+ // [fs.dir.entry.mods], modifiers
20
+ void assign(const filesystem::path& p);
21
+ void assign(const filesystem::path& p, error_code& ec);
22
+ void replace_filename(const filesystem::path& p);
23
+ void replace_filename(const filesystem::path& p, error_code& ec);
24
+ void refresh();
25
+ void refresh(error_code& ec) noexcept;
26
+
27
+ // [fs.dir.entry.obs], observers
28
+ const filesystem::path& path() const noexcept;
29
+ operator const filesystem::path&() const noexcept;
30
+ bool exists() const;
31
+ bool exists(error_code& ec) const noexcept;
32
+ bool is_block_file() const;
33
+ bool is_block_file(error_code& ec) const noexcept;
34
+ bool is_character_file() const;
35
+ bool is_character_file(error_code& ec) const noexcept;
36
+ bool is_directory() const;
37
+ bool is_directory(error_code& ec) const noexcept;
38
+ bool is_fifo() const;
39
+ bool is_fifo(error_code& ec) const noexcept;
40
+ bool is_other() const;
41
+ bool is_other(error_code& ec) const noexcept;
42
+ bool is_regular_file() const;
43
+ bool is_regular_file(error_code& ec) const noexcept;
44
+ bool is_socket() const;
45
+ bool is_socket(error_code& ec) const noexcept;
46
+ bool is_symlink() const;
47
+ bool is_symlink(error_code& ec) const noexcept;
48
+ uintmax_t file_size() const;
49
+ uintmax_t file_size(error_code& ec) const noexcept;
50
+ uintmax_t hard_link_count() const;
51
+ uintmax_t hard_link_count(error_code& ec) const noexcept;
52
+ file_time_type last_write_time() const;
53
+ file_time_type last_write_time(error_code& ec) const noexcept;
54
+ file_status status() const;
55
+ file_status status(error_code& ec) const noexcept;
56
+ file_status symlink_status() const;
57
+ file_status symlink_status(error_code& ec) const noexcept;
58
+
59
+ bool operator==(const directory_entry& rhs) const noexcept;
60
+ strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
61
+
62
+ // [fs.dir.entry.io], inserter
63
+ template<class charT, class traits>
64
+ friend basic_ostream<charT, traits>&
65
+ operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
66
+
67
+ private:
68
+ filesystem::path pathobject; // exposition only
69
+ friend class directory_iterator; // exposition only
70
+ };
71
+ }
72
+ ```
73
+
74
+ A `directory_entry` object stores a `path` object and may store
75
+ additional objects for file attributes such as hard link count, status,
76
+ symlink status, file size, and last write time.
77
+
78
+ Implementations should store such additional file attributes during
79
+ directory iteration if their values are available and storing the values
80
+ would allow the implementation to eliminate file system accesses by
81
+ `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
82
+ attribute values are said to be *cached*.
83
+
84
+ [*Note 1*: For purposes of exposition, class `directory_iterator`
85
+ [[fs.class.directory.iterator]] is shown above as a friend of class
86
+ `directory_entry`. Friendship allows the `directory_iterator`
87
+ implementation to cache already available attribute values directly into
88
+ a `directory_entry` object without the cost of an unneeded call to
89
+ `refresh()`. — *end note*]
90
+
91
+ [*Example 1*:
92
+
93
+ ``` cpp
94
+ using namespace std::filesystem;
95
+
96
+ // use possibly cached last write time to minimize disk accesses
97
+ for (auto&& x : directory_iterator("."))
98
+ {
99
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
100
+ }
101
+
102
+ // call refresh() to refresh a stale cache
103
+ for (auto&& x : directory_iterator("."))
104
+ {
105
+ lengthy_function(x.path()); // cache becomes stale
106
+ x.refresh();
107
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
108
+ }
109
+ ```
110
+
111
+ On implementations that do not cache the last write time, both loops
112
+ will result in a potentially expensive call to the
113
+ `std::filesystem::last_write_time` function. On implementations that do
114
+ cache the last write time, the first loop will use the cached value and
115
+ so will not result in a potentially expensive call to the
116
+ `std::filesystem::last_write_time` function. The code is portable to any
117
+ implementation, regardless of whether or not it employs caching.
118
+
119
+ — *end example*]
120
+