[locale] - C++20 → C++23

Files changed (1) hide show

tmp/tmp2g_my2en/{from.md → to.md} +35 -24

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

@@ -1,7 +1,9 @@
 ### Class `locale` <a id="locale">[[locale]]</a>
 ``` cpp
 namespace std {
   class locale {
   public:
     // types
@@ -52,11 +54,11 @@ locale’s set of facets.
 Access to the facets of a `locale` is via two function templates,
 `use_facet<>` and `has_facet<>`.
 [*Example 1*:
-An iostream `operator<<` might be implemented as: [^2]
 ``` cpp
 template<class charT, class traits>
 basic_ostream<charT, traits>&
 operator<< (basic_ostream<charT, traits>& s, Date d) {
@@ -65,11 +67,11 @@ operator<< (basic_ostream<charT, traits>& s, Date d) {
     tm tmbuf; d.extract(tmbuf);
     bool failed =
       use_facet<time_put<charT, ostreambuf_iterator<charT, traits>>>(
         s.getloc()).put(s, s, s.fill(), &tmbuf, 'x').failed();
     if (failed)
-      s.setstate(s.badbit);     // might throw
   }
   return s;
 }
 ```
@@ -86,12 +88,15 @@ installed in a locale, and used identically as may standard facets.
 All locale semantics are accessed via `use_facet<>` and `has_facet<>`,
 except that:
 - A member operator template
-  `operator()(const basic_string<C, T, A>&, const basic_string<{}C, T, A>&)`
- is provided so that a locale may be used as a predicate argument to
   the standard collections, to collate strings.
 - Convenient global interfaces are provided for traditional `ctype`
   functions such as `isdigit()` and `isspace()`, so that given a locale
   object `loc` a C++ program can call `isspace(c, loc)`. (This eases
   upgrading existing extractors [[istream.formatted]].)
@@ -140,14 +145,12 @@ that the expression
 is `true`, and represents the union of all categories. Further, the
 expression `(X | Y)`, where `X` and `Y` each represent a single
 category, represents the union of the two categories.
-`locale`
-member functions expecting a `category` argument require one of the
-`category` values defined above, or the union of two or more such
 values. Such a `category` value identifies a set of locale categories.
 Each locale category, in turn, identifies a set of locale facets,
 including at least those shown in [[locale.category.facets]].
 **Table: Locale category facets** <a id="locale.category.facets">[locale.category.facets]</a>
@@ -264,11 +267,11 @@ facet) when the last `locale` object containing the facet is destroyed;
 for `refs == 1`, the implementation never destroys the facet.
 Constructors of all facets defined in this Clause take such an argument
 and pass it along to their `facet` base class constructor. All
 one-argument constructors defined in this Clause are *explicit*,
-preventing their participation in automatic conversions.
 For some standard facets a standard “…`_byname`” class, derived from it,
 implements the virtual function semantics equivalent to that facet of
 the locale constructed by `locale(const char*)` with the same name. Each
 such facet provides a constructor that takes a `const char*` argument,
@@ -335,51 +338,59 @@ any *implementation-defined* values.
 ``` cpp
 explicit locale(const string& std_name);
 ```
-*Effects:* The same as `locale(std_name.c_str())`.
 ``` cpp
-locale(const locale& other, const char* std_name, category);
 ```
 *Effects:* Constructs a locale as a copy of `other` except for the
 facets identified by the `category` argument, which instead implement
 the same semantics as `locale(std_name)`.
-*Throws:* `runtime_error` if the argument is not valid, or is null.
 *Remarks:* The locale has a name if and only if `other` has a name.
 ``` cpp
-locale(const locale& other, const string& std_name, category cat);
 ```
-*Effects:* The same as `locale(other, std_name.c_str(), cat)`.
 ``` cpp
 template<class Facet> locale(const locale& other, Facet* f);
 ```
 *Effects:* Constructs a locale incorporating all facets from the first
 argument except that of type `Facet`, and installs the second argument
 as the remaining facet. If `f` is null, the resulting object is a copy
 of `other`.
-*Remarks:* The resulting locale has no name.
 ``` cpp
 locale(const locale& other, const locale& one, category cats);
 ```
 *Effects:* Constructs a locale incorporating all facets from the first
 argument except those that implement `cats`, which are instead
 incorporated from the second argument.
-*Remarks:* The resulting locale has a name if and only if the first two
-arguments have names.
 ``` cpp
 const locale& operator=(const locale& other) noexcept;
 ```
@@ -425,25 +436,25 @@ template<class charT, class traits, class Allocator>
                   const basic_string<charT, traits, Allocator>& s2) const;
 ```
 *Effects:* Compares two strings according to the `collate<charT>` facet.
