From Jason Turner

[category.time]

C++14 → C++17 13.4 KB 114 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp6w4tavb1/{from.md → to.md} +53 -50
tmp/tmp6w4tavb1/{from.md → to.md} RENAMED
@@ -5,12 +5,12 @@ Templates `time_get<charT,InputIterator>` and
5
  parsing. All specifications of member functions for `time_put` and
6
  `time_get` in the subclauses of  [[category.time]] only apply to the
7
  specializations required in Tables  [[tab:localization.category.facets]]
8
  and  [[tab:localization.required.specializations]] (
9
  [[locale.category]]). Their members use their `ios_base&`,
10
- `ios_base::iostate&`, and `fill` arguments as described in (
11
- [[locale.categories]]), and the `ctype<>` facet, to determine formatting
12
  details.
13
 
14
  #### Class template `time_get` <a id="locale.time.get">[[locale.time.get]]</a>
15
 
16
  ``` cpp
@@ -21,12 +21,12 @@ namespace std {
21
  };
22
 
23
  template <class charT, class InputIterator = istreambuf_iterator<charT>>
24
  class time_get : public locale::facet, public time_base {
25
  public:
26
- typedef charT char_type;
27
- typedef InputIterator iter_type;
28
 
29
  explicit time_get(size_t refs = 0);
30
 
31
  dateorder date_order() const { return do_date_order(); }
32
  iter_type get_time(iter_type s, iter_type end, ios_base& f,
@@ -67,81 +67,81 @@ namespace std {
67
  ```
68
 
69
  `time_get`
70
 
71
  is used to parse a character sequence, extracting components of a time
72
- or date into a `struct tm` record. Each `get` member parses a format as
73
  produced by a corresponding format specifier to `time_put<>::put`. If
74
  the sequence being parsed matches the correct format, the corresponding
75
  members of the `struct tm` argument are set to the values used to
76
  produce the sequence; otherwise either an error is reported or
77
- unspecified values are assigned.[^14]
78
 
79
  If the end iterator is reached during parsing by any of the `get()`
80
  member functions, the member sets `ios_base::eofbit` in `err`.
81
 
82
  ##### `time_get` members <a id="locale.time.get.members">[[locale.time.get.members]]</a>
83
 
84
  ``` cpp
85
  dateorder date_order() const;
86
  ```
87
 
88
- *Returns:* `do_date_order()`
89
 
90
  ``` cpp
91
  iter_type get_time(iter_type s, iter_type end, ios_base& str,
92
  ios_base::iostate& err, tm* t) const;
93
  ```
94
 
95
- *Returns:* `do_get_time(s, end, str, err, t)`
96
 
97
  ``` cpp
98
  iter_type get_date(iter_type s, iter_type end, ios_base& str,
99
  ios_base::iostate& err, tm* t) const;
100
  ```
101
 
102
- *Returns:* `do_get_date(s, end, str, err, t)`
103
 
104
  ``` cpp
105
  iter_type get_weekday(iter_type s, iter_type end, ios_base& str,
106
  ios_base::iostate& err, tm* t) const;
107
  iter_type get_monthname(iter_type s, iter_type end, ios_base& str,
108
  ios_base::iostate& err, tm* t) const;
109
  ```
110
 
111
  *Returns:* `do_get_weekday(s, end, str, err, t)` or
112
- `do_get_monthname(s, end, str, err, t)`
113
 
114
  ``` cpp
115
  iter_type get_year(iter_type s, iter_type end, ios_base& str,
116
  ios_base::iostate& err, tm* t) const;
117
  ```
118
 
119
- *Returns:* `do_get_year(s, end, str, err, t)`
120
 
121
  ``` cpp
122
- iter_type get(iter_type s, iter_type end, ios_base& f,
123
- ios_base::iostate& err, tm* t, char format, char modifier = 0) const;
124
  ```
125
 
126
- *Returns:* `do_get(s, end, f, err, t, format, modifier)`
127
 
128
  ``` cpp
129
- iter_type get(iter_type s, iter_type end, ios_base& f,
130
- ios_base::iostate& err, tm* t, const char_type* fmt, const char_type* fmtend) const;
131
  ```
132
 
133
  *Requires:* \[`fmt`, `fmtend`) shall be a valid range.
134
 
135
  *Effects:* The function starts by evaluating `err = ios_base::goodbit`.
136
  It then enters a loop, reading zero or more characters from `s` at each
137
  iteration. Unless otherwise specified below, the loop terminates when
138
  the first of the following conditions holds:
