[category.time] - C++20 → C++23

Files changed (1) hide show

tmp/tmpbp1zv8cm/{from.md → to.md} +62 -49

tmp/tmpbp1zv8cm/{from.md → to.md} RENAMED Viewed

@@ -1,7 +1,9 @@
 ### The time category <a id="category.time">[[category.time]]</a>
 Templates `time_get<charT, InputIterator>` and
 `time_put<charT, OutputIterator>` provide date and time formatting and
 parsing. All specifications of member functions for `time_put` and
 `time_get` in the subclauses of  [[category.time]] only apply to the
 specializations required in Tables  [[tab:locale.category.facets]] and
@@ -10,10 +12,12 @@ specializations required in Tables  [[tab:locale.category.facets]] and
 [[locale.categories]], and the `ctype<>` facet, to determine formatting
 details.
 #### Class template `time_get` <a id="locale.time.get">[[locale.time.get]]</a>
 ``` cpp
 namespace std {
   class time_base {
   public:
     enum dateorder { no_order, dmy, mdy, ymd, ydm };
@@ -63,19 +67,17 @@ namespace std {
                                ios_base::iostate& err, tm* t, char format, char modifier) const;
     };
 }
 ```
-`time_get`
-is used to parse a character sequence, extracting components of a time
-or date into a `struct tm` object. Each `get` member parses a format as
-produced by a corresponding format specifier to `time_put<>::put`. If
 the sequence being parsed matches the correct format, the corresponding
-members of the `struct tm` argument are set to the values used to
-produce the sequence; otherwise either an error is reported or
-unspecified values are assigned.[^15]
 If the end iterator is reached during parsing by any of the `get()`
 member functions, the member sets `ios_base::eofbit` in `err`.
 ##### Members <a id="locale.time.get.members">[[locale.time.get.members]]</a>
@@ -141,12 +143,12 @@ the first of the following conditions holds:
 - The expression `s == end` evaluates to `true`, in which case the
   function evaluates `err = ios_base::eofbit | ios_base::failbit`.
 - The next element of `fmt` is equal to `’%’`, optionally followed by a
   modifier character, followed by a conversion specifier character,
   `format`, together forming a conversion specification valid for the
- ISO/IEC 9945 function `strptime`. If the number of elements in the
- range \[`fmt`, `fmtend`) is not sufficient to unambiguously determine
   whether the conversion specification is complete and valid, the
   function evaluates `err = ios_base::failbit`. Otherwise, the function
   evaluates `s = do_get(s, end, f, err, t, format, modifier)`, where the
   value of `modifier` is `’\0’` when the optional modifier is absent
   from the conversion specification. If `err == ios_base::goodbit` holds
@@ -177,37 +179,38 @@ so. — *end note*]
 dateorder do_date_order() const;
 ```
 *Returns:* An enumeration value indicating the preferred order of
 components for those date formats that are composed of day, month, and
-year.[^16] Returns `no_order` if the date format specified by `’x’`
-contains other variable components (e.g., Julian day, week number, week
-day).
 ``` cpp
 iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
                       ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted those
-`struct tm` members, and remaining format characters, used by
-`time_put<>::put` to produce the format specified by `"%H:%M:%S"`, or
-until it encounters an error or end of sequence.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as possibly part of a valid time.
 ``` cpp
 iter_type do_get_date(iter_type s, iter_type end, ios_base& str,
                       ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted those
-`struct tm` members and remaining format characters used by
-`time_put<>::put` to produce one of the following formats, or until it
-encounters an error. The format depends on the value returned by
-`date_order()` as shown in [[locale.time.get.dogetdate]].
 **Table: `do_get_date` effects** <a id="locale.time.get.dogetdate">[locale.time.get.dogetdate]</a>
 | `date_order()` | Format     |
 | -------------- | ---------- |
@@ -231,13 +234,13 @@ iter_type do_get_monthname(iter_type s, iter_type end, ios_base& str,
                            ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted the
 (perhaps abbreviated) name of a weekday or month. If it finds an
-abbreviation that is followed by characters that could match a full
-name, it continues reading until it matches the full name or fails. It
-sets the appropriate `struct tm` member accordingly.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as part of a valid name.
 ``` cpp