-*Remarks:* This member operator template (and therefore `locale` itself)
-meets the requirements for a comparator predicate template
-argument [[algorithms]] applied to strings.
 *Returns:*
 ``` cpp
 use_facet<collate<charT>>(*this).compare(s1.data(), s1.data() + s1.size(),
                                          s2.data(), s2.data() + s2.size()) < 0
 ```
 [*Example 1*:
 A vector of strings `v` can be collated according to collation rules in
-locale `loc` simply by ([[alg.sort]], [[vector]]):
 ``` cpp
 std::sort(v.begin(), v.end(), loc);
 ```
@@ -464,18 +475,18 @@ setlocale(LC_ALL, loc.name().c_str());
 ```
 otherwise, the effect on the C locale, if any, is
 *implementation-defined*.
 *Remarks:* No library function other than `locale::global()` affects the
 value returned by `locale()`.
 [*Note 1*: See  [[c.locales]] for data race considerations when
 `setlocale` is invoked. — *end note*]
-*Returns:* The previous value of `locale()`.
 ``` cpp
 static const locale& classic();
 ```
 The `"C"` locale.

 ### Class `locale` <a id="locale">[[locale]]</a>
+#### General <a id="locale.general">[[locale.general]]</a>
 ``` cpp
 namespace std {
   class locale {
   public:
     // types
 Access to the facets of a `locale` is via two function templates,
 `use_facet<>` and `has_facet<>`.
 [*Example 1*:
+An iostream `operator<<` can be implemented as:[^2]
 ``` cpp
 template<class charT, class traits>
 basic_ostream<charT, traits>&
 operator<< (basic_ostream<charT, traits>& s, Date d) {
     tm tmbuf; d.extract(tmbuf);
     bool failed =
       use_facet<time_put<charT, ostreambuf_iterator<charT, traits>>>(
         s.getloc()).put(s, s, s.fill(), &tmbuf, 'x').failed();
     if (failed)
+      s.setstate(s.badbit);     // can throw
   }
   return s;
 }
 ```
 All locale semantics are accessed via `use_facet<>` and `has_facet<>`,
 except that:
 - A member operator template
+  ``` cpp
+ operator()(const basic_string<C, T, A>&, const basic_string<C, T, A>&)
+  ```
+  is provided so that a locale can be used as a predicate argument to
   the standard collections, to collate strings.
 - Convenient global interfaces are provided for traditional `ctype`
   functions such as `isdigit()` and `isspace()`, so that given a locale
   object `loc` a C++ program can call `isspace(c, loc)`. (This eases
   upgrading existing extractors [[istream.formatted]].)
 is `true`, and represents the union of all categories. Further, the
 expression `(X | Y)`, where `X` and `Y` each represent a single
 category, represents the union of the two categories.
+`locale` member functions expecting a `category` argument require one of
+the `category` values defined above, or the union of two or more such
 values. Such a `category` value identifies a set of locale categories.
 Each locale category, in turn, identifies a set of locale facets,
 including at least those shown in [[locale.category.facets]].
 **Table: Locale category facets** <a id="locale.category.facets">[locale.category.facets]</a>
 for `refs == 1`, the implementation never destroys the facet.
 Constructors of all facets defined in this Clause take such an argument
 and pass it along to their `facet` base class constructor. All
 one-argument constructors defined in this Clause are *explicit*,
+preventing their participation in implicit conversions.
 For some standard facets a standard “…`_byname`” class, derived from it,
 implements the virtual function semantics equivalent to that facet of
 the locale constructed by `locale(const char*)` with the same name. Each
 such facet provides a constructor that takes a `const char*` argument,
 ``` cpp
 explicit locale(const string& std_name);
 ```
+*Effects:* Equivalent to `locale(std_name.c_str())`.
 ``` cpp
+locale(const locale& other, const char* std_name, category cats);
 ```
+*Preconditions:* `cats` is a valid `category` value [[locale.category]].
 *Effects:* Constructs a locale as a copy of `other` except for the
 facets identified by the `category` argument, which instead implement
 the same semantics as `locale(std_name)`.
+*Throws:* `runtime_error` if the second argument is not valid, or is
+null.
 *Remarks:* The locale has a name if and only if `other` has a name.
 ``` cpp
+locale(const locale& other, const string& std_name, category cats);
 ```
+*Effects:* Equivalent to `locale(other, std_name.c_str(), cats)`.
 ``` cpp
 template<class Facet> locale(const locale& other, Facet* f);
 ```
 *Effects:* Constructs a locale incorporating all facets from the first
 argument except that of type `Facet`, and installs the second argument
 as the remaining facet. If `f` is null, the resulting object is a copy
 of `other`.
+*Remarks:* If `f` is null, the resulting locale has the same name as
+`other`. Otherwise, the resulting locale has no name.
 ``` cpp
 locale(const locale& other, const locale& one, category cats);
 ```
+*Preconditions:* `cats` is a valid `category` value.
 *Effects:* Constructs a locale incorporating all facets from the first
 argument except those that implement `cats`, which are instead
 incorporated from the second argument.
+*Remarks:* If `cats` is equal to `locale::none`, the resulting locale
+has a name if and only if the first argument has a name. Otherwise, the
+resulting locale has a name if and only if the first two arguments both
+have names.
 ``` cpp
 const locale& operator=(const locale& other) noexcept;
 ```
                   const basic_string<charT, traits, Allocator>& s2) const;
 ```
 *Effects:* Compares two strings according to the `collate<charT>` facet.
 *Returns:*
 ``` cpp
 use_facet<collate<charT>>(*this).compare(s1.data(), s1.data() + s1.size(),
                                          s2.data(), s2.data() + s2.size()) < 0
 ```
+*Remarks:* This member operator template (and therefore `locale` itself)
+meets the requirements for a comparator predicate template
+argument [[algorithms]] applied to strings.
 [*Example 1*:
 A vector of strings `v` can be collated according to collation rules in
+locale `loc` simply by [[alg.sort]], [[vector]]:
 ``` cpp
 std::sort(v.begin(), v.end(), loc);
 ```
 ```
 otherwise, the effect on the C locale, if any, is
 *implementation-defined*.
+*Returns:* The previous value of `locale()`.
 *Remarks:* No library function other than `locale::global()` affects the
 value returned by `locale()`.
 [*Note 1*: See  [[c.locales]] for data race considerations when
 `setlocale` is invoked. — *end note*]
 ``` cpp
 static const locale& classic();
 ```
 The `"C"` locale.

Diff to HTML by rtfpessoa