139
 
140
- - The expression `fmt == fmtend` evaluates to true.
141
- - The expression `err == ios_base::goodbit` evaluates to false.
142
- - The expression `s == end` evaluates to true, in which case the
143
  function evaluates `err = ios_base::eofbit | ios_base::failbit`.
144
  - The next element of `fmt` is equal to `’%’`, optionally followed by a
145
  modifier character, followed by a conversion specifier character,
146
  `format`, together forming a conversion specification valid for the
147
  ISO/IEC 9945 function `strptime`. If the number of elements in the
@@ -152,36 +152,37 @@ the first of the following conditions holds:
152
  value of `modifier` is `’\0’` when the optional modifier is absent
153
  from the conversion specification. If `err == ios_base::goodbit` holds
154
  after the evaluation of the expression, the function increments `fmt`
155
  to point just past the end of the conversion specification and
156
  continues looping.
157
- - The expression `isspace(*fmt, f.getloc())` evaluates to true, in which
158
- case the function first increments `fmt` until
159
- `fmt == fmtend || !isspace(*fmt, f.getloc())` evaluates to true, then
160
- advances `s` until `s == end || !isspace(*s, f.getloc())` is true, and
161
- finally resumes looping.
162
  - The next character read from `s` matches the element pointed to by
163
  `fmt` in a case-insensitive comparison, in which case the function
164
  evaluates `++fmt, ++s` and continues looping. Otherwise, the function
165
  evaluates `err = ios_base::failbit`.
166
 
167
- The function uses the `ctype<charT>` facet installed in `f`’s locale to
168
- determine valid whitespace characters. It is unspecified by what means
169
- the function performs case-insensitive comparison or whether
170
- multi-character sequences are considered while doing so.
 
171
 
172
- *Returns:* `s`
173
 
174
  ##### `time_get` virtual functions <a id="locale.time.get.virtuals">[[locale.time.get.virtuals]]</a>
175
 
176
  ``` cpp
177
  dateorder do_date_order() const;
178
  ```
179
 
180
  *Returns:* An enumeration value indicating the preferred order of
181
  components for those date formats that are composed of day, month, and
182
- year.[^15] Returns `no_order` if the date format specified by `’x’`
183
  contains other variable components (e.g., Julian day, week number, week
184
  day).
185
 
186
  ``` cpp
187
  iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
@@ -268,24 +269,24 @@ any remaining format characters, corresponding to a conversion directive
268
  appropriate for the ISO/IEC 9945 function `strptime`, formed by
269
  concatenating `’%’`, the `modifier` character, when non-NUL, and the
270
  `format` character. When the concatenation fails to yield a complete
271
  valid directive the function leaves the object pointed to by `t`
272
  unchanged and evaluates `err |= ios_base::failbit`. When `s == end`
273
- evaluates to true after reading a character the function evaluates
274
  `err |= ios_base::eofbit`.
275
 
276
  For complex conversion directives such as `%c`, `%x`, or `%X`, or
277
  directives that involve the optional modifiers `E` or `O`, when the
278
  function is unable to unambiguously determine some or all `struct tm`
279
  members from the input sequence \[`s`, `end`), it evaluates
280
  `err |= ios_base::eofbit`. In such cases the values of those `struct tm`
281
  members are unspecified and may be outside their valid range.
282
 
283
- It is unspecified whether multiple calls to `do_get()` with the address
284
- of the same `struct tm` object will update the current contents of the
285
- object or simply overwrite its members. Portable programs must zero out
286
- the object before invoking the function.
287
 
288
  *Returns:* An iterator pointing immediately beyond the last character
289
  recognized as possibly part of a valid input sequence for the given
290
  `format` and `modifier`.
291
 
@@ -294,12 +295,12 @@ recognized as possibly part of a valid input sequence for the given
294
  ``` cpp
