From Jason Turner

[time.zone.db]

C++17 → C++20 6.5 KB 225 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpimax463o/{from.md → to.md} +222 -0
tmp/tmpimax463o/{from.md → to.md} RENAMED
@@ -0,0 +1,222 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Time zone database <a id="time.zone.db">[[time.zone.db]]</a>
2
+
3
+ #### Class `tzdb` <a id="time.zone.db.tzdb">[[time.zone.db.tzdb]]</a>
4
+
5
+ ``` cpp
6
+ namespace std::chrono {
7
+ struct tzdb {
8
+ string version;
9
+ vector<time_zone> zones;
10
+ vector<time_zone_link> links;
11
+ vector<leap_second> leap_seconds;
12
+
13
+ const time_zone* locate_zone(string_view tz_name) const;
14
+ const time_zone* current_zone() const;
15
+ };
16
+ }
17
+ ```
18
+
19
+ Each `vector` in a `tzdb` object is sorted to enable fast lookup.
20
+
21
+ ``` cpp
22
+ const time_zone* locate_zone(string_view tz_name) const;
23
+ ```
24
+
25
+ *Returns:*
26
+
27
+ - If `zones` contains an element `tz` for which `tz.name() == tz_name`,
28
+ a pointer to `tz`;
29
+ - otherwise, if `links` contains an element `tz_l` for which
30
+ `tz_l.name() == tz_name`, then a pointer to the element `tz` of
31
+ `zones` for which `tz.name() == tz_l.target()`.
32
+
33
+ [*Note 1*: A `time_zone_link` specifies an alternative name for a
34
+ `time_zone`. — *end note*]
35
+
36
+ *Throws:* If a `const time_zone*` cannot be found as described in the
37
+ *Returns:* clause, throws a `runtime_error`.
38
+
39
+ [*Note 2*: On non-exceptional return, the return value is always a
40
+ pointer to a valid `time_zone`. — *end note*]
41
+
42
+ ``` cpp
43
+ const time_zone* current_zone() const;
44
+ ```
45
+
46
+ *Returns:* A pointer to the time zone which the computer has set as its
47
+ local time zone.
48
+
49
+ #### Class `tzdb_list` <a id="time.zone.db.list">[[time.zone.db.list]]</a>
50
+
51
+ ``` cpp
52
+ namespace std::chrono {
53
+ class tzdb_list {
54
+ public:
55
+ tzdb_list(const tzdb_list&) = delete;
56
+ tzdb_list& operator=(const tzdb_list&) = delete;
57
+
58
+ // unspecified additional constructors
59
+
60
+ class const_iterator;
61
+
62
+ const tzdb& front() const noexcept;
63
+
64
+ const_iterator erase_after(const_iterator p);
65
+
66
+ const_iterator begin() const noexcept;
67
+ const_iterator end() const noexcept;
68
+
69
+ const_iterator cbegin() const noexcept;
70
+ const_iterator cend() const noexcept;
71
+ };
72
+ }
73
+ ```
74
+
75
+ The `tzdb_list` database is a singleton; the unique object of type
76
+ `tzdb_list` can be accessed via the `get_tzdb_list()` function.
77
+
78
+ [*Note 1*: This access is only needed for those applications that need
79
+ to have long uptimes and have a need to update the time zone database
80
+ while running. Other applications can implicitly access the `front()` of
81
+ this list via the read-only namespace scope functions `get_tzdb()`,
82
+ `locate_zone()`, and `current_zone()`. — *end note*]
83
+
84
+ The `tzdb_list` object contains a list of `tzdb` objects.
85
+
86
+ `tzdb_list::const_iterator` is a constant iterator which meets the
87
+ *Cpp17ForwardIterator* requirements and has a value type of `tzdb`.
88
+
89
+ ``` cpp
90
+ const tzdb& front() const noexcept;
91
+ ```
92
+
93
+ *Synchronization:* This operation is thread-safe with respect to
94
+ `reload_tzdb()`.
95
+
96
+ [*Note 1*: `reload_tzdb()` pushes a new `tzdb` onto the front of this
97
+ container. — *end note*]
98
+
99
+ *Returns:* A reference to the first `tzdb` in the container.
100
+
101
+ ``` cpp
102
+ const_iterator erase_after(const_iterator p);
103
+ ```
104
+
105
+ *Preconditions:* The iterator following `p` is dereferenceable.
106
+
107
+ *Effects:* Erases the `tzdb` referred to by the iterator following `p`.
108
+
109
+ *Returns:* An iterator pointing to the element following the one that
110
+ was erased, or `end()` if no such element exists.
111
+
112
+ *Ensures:* No pointers, references, or iterators are invalidated except
113
+ those referring to the erased `tzdb`.
114
+
115
+ [*Note 2*: It is not possible to erase the `tzdb` referred to by
116
+ `begin()`. — *end note*]
117
+
118
+ *Throws:* Nothing.
119
+
120
+ ``` cpp
121
+ const_iterator begin() const noexcept;
122
+ ```
123
+
124
+ *Returns:* An iterator referring to the first `tzdb` in the container.
125
+
126
+ ``` cpp
127
+ const_iterator end() const noexcept;
128
+ ```
129
+
130
+ *Returns:* An iterator referring to the position one past the last
131
+ `tzdb` in the container.
132
+
133
+ ``` cpp
134
+ const_iterator cbegin() const noexcept;
135
+ ```
136
+
137
+ *Returns:* `begin()`.
138
+
139
+ ``` cpp
140
+ const_iterator cend() const noexcept;
141
+ ```
142
+
143
+ *Returns:* `end()`.
144
+
145
+ #### Time zone database access <a id="time.zone.db.access">[[time.zone.db.access]]</a>
146
+
147
+ ``` cpp
148
+ tzdb_list& get_tzdb_list();
149
+ ```
150
+
151
+ *Effects:* If this is the first access to the time zone database,
152
+ initializes the database. If this call initializes the database, the
153
+ resulting database will be a `tzdb_list` holding a single initialized
154
+ `tzdb`.
155
+
156
+ *Synchronization:* It is safe to call this function from multiple
157
+ threads at one time.
158
+
159
+ *Returns:* A reference to the database.
160
+
161
+ *Throws:* `runtime_error` if for any reason a reference cannot be
162
+ returned to a valid `tzdb_list` containing one or more valid `tzdb`s.
163
+
164
+ ``` cpp
165
+ const tzdb& get_tzdb();
166
+ ```
167
+
168
+ *Returns:* `get_tzdb_list().front()`.
169
+
170
+ ``` cpp
171
+ const time_zone* locate_zone(string_view tz_name);
172
+ ```
173
+
174
+ *Returns:* `get_tzdb().locate_zone(tz_name)`.
175
+
176
+ [*Note 1*: The time zone database will be initialized if this is the
177
+ first reference to the database. — *end note*]
178
+
179
+ ``` cpp
180
+ const time_zone* current_zone();
181
+ ```
182
+
183
+ *Returns:* `get_tzdb().current_zone()`.
184
+
185
+ #### Remote time zone database support <a id="time.zone.db.remote">[[time.zone.db.remote]]</a>
186
+
187
+ The local time zone database is that supplied by the implementation when
188
+ the program first accesses the database, for example via
189
+ `current_zone()`. While the program is running, the implementation may
190
+ choose to update the time zone database. This update shall not impact
191
+ the program in any way unless the program calls the functions in this
192
+ subclause. This potentially updated time zone database is referred to as
193
+ the *remote time zone database*.
194
+
195
+ ``` cpp
196
+ const tzdb& reload_tzdb();
197
+ ```
198
+
199
+ *Effects:* This function first checks the version of the remote time
200
+ zone database. If the versions of the local and remote databases are the
201
+ same, there are no effects. Otherwise the remote database is pushed to
202
+ the front of the `tzdb_list` accessed by `get_tzdb_list()`.
203
+
204
+ *Synchronization:* This function is thread-safe with respect to
205
+ `get_tzdb_list().front()` and `get_tzdb_list().erase_after()`.
206
+
207
+ *Ensures:* No pointers, references, or iterators are invalidated.
208
+
209
+ *Returns:* `get_tzdb_list().front()`.
210
+
211
+ *Throws:* `runtime_error` if for any reason a reference cannot be
212
+ returned to a valid `tzdb`.
213
+
214
+ ``` cpp
215
+ string remote_version();
216
+ ```
217
+
218
+ *Returns:* The latest remote database version.
219
+
220
+ [*Note 1*: This can be compared with `get_tzdb().version` to discover
221
+ if the local and remote databases are equivalent. — *end note*]
222
+