@@ -260,36 +263,36 @@ iter_type do_get(iter_type s, iter_type end, ios_base& f,
 *Preconditions:* `t` points to an object.
 *Effects:* The function starts by evaluating `err = ios_base::goodbit`.
 It then reads characters starting at `s` until it encounters an error,
-or until it has extracted and assigned those `struct tm` members, and
-any remaining format characters, corresponding to a conversion directive
-appropriate for the ISO/IEC 9945 function `strptime`, formed by
-concatenating `’%’`, the `modifier` character, when non-NUL, and the
-`format` character. When the concatenation fails to yield a complete
-valid directive the function leaves the object pointed to by `t`
-unchanged and evaluates `err |= ios_base::failbit`. When `s == end`
-evaluates to `true` after reading a character the function evaluates
 `err |= ios_base::eofbit`.
-For complex conversion directives such as `%c`, `%x`, or `%X`, or
-directives that involve the optional modifiers `E` or `O`, when the
-function is unable to unambiguously determine some or all `struct tm`
-members from the input sequence \[`s`, `end`), it evaluates
-`err |= ios_base::eofbit`. In such cases the values of those `struct tm`
 members are unspecified and may be outside their valid range.
-*Remarks:* It is unspecified whether multiple calls to `do_get()` with
-the address of the same `struct tm` object will update the current
-contents of the object or simply overwrite its members. Portable
-programs should zero out the object before invoking the function.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as possibly part of a valid input sequence for the given
 `format` and `modifier`.
 #### Class template `time_get_byname` <a id="locale.time.get.byname">[[locale.time.get.byname]]</a>
 ``` cpp
 namespace std {
   template<class charT, class InputIterator = istreambuf_iterator<charT>>
@@ -352,18 +355,20 @@ call to `do_put`; thus, format elements and other characters are
 interleaved in the output in the order in which they appear in the
 pattern. Format sequences are identified by converting each character
 `c` to a `char` value as if by `ct.narrow(c, 0)`, where `ct` is a
 reference to `ctype<charT>` obtained from `str.getloc()`. The first
 character of each sequence is equal to `’%’`, followed by an optional
-modifier character `mod`[^17] and a format specifier character `spec` as
-defined for the function `strftime`. If no modifier character is
-present, `mod` is zero. For each valid format sequence identified, calls
 `do_put(s, str, fill, t, spec, mod)`.
 The second form calls `do_put(s, str, fill, t, format, modifier)`.
-[*Note 1*: The `fill` argument may be used in the
 implementation-defined formats or by derivations. A space character is a
 reasonable default for this argument. — *end note*]
 *Returns:* An iterator pointing immediately after the last character
 produced.
@@ -377,21 +382,29 @@ iter_type do_put(iter_type s, ios_base&, char_type fill, const tm* t,
 *Effects:* Formats the contents of the parameter `t` into characters
 placed on the output sequence `s`. Formatting is controlled by the
 parameters `format` and `modifier`, interpreted identically as the
 format specifiers in the string argument to the standard library
-function `strftime()`[^18], except that the sequence of characters
-produced for those specifiers that are described as depending on the C
-locale are instead *implementation-defined*.[^19]
 *Returns:* An iterator pointing immediately after the last character
 produced.
-[*Note 2*: The `fill` argument may be used in the
 implementation-defined formats or by derivations. A space character is a
 reasonable default for this argument. — *end note*]
 #### Class template `time_put_byname` <a id="locale.time.put.byname">[[locale.time.put.byname]]</a>
 ``` cpp
 namespace std {
   template<class charT, class OutputIterator = ostreambuf_iterator<charT>>

 ### The time category <a id="category.time">[[category.time]]</a>
+#### General <a id="category.time.general">[[category.time.general]]</a>
 Templates `time_get<charT, InputIterator>` and
 `time_put<charT, OutputIterator>` provide date and time formatting and
 parsing. All specifications of member functions for `time_put` and
 `time_get` in the subclauses of  [[category.time]] only apply to the
 specializations required in Tables  [[tab:locale.category.facets]] and
 [[locale.categories]], and the `ctype<>` facet, to determine formatting
 details.
 #### Class template `time_get` <a id="locale.time.get">[[locale.time.get]]</a>
+##### General <a id="locale.time.get.general">[[locale.time.get.general]]</a>
 ``` cpp
 namespace std {
   class time_base {
   public:
     enum dateorder { no_order, dmy, mdy, ymd, ydm };
                                ios_base::iostate& err, tm* t, char format, char modifier) const;
     };
 }
 ```
+`time_get` is used to parse a character sequence, extracting components
+of a time or date into a `tm` object. Each `get` member parses a format
+as produced by a corresponding format specifier to `time_put<>::put`. If
 the sequence being parsed matches the correct format, the corresponding
+members of the `tm` argument are set to the values used to produce the
+sequence; otherwise either an error is reported or unspecified values
+are assigned.[^15]
 If the end iterator is reached during parsing by any of the `get()`
 member functions, the member sets `ios_base::eofbit` in `err`.
 ##### Members <a id="locale.time.get.members">[[locale.time.get.members]]</a>
 - The expression `s == end` evaluates to `true`, in which case the
   function evaluates `err = ios_base::eofbit | ios_base::failbit`.
 - The next element of `fmt` is equal to `’%’`, optionally followed by a
   modifier character, followed by a conversion specifier character,
   `format`, together forming a conversion specification valid for the
+ POSIX function `strptime`. If the number of elements in the range
+  \[`fmt`, `fmtend`) is not sufficient to unambiguously determine
   whether the conversion specification is complete and valid, the
   function evaluates `err = ios_base::failbit`. Otherwise, the function
   evaluates `s = do_get(s, end, f, err, t, format, modifier)`, where the
   value of `modifier` is `’\0’` when the optional modifier is absent
   from the conversion specification. If `err == ios_base::goodbit` holds
 dateorder do_date_order() const;
 ```
 *Returns:* An enumeration value indicating the preferred order of
 components for those date formats that are composed of day, month, and
+year.[^16]
+Returns `no_order` if the date format specified by `’x’` contains other
+variable components (e.g., Julian day, week number, week day).
 ``` cpp
 iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
                       ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted those
+`tm` members, and remaining format characters, used by `time_put<>::put`
+to produce the format specified by `"%H:%M:%S"`, or until it encounters
+an error or end of sequence.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as possibly part of a valid time.
 ``` cpp
 iter_type do_get_date(iter_type s, iter_type end, ios_base& str,
                       ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted those
+`tm` members and remaining format characters used by `time_put<>::put`
+to produce one of the following formats, or until it encounters an
+error. The format depends on the value returned by `date_order()` as
+shown in [[locale.time.get.dogetdate]].
 **Table: `do_get_date` effects** <a id="locale.time.get.dogetdate">[locale.time.get.dogetdate]</a>
 | `date_order()` | Format     |
 | -------------- | ---------- |
                            ios_base::iostate& err, tm* t) const;
 ```
 *Effects:* Reads characters starting at `s` until it has extracted the
 (perhaps abbreviated) name of a weekday or month. If it finds an
+abbreviation that is followed by characters that can match a full name,
+it continues reading until it matches the full name or fails. It sets
+the appropriate `tm` member accordingly.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as part of a valid name.
 ``` cpp
 *Preconditions:* `t` points to an object.
 *Effects:* The function starts by evaluating `err = ios_base::goodbit`.
 It then reads characters starting at `s` until it encounters an error,
+or until it has extracted and assigned those `tm` members, and any
+remaining format characters, corresponding to a conversion specification
+appropriate for the POSIX function `strptime`, formed by concatenating
+`’%’`, the `modifier` character, when non-NUL, and the `format`
+character. When the concatenation fails to yield a complete valid
+directive the function leaves the object pointed to by `t` unchanged and
+evaluates `err |= ios_base::failbit`. When `s == end` evaluates to
+`true` after reading a character the function evaluates
 `err |= ios_base::eofbit`.
+For complex conversion specifications such as `%c`, `%x`, or `%X`, or
+conversion specifications that involve the optional modifiers `E` or
+`O`, when the function is unable to unambiguously determine some or all
+`tm` members from the input sequence \[`s`, `end`), it evaluates
+`err |= ios_base::eofbit`. In such cases the values of those `tm`
 members are unspecified and may be outside their valid range.
 *Returns:* An iterator pointing immediately beyond the last character
 recognized as possibly part of a valid input sequence for the given
 `format` and `modifier`.
+*Remarks:* It is unspecified whether multiple calls to `do_get()` with
+the address of the same `tm` object will update the current contents of
+the object or simply overwrite its members. Portable programs should
+zero out the object before invoking the function.
 #### Class template `time_get_byname` <a id="locale.time.get.byname">[[locale.time.get.byname]]</a>
 ``` cpp
 namespace std {
   template<class charT, class InputIterator = istreambuf_iterator<charT>>
 interleaved in the output in the order in which they appear in the
 pattern. Format sequences are identified by converting each character
 `c` to a `char` value as if by `ct.narrow(c, 0)`, where `ct` is a
 reference to `ctype<charT>` obtained from `str.getloc()`. The first
 character of each sequence is equal to `’%’`, followed by an optional
+modifier character `mod`[^17]
+and a format specifier character `spec` as defined for the function
+`strftime`. If no modifier character is present, `mod` is zero. For each
+valid format sequence identified, calls
 `do_put(s, str, fill, t, spec, mod)`.
 The second form calls `do_put(s, str, fill, t, format, modifier)`.
+[*Note 1*: The `fill` argument can be used in the
 implementation-defined formats or by derivations. A space character is a
 reasonable default for this argument. — *end note*]
 *Returns:* An iterator pointing immediately after the last character
 produced.
 *Effects:* Formats the contents of the parameter `t` into characters
 placed on the output sequence `s`. Formatting is controlled by the
 parameters `format` and `modifier`, interpreted identically as the
 format specifiers in the string argument to the standard library
+function `strftime()`, except that the sequence of characters produced
+for those specifiers that are described as depending on the C locale are
+instead *implementation-defined*.
+[*Note 2*: Interpretation of the `modifier` argument is
+implementation-defined. — *end note*]
 *Returns:* An iterator pointing immediately after the last character
 produced.
+[*Note 3*: The `fill` argument can be used in the
 implementation-defined formats or by derivations. A space character is a
 reasonable default for this argument. — *end note*]
+*Recommended practice:* Interpretation of the `modifier` should follow
+POSIX conventions. Implementations should refer to other standards such
+as POSIX for a specification of the character sequences produced for
+those specifiers described as depending on the C locale.
 #### Class template `time_put_byname` <a id="locale.time.put.byname">[[locale.time.put.byname]]</a>
 ``` cpp
 namespace std {
   template<class charT, class OutputIterator = ostreambuf_iterator<charT>>

Diff to HTML by rtfpessoa