295
  namespace std {
296
  template <class charT, class InputIterator = istreambuf_iterator<charT>>
297
  class time_get_byname : public time_get<charT, InputIterator> {
298
  public:
299
- typedef time_base::dateorder dateorder;
300
- typedef InputIterator iter_type;
301
 
302
  explicit time_get_byname(const char*, size_t refs = 0);
303
  explicit time_get_byname(const string&, size_t refs = 0);
304
  protected:
305
  ~time_get_byname();
@@ -312,12 +313,12 @@ namespace std {
312
  ``` cpp
313
  namespace std {
314
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
315
  class time_put : public locale::facet {
316
  public:
317
- typedef charT char_type;
318
- typedef OutputIterator iter_type;
319
 
320
  explicit time_put(size_t refs = 0);
321
 
322
  // the following is implemented in terms of other member functions.
323
  iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb,
@@ -352,20 +353,20 @@ call to `do_put`; thus, format elements and other characters are
352
  interleaved in the output in the order in which they appear in the
353
  pattern. Format sequences are identified by converting each character
354
  `c` to a `char` value as if by `ct.narrow(c, 0)`, where `ct` is a
355
  reference to `ctype<charT>` obtained from `str.getloc()`. The first
356
  character of each sequence is equal to `’%’`, followed by an optional
357
- modifier character `mod`[^16] and a format specifier character `spec` as
358
  defined for the function `strftime`. If no modifier character is
359
  present, `mod` is zero. For each valid format sequence identified, calls
360
  `do_put(s, str, fill, t, spec, mod)`.
361
 
362
  The second form calls `do_put(s, str, fill, t, format, modifier)`.
363
 
364
- The `fill` argument may be used in the implementation-defined formats or
365
- by derivations. A space character is a reasonable default for this
366
- argument.
367
 
368
  *Returns:* An iterator pointing immediately after the last character
369
  produced.
370
 
371
  ##### `time_put` virtual functions <a id="locale.time.put.virtuals">[[locale.time.put.virtuals]]</a>
@@ -377,29 +378,31 @@ iter_type do_put(iter_type s, ios_base&, char_type fill, const tm* t,
377
 
378
  *Effects:* Formats the contents of the parameter `t` into characters
379
  placed on the output sequence `s`. Formatting is controlled by the
380
  parameters `format` and `modifier`, interpreted identically as the
381
  format specifiers in the string argument to the standard library
382
- function `strftime()`[^17], except that the sequence of characters
383
  produced for those specifiers that are described as depending on the C
384
- locale are instead *implementation-defined*.[^18]
385
 
386
  *Returns:* An iterator pointing immediately after the last character
387
- produced. The `fill` argument may be used in the implementation-defined
388
- formats or by derivations. A space character is a reasonable default for
389
- this argument.
 
 
390
 
391
  #### Class template `time_put_byname` <a id="locale.time.put.byname">[[locale.time.put.byname]]</a>
392
 
393
  ``` cpp
394
  namespace std {
395
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
396
  class time_put_byname : public time_put<charT, OutputIterator>
397
  {
398
  public:
399
- typedef charT char_type;
400
- typedef OutputIterator iter_type;
401
 
402
  explicit time_put_byname(const char*, size_t refs = 0);
403
  explicit time_put_byname(const string&, size_t refs = 0);
404
  protected:
405
  ~time_put_byname();
 
5
  parsing. All specifications of member functions for `time_put` and
6
  `time_get` in the subclauses of  [[category.time]] only apply to the
7
  specializations required in Tables  [[tab:localization.category.facets]]
8
  and  [[tab:localization.required.specializations]] (
9
  [[locale.category]]). Their members use their `ios_base&`,
10
+ `ios_base::iostate&`, and `fill` arguments as described in 
11
+ [[locale.categories]], and the `ctype<>` facet, to determine formatting
12
  details.
13
 
14
  #### Class template `time_get` <a id="locale.time.get">[[locale.time.get]]</a>
15
 
16
  ``` cpp
 
21
  };
22
 
23
  template <class charT, class InputIterator = istreambuf_iterator<charT>>
24
  class time_get : public locale::facet, public time_base {
25
  public:
26
+ using char_type = charT;
27
+ using iter_type = InputIterator;
28
 
29
  explicit time_get(size_t refs = 0);
30
 
31
  dateorder date_order() const { return do_date_order(); }
32
  iter_type get_time(iter_type s, iter_type end, ios_base& f,
 
67
  ```
68
 
69
  `time_get`
70
 
71
  is used to parse a character sequence, extracting components of a time
72
+ or date into a `struct tm` object. Each `get` member parses a format as
73
  produced by a corresponding format specifier to `time_put<>::put`. If
74
  the sequence being parsed matches the correct format, the corresponding
75
  members of the `struct tm` argument are set to the values used to
76
  produce the sequence; otherwise either an error is reported or
77
+ unspecified values are assigned.[^15]
78
 
79
  If the end iterator is reached during parsing by any of the `get()`
80
  member functions, the member sets `ios_base::eofbit` in `err`.
81
 
82
  ##### `time_get` members <a id="locale.time.get.members">[[locale.time.get.members]]</a>
83
 
84
  ``` cpp
85
  dateorder date_order() const;
86
  ```
87
 
88
+ *Returns:* `do_date_order()`.
89
 
90
  ``` cpp
91
  iter_type get_time(iter_type s, iter_type end, ios_base& str,
92
  ios_base::iostate& err, tm* t) const;
93
  ```
94
 
95
+ *Returns:* `do_get_time(s, end, str, err, t)`.
96
 
97
  ``` cpp
98
  iter_type get_date(iter_type s, iter_type end, ios_base& str,
99
  ios_base::iostate& err, tm* t) const;
100
  ```
101
 
102
+ *Returns:* `do_get_date(s, end, str, err, t)`.
103
 
104
  ``` cpp
105
  iter_type get_weekday(iter_type s, iter_type end, ios_base& str,
106
  ios_base::iostate& err, tm* t) const;
107
  iter_type get_monthname(iter_type s, iter_type end, ios_base& str,
108
  ios_base::iostate& err, tm* t) const;
109
  ```
110
 
111
  *Returns:* `do_get_weekday(s, end, str, err, t)` or
112
+ `do_get_monthname(s, end, str, err, t)`.
113
 
114
  ``` cpp
115
  iter_type get_year(iter_type s, iter_type end, ios_base& str,
116
  ios_base::iostate& err, tm* t) const;
117
  ```
118
 
119
+ *Returns:* `do_get_year(s, end, str, err, t)`.
120
 
121
  ``` cpp
122
+ iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err,
123
+ tm* t, char format, char modifier = 0) const;
124
  ```
125
 
126
+ *Returns:* `do_get(s, end, f, err, t, format, modifier)`.
127
 
128
  ``` cpp
129
+ iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err,
130
+ tm* t, const char_type* fmt, const char_type* fmtend) const;
131
  ```
132
 
133
  *Requires:* \[`fmt`, `fmtend`) shall be a valid range.
134
 
135
  *Effects:* The function starts by evaluating `err = ios_base::goodbit`.
136
  It then enters a loop, reading zero or more characters from `s` at each
137
  iteration. Unless otherwise specified below, the loop terminates when
138
  the first of the following conditions holds:
139
 
140
+ - The expression `fmt == fmtend` evaluates to `true`.
141
+ - The expression `err == ios_base::goodbit` evaluates to `false`.
142
+ - The expression `s == end` evaluates to `true`, in which case the
143
  function evaluates `err = ios_base::eofbit | ios_base::failbit`.
144
  - The next element of `fmt` is equal to `’%’`, optionally followed by a
145
  modifier character, followed by a conversion specifier character,
146
  `format`, together forming a conversion specification valid for the
147
  ISO/IEC 9945 function `strptime`. If the number of elements in the
 
152
  value of `modifier` is `’\0’` when the optional modifier is absent
153
  from the conversion specification. If `err == ios_base::goodbit` holds
154
  after the evaluation of the expression, the function increments `fmt`
155
  to point just past the end of the conversion specification and
156
  continues looping.
157
+ - The expression `isspace(*fmt, f.getloc())` evaluates to `true`, in
158
+ which case the function first increments `fmt` until
159
+ `fmt == fmtend || !isspace(*fmt, f.getloc())` evaluates to `true`,
160
+ then advances `s` until `s == end || !isspace(*s, f.getloc())` is
161
+ `true`, and finally resumes looping.
162
  - The next character read from `s` matches the element pointed to by
163
  `fmt` in a case-insensitive comparison, in which case the function
164
  evaluates `++fmt, ++s` and continues looping. Otherwise, the function
165
  evaluates `err = ios_base::failbit`.
166
 
167
+ [*Note 1*: The function uses the `ctype<charT>` facet installed in
168
+ `f`’s locale to determine valid whitespace characters. It is unspecified
169
+ by what means the function performs case-insensitive comparison or
170
+ whether multi-character sequences are considered while doing
171
+ so. — *end note*]
172
 
173
+ *Returns:* `s`.
174
 
175
  ##### `time_get` virtual functions <a id="locale.time.get.virtuals">[[locale.time.get.virtuals]]</a>
176
 
177
  ``` cpp
178
  dateorder do_date_order() const;
179
  ```
180
 
181
  *Returns:* An enumeration value indicating the preferred order of
182
  components for those date formats that are composed of day, month, and
183
+ year.[^16] Returns `no_order` if the date format specified by `’x’`
184
  contains other variable components (e.g., Julian day, week number, week
185
  day).
186
 
187
  ``` cpp
188
  iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
 
269
  appropriate for the ISO/IEC 9945 function `strptime`, formed by
270
  concatenating `’%’`, the `modifier` character, when non-NUL, and the
271
  `format` character. When the concatenation fails to yield a complete
272
  valid directive the function leaves the object pointed to by `t`
273
  unchanged and evaluates `err |= ios_base::failbit`. When `s == end`
274
+ evaluates to `true` after reading a character the function evaluates
275
  `err |= ios_base::eofbit`.
276
 
277
  For complex conversion directives such as `%c`, `%x`, or `%X`, or
278
  directives that involve the optional modifiers `E` or `O`, when the
279
  function is unable to unambiguously determine some or all `struct tm`
280
  members from the input sequence \[`s`, `end`), it evaluates
281
  `err |= ios_base::eofbit`. In such cases the values of those `struct tm`
282
  members are unspecified and may be outside their valid range.
283
 
284
+ *Remarks:* It is unspecified whether multiple calls to `do_get()` with
285
+ the address of the same `struct tm` object will update the current
286
+ contents of the object or simply overwrite its members. Portable
287
+ programs must zero out the object before invoking the function.
288
 
289
  *Returns:* An iterator pointing immediately beyond the last character
290
  recognized as possibly part of a valid input sequence for the given
291
  `format` and `modifier`.
292
 
 
295
  ``` cpp
296
  namespace std {
297
  template <class charT, class InputIterator = istreambuf_iterator<charT>>
298
  class time_get_byname : public time_get<charT, InputIterator> {
299
  public:
300
+ using dateorder = time_base::dateorder;
301
+ using iter_type = InputIterator;
302
 
303
  explicit time_get_byname(const char*, size_t refs = 0);
304
  explicit time_get_byname(const string&, size_t refs = 0);
305
  protected:
306
  ~time_get_byname();
 
313
  ``` cpp
314
  namespace std {
315
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
316
  class time_put : public locale::facet {
317
  public:
318
+ using char_type = charT;
319
+ using iter_type = OutputIterator;
320
 
321
  explicit time_put(size_t refs = 0);
322
 
323
  // the following is implemented in terms of other member functions.
324
  iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb,
 
353
  interleaved in the output in the order in which they appear in the
354
  pattern. Format sequences are identified by converting each character
355
  `c` to a `char` value as if by `ct.narrow(c, 0)`, where `ct` is a
356
  reference to `ctype<charT>` obtained from `str.getloc()`. The first
357
  character of each sequence is equal to `’%’`, followed by an optional
358
+ modifier character `mod`[^17] and a format specifier character `spec` as
359
  defined for the function `strftime`. If no modifier character is
360
  present, `mod` is zero. For each valid format sequence identified, calls
361
  `do_put(s, str, fill, t, spec, mod)`.
362
 
363
  The second form calls `do_put(s, str, fill, t, format, modifier)`.
364
 
365
+ [*Note 1*: The `fill` argument may be used in the
366
+ implementation-defined formats or by derivations. A space character is a
367
+ reasonable default for this argument. — *end note*]
368
 
369
  *Returns:* An iterator pointing immediately after the last character
370
  produced.
371
 
372
  ##### `time_put` virtual functions <a id="locale.time.put.virtuals">[[locale.time.put.virtuals]]</a>
 
378
 
379
  *Effects:* Formats the contents of the parameter `t` into characters
380
  placed on the output sequence `s`. Formatting is controlled by the
381
  parameters `format` and `modifier`, interpreted identically as the
382
  format specifiers in the string argument to the standard library
383
+ function `strftime()`[^18], except that the sequence of characters
384
  produced for those specifiers that are described as depending on the C
385
+ locale are instead *implementation-defined*.[^19]
386
 
387
  *Returns:* An iterator pointing immediately after the last character
388
+ produced.
389
+
390
+ [*Note 2*: The `fill` argument may be used in the
391
+ implementation-defined formats or by derivations. A space character is a
392
+ reasonable default for this argument. — *end note*]
393
 
394
  #### Class template `time_put_byname` <a id="locale.time.put.byname">[[locale.time.put.byname]]</a>
395
 
396
  ``` cpp
397
  namespace std {
398
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
399
  class time_put_byname : public time_put<charT, OutputIterator>
400
  {
401
  public:
402
+ using char_type = charT;
403
+ using iter_type = OutputIterator;
404
 
405
  explicit time_put_byname(const char*, size_t refs = 0);
406
  explicit time_put_byname(const string&, size_t refs = 0);
407
  protected:
408
  ~time_put_byname();