[locales] - C++14 → C++17

Files changed (1) hide show

tmp/tmpe2g4mj4c/{from.md → to.md} +58 -333

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

@@ -7,11 +7,11 @@ namespace std {
   class locale {
   public:
     // types:
     class facet;
     class id;
- typedef int category;
     static const category   // values assigned here are for exposition only
       none     = 0,
       collate  = 0x010, ctype    = 0x020,
       monetary = 0x040, numeric  = 0x080,
       time     = 0x100, messages = 0x200,
@@ -53,10 +53,12 @@ it’s just a class interface; at the same time, it’s an index into a
 locale’s set of facets.
 Access to the facets of a `locale` is via two function templates,
 `use_facet<>` and `has_facet<>`.
 An iostream `operator<<` might be implemented as:[^2]
 ``` cpp
 template <class charT, class traits>
 basic_ostream<charT, traits>&
@@ -71,18 +73,22 @@ operator<< (basic_ostream<charT,traits>& s, Date d) {
   }
   return s;
 }
 ```
 In the call to `use_facet<Facet>(loc)`, the type argument chooses a
 facet, making available all members of the named type. If `Facet` is not
 present in a locale, it throws the standard exception `bad_cast`. A
 C++program can check if a locale implements a particular facet with the
 function template `has_facet<Facet>()`. User-defined facets may be
 installed in a locale, and used identically as may standard facets (
 [[facets.examples]]).
 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>&)`
@@ -91,10 +97,12 @@ except that:
 - 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]]).)
 Once a facet reference is obtained from a locale object by calling
 `use_facet<>`, that reference remains usable, and the results from
 member functions of it may be cached and re-used, as long as some locale
 object refers to that facet.
@@ -117,11 +125,11 @@ implementations are not required to avoid data races on it (
 #### `locale` types <a id="locale.types">[[locale.types]]</a>
 ##### Type `locale::category` <a id="locale.category">[[locale.category]]</a>
 ``` cpp
-typedef int category;
 ```
 *Valid* `category` values include the `locale` member bitmask elements
 `collate`, `ctype`, `monetary`, `numeric`, `time`, and `messages`, each
 of which represents a single locale category. In addition, `locale`
@@ -147,11 +155,11 @@ including at least those shown in Table
 [[tab:localization.category.facets]].
 **Table: Locale category facets** <a id="tab:localization.category.facets">[tab:localization.category.facets]</a>
 | Category | Includes facets                                       |
-| -------- | --------------------------------------------------- |
 | collate  | `collate<char>`, `collate<wchar_t>`                   |
 | ctype    | `ctype<char>`, `ctype<wchar_t>`                       |
 |          | `codecvt<char, char, mbstate_t>`                      |
 |          | `codecvt<char16_t, char, mbstate_t>`                  |
 |          | `codecvt<char32_t, char, mbstate_t>`                  |
@@ -168,22 +176,22 @@ including at least those shown in Table
 | messages | `messages<char>`, `messages<wchar_t>`                 |
 For any locale `loc` either constructed, or returned by
 `locale::classic()`, and any facet `Facet` shown in Table
-[[tab:localization.category.facets]], `has_facet<Facet>(loc)` is true.
 Each `locale` member function which takes a `locale::category` argument
 operates on the corresponding set of facets.
 An implementation is required to provide those specializations for facet
 templates identified as members of a category, and for those shown in
 Table  [[tab:localization.required.specializations]].
 **Table: Required specializations** <a id="tab:localization.required.specializations">[tab:localization.required.specializations]</a>
 | Category | Includes facets                                           |
-| -------- | ------------------------------------------------------- |
 | collate  | `collate_byname<char>`, `collate_byname<wchar_t>`         |
 | ctype    | `ctype_byname<char>`, `ctype_byname<wchar_t>`             |
 |          | `codecvt_byname<char, char, mbstate_t>`                   |
 |          | `codecvt_byname<char16_t, char, mbstate_t>`               |
 |          | `codecvt_byname<char32_t, char, mbstate_t>`               |
@@ -215,14 +223,14 @@ In declarations of facets, a template parameter with name
 `InputIterator` or `OutputIterator` indicates the set of all possible
 specializations on parameters that satisfy the requirements of an Input
 Iterator or an Output Iterator, respectively (
 [[iterator.requirements]]). A template parameter with name `C`
 represents the set of types containing `char`, `wchar_t`, and any other
-implementation-defined character types that satisfy the requirements for
-a character on which any of the iostream components can be instantiated.
-A template parameter with name `International` represents the set of all
-possible specializations on a bool parameter.
 ##### Class `locale::facet` <a id="locale.facet">[[locale.facet]]</a>
 ``` cpp
 namespace std {
@@ -234,25 +242,32 @@ namespace std {
     void operator=(const facet&) = delete;
   };
 }
 ```
 Template parameters in this Clause which are required to be facets are
 those named `Facet` in declarations. A program that passes a type that
 is *not* a facet, or a type that refers to a volatile-qualified facet,
 as an (explicit or deduced) template parameter to a locale function
 expecting a facet, is ill-formed. A const-qualified facet is a valid
 template argument to any locale function that expects a Facet template
 parameter.
 The `refs` argument to the constructor is used for lifetime management.
-- For `refs == 0`, the implementation performs
 `delete static_cast<locale::facet*>(f)` (where `f` is a pointer to the
- 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.
@@ -280,21 +295,21 @@ namespace std {
     id(const id&) = delete;
   };
 }
 ```
-The class locale::id provides identification of a locale facet
 interface, used as an index for lookup and to encapsulate
 initialization.
-Because facets are used by iostreams, potentially while static
-constructors are running, their initialization cannot depend on
 programmed static initialization. One initialization strategy is for
 `locale` to initialize each facet’s `id` member the first time an
 instance of the facet is installed into a locale. This depends only on
 static storage being zero before constructors run (
-[[basic.start.init]]).
 #### `locale` constructors and destructor <a id="locale.cons">[[locale.cons]]</a>
 ``` cpp
 locale() noexcept;
@@ -303,12 +318,15 @@ locale() noexcept;
 Default constructor: a snapshot of the current global locale.
 *Effects:* Constructs a copy of the argument last passed to
 `locale::global(locale&)`, if it has been called; else, the resulting
 facets have virtual function semantics identical to those of
-`locale::classic()`. This constructor is commonly used as the default
-value for arguments of functions that take a `const locale&` argument.
 ``` cpp
 locale(const locale& other) noexcept;
 ```
@@ -377,11 +395,11 @@ arguments have names.
 const locale& operator=(const locale& other) noexcept;
 ```
 *Effects:* Creates a copy of `other`, replacing the current value.
-*Returns:* `*this`
 ``` cpp
 ~locale();
 ```
@@ -396,23 +414,20 @@ template <class Facet> locale combine(const locale& other) const;
 *Effects:* Constructs a locale incorporating all facets from `*this`
 except for that one facet of `other` that is identified by `Facet`.
 *Returns:* The newly created locale.
-*Throws:* `runtime_error` if `has_facet<Facet>(other)` is false.
 *Remarks:* The resulting locale has no name.
 ``` cpp
 basic_string<char> name() const;
 ```
 *Returns:* The name of `*this`, if it has one; otherwise, the string
-`"*"`. If `*this` has a name, then
-`locale(name().c`\textunderscore`str())` is equivalent to `*this`.
-Details of the contents of the resulting string are otherwise
-implementation-defined.
 #### `locale` operators <a id="locale.operators">[[locale.operators]]</a>
 ``` cpp
 bool operator==(const locale& other) const;
@@ -424,11 +439,11 @@ copy of the other, or each has a name and the names are identical;
 ``` cpp
 bool operator!=(const locale& other) const;
 ```
-*Returns:* The result of the expression: `!(*this == other)`.
 ``` cpp
 template <class charT, class traits, class Allocator>
   bool operator()(const basic_string<charT, traits, Allocator>& s1,
                   const basic_string<charT, traits, Allocator>& s2) const;
@@ -438,24 +453,28 @@ template <class charT, class traits, class Allocator>
 *Remarks:* This member operator template (and therefore `locale` itself)
 satisfies requirements for a comparator predicate template argument
 (Clause  [[algorithms]]) applied to strings.
-*Returns:* The result of the following expression:
 ``` cpp
-use_facet< collate<charT> >(*this).compare
-  (s1.data(), s1.data()+s1.size(), s2.data(), s2.data()+s2.size()) < 0;
 ```
 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);
 ```
 #### `locale` static members <a id="locale.statics">[[locale.statics]]</a>
 ``` cpp
 static locale global(const locale& loc);
 ```
@@ -464,18 +483,19 @@ Sets the global locale to its argument.
 *Effects:* Causes future calls to the constructor `locale()` to return a
 copy of the argument. If the argument has a name, does
 ``` cpp
-std::setlocale(LC_ALL, loc.name().c_str());
 ```
 otherwise, the effect on the C locale, if any, is
 *implementation-defined*. No library function other than
 `locale::global()` shall affect the value returned by `locale()`.
-See  [[c.locales]] for data race considerations when `setlocale` is
-invoked.
 *Returns:* The previous value of `locale()`.
 ``` cpp
 static const locale& classic();
@@ -507,12 +527,12 @@ copy of `loc` exists.
 ``` cpp
 template <class Facet> bool has_facet(const locale& loc) noexcept;
 ```
-*Returns:* True if the facet requested is present in `loc`; otherwise
-false.
 ### Convenience interfaces <a id="locale.convenience">[[locale.convenience]]</a>
 #### Character classification <a id="classification">[[classification]]</a>
@@ -529,19 +549,18 @@ template <class charT> bool isxdigit(charT c, const locale& loc);
 template <class charT> bool isalnum (charT c, const locale& loc);
 template <class charT> bool isgraph (charT c, const locale& loc);
 template <class charT> bool isblank (charT c, const locale& loc);
 ```
-Each of these functions `is\textbf{F}` returns the result of the
-expression:
 ``` cpp
 use_facet<ctype<charT>>(loc).is(ctype_base::F, c)
 ```
-where ***F*** is the `ctype_base::mask` value corresponding to that
-function ([[category.ctype]]).[^3]
 #### Conversions <a id="conversions">[[conversions]]</a>
 ##### Character conversions <a id="conversions.character">[[conversions.character]]</a>
@@ -555,299 +574,5 @@ template <class charT> charT toupper(charT c, const locale& loc);
 template <class charT> charT tolower(charT c, const locale& loc);
 ```
 *Returns:* `use_facet<ctype<charT>>(loc).tolower(c)`.
-##### `string` conversions <a id="conversions.string">[[conversions.string]]</a>
-Class template `wstring_convert` performs conversions between a wide
-string and a byte string. It lets you specify a code conversion facet
-(like class template `codecvt`) to perform the conversions, without
-affecting any streams or locales. If you want to use the code conversion
-facet `codecvt_utf8` to output to `cout` a UTF-8 multibyte sequence
-corresponding to a wide string, but you don’t want to alter the locale
-for `cout`, you can write something like:
-``` cpp
-wstring_convert<std::codecvt_utf8<wchar_t>> myconv;
-std::string mbstring = myconv.to_bytes(L"Hello\n");
-std::cout << mbstring;
-```
-``` cpp
-namespace std {
-template<class Codecvt, class Elem = wchar_t,
-    class Wide_alloc = std::allocator<Elem>,
-    class Byte_alloc = std::allocator<char> > class wstring_convert {
-  public:
-    typedef std::basic_string<char, char_traits<char>, Byte_alloc> byte_string;
-    typedef std::basic_string<Elem, char_traits<Elem>, Wide_alloc> wide_string;
-    typedef typename Codecvt::state_type state_type;
-    typedef typename wide_string::traits_type::int_type int_type;
-    explicit wstring_convert(Codecvt* pcvt = new Codecvt);
-    wstring_convert(Codecvt* pcvt, state_type state);
-    explicit wstring_convert(const byte_string& byte_err,
-                             const wide_string& wide_err = wide_string());
-    ~wstring_convert();
-    wstring_convert(const wstring_convert&) = delete;
-    wstring_convert& operator=(const wstring_convert&) = delete;
-    wide_string from_bytes(char byte);
-    wide_string from_bytes(const char* ptr);
-    wide_string from_bytes(const byte_string& str);
-    wide_string from_bytes(const char* first, const char* last);
-    byte_string to_bytes(Elem wchar);
-    byte_string to_bytes(const Elem* wptr);
-    byte_string to_bytes(const wide_string& wstr);
-    byte_string to_bytes(const Elem* first, const Elem* last);
-    size_t converted() const noexcept;
-    state_type state() const;
-  private:
-    byte_string byte_err_string;    // exposition only
-    wide_string wide_err_string;    // exposition only
-    Codecvt* cvtptr;                // exposition only
-    state_type cvtstate;            // exposition only
-    size_t cvtcount;                // exposition only
-  };
-}
-```
-The class template describes an object that controls conversions between
-wide string objects of class `std::basic_string<Elem, char_traits<Elem>,
-Wide_alloc>` and byte string objects of class `std::\\basic_string<char,
-char_traits<char>, Byte_alloc>`. The class template defines the types
-`wide_string` and `byte_string` as synonyms for these two types.
-Conversion between a sequence of `Elem` values (stored in a
-`wide_string` object) and multibyte sequences (stored in a `byte_string`
-object) is performed by an object of class `Codecvt`, which meets the
-requirements of the standard code-conversion facet `std::codecvt<Elem,
-char, std::mbstate_t>`.
-An object of this class template stores:
-- `byte_err_string` — a byte string to display on errors
-- `wide_err_string` — a wide string to display on errors
-- `cvtptr` — a pointer to the allocated conversion object (which is
-  freed when the `wstring_convert` object is destroyed)
-- `cvtstate` — a conversion state object
-- `cvtcount` — a conversion count
-``` cpp
-typedef std::basic_string<char, char_traits<char>, Byte_alloc> byte_string;
-```
-The type shall be a synonym for
-`std::basic_string<char, char_traits<char>, Byte_alloc>`
-``` cpp
-size_t converted() const noexcept;
-```
-*Returns:* `cvtcount`.
-``` cpp
-wide_string from_bytes(char byte);
-wide_string from_bytes(const char* ptr);
-wide_string from_bytes(const byte_string& str);
-wide_string from_bytes(const char* first, const char* last);
-```
-*Effects:* The first member function shall convert the single-element
-sequence `byte` to a wide string. The second member function shall
-convert the null-terminated sequence beginning at `ptr` to a wide
-string. The third member function shall convert the sequence stored in
-`str` to a wide string. The fourth member function shall convert the
-sequence defined by the range \[`first`, `last`) to a wide string.
-In all cases:
-- If the `cvtstate` object was not constructed with an explicit value,
-  it shall be set to its default value (the initial conversion state)
-  before the conversion begins. Otherwise it shall be left unchanged.
-- The number of input elements successfully converted shall be stored in
-  `cvtcount`.
-*Returns:* If no conversion error occurs, the member function shall
-return the converted wide string. Otherwise, if the object was
-constructed with a wide-error string, the member function shall return
-the wide-error string. Otherwise, the member function throws an object
-of class `std::range_error`.
-``` cpp
-typedef typename wide_string::traits_type::int_type int_type;
-```
-The type shall be a synonym for `wide_string::traits_type::int_type`.
-``` cpp
-state_type state() const;
-```
-returns `cvtstate`.
-``` cpp
-typedef typename Codecvt::state_type state_type;
-```
-The type shall be a synonym for `Codecvt::state_type`.
-``` cpp
-byte_string to_bytes(Elem wchar);
-byte_string to_bytes(const Elem* wptr);
-byte_string to_bytes(const wide_string& wstr);
-byte_string to_bytes(const Elem* first, const Elem* last);
-```
-*Effects:* The first member function shall convert the single-element
-sequence `wchar` to a byte string. The second member function shall
-convert the null-terminated sequence beginning at `wptr` to a byte
-string. The third member function shall convert the sequence stored in
-`wstr` to a byte string. The fourth member function shall convert the
-sequence defined by the range \[`first`, `last`) to a byte string.
-In all cases:
-- If the `cvtstate` object was not constructed with an explicit value,
-  it shall be set to its default value (the initial conversion state)
-  before the conversion begins. Otherwise it shall be left unchanged.
-- The number of input elements successfully converted shall be stored in
-  `cvtcount`.
-*Returns:* If no conversion error occurs, the member function shall
-return the converted byte string. Otherwise, if the object was
-constructed with a byte-error string, the member function shall return
-the byte-error string. Otherwise, the member function shall throw an
-object of class `std::range_error`.
-``` cpp
-typedef std::basic_string<Elem, char_traits<Elem>, Wide_alloc> wide_string;
-```
-The type shall be a synonym for
-`std::basic_string<Elem, char_traits<Elem>, Wide_alloc>`.
-``` cpp
-explicit wstring_convert(Codecvt* pcvt = new Codecvt);
-wstring_convert(Codecvt* pcvt, state_type state);
-explicit wstring_convert(const byte_string& byte_err,
-    const wide_string& wide_err = wide_string());
-```
-*Requires:* For the first and second constructors, `pcvt != nullptr`.
-*Effects:* The first constructor shall store `pcvt` in `cvtptr` and
-default values in `cvtstate`, `byte_err_string`, and `wide_err_string`.
-The second constructor shall store `pcvt` in `cvtptr`, `state` in
-`cvtstate`, and default values in `byte_err_string` and
-`wide_err_string`; moreover the stored state shall be retained between
-calls to `from_bytes` and `to_bytes`. The third constructor shall store
-`new Codecvt` in `cvtptr`, `state_type()` in `cvtstate`, `byte_err` in
-`byte_err_string`, and `wide_err` in `wide_err_string`.
-``` cpp
-~wstring_convert();
-```
-*Effects:* The destructor shall delete `cvtptr`.
-##### Buffer conversions <a id="conversions.buffer">[[conversions.buffer]]</a>
-Class template `wbuffer_convert` looks like a wide stream buffer, but
-performs all its I/O through an underlying byte stream buffer that you
-specify when you construct it. Like class template `wstring_convert`, it
-lets you specify a code conversion facet to perform the conversions,
-without affecting any streams or locales.
-``` cpp
-namespace std {
-template<class Codecvt,
-    class Elem = wchar_t,
-    class Tr = std::char_traits<Elem> >
-  class wbuffer_convert
-    : public std::basic_streambuf<Elem, Tr> {
-  public:
-    typedef typename Codecvt::state_type state_type;
-    explicit wbuffer_convert(std::streambuf* bytebuf = 0,
-                             Codecvt* pcvt = new Codecvt,
-                             state_type state = state_type());
-    ~wbuffer_convert();
-    wbuffer_convert(const wbuffer_convert&) = delete;
-    wbuffer_convert& operator=(const wbuffer_convert&) = delete;
-    std::streambuf* rdbuf() const;
-    std::streambuf* rdbuf(std::streambuf* bytebuf);
-    state_type state() const;
-  private:
-    std::streambuf* bufptr;         // exposition only
-    Codecvt* cvtptr;                // exposition only
-    state_type cvtstate;            // exposition only
-  };
-}
-```
-The class template describes a stream buffer that controls the
-transmission of elements of type `Elem`, whose character traits are
-described by the class `Tr`, to and from a byte stream buffer of type
-`std::streambuf`. Conversion between a sequence of `Elem` values and
-multibyte sequences is performed by an object of class `Codecvt`, which
-shall meet the requirements of the standard code-conversion facet
-`std::codecvt<Elem, char, std::mbstate_t>`.
-An object of this class template stores:
-- `bufptr` — a pointer to its underlying byte stream buffer
-- `cvtptr` — a pointer to the allocated conversion object (which is
-  freed when the `wbuffer_convert` object is destroyed)
-- `cvtstate` — a conversion state object
-``` cpp
-state_type state() const;
-```
-*Returns:* `cvtstate`.
-``` cpp
-std::streambuf* rdbuf() const;
-```
-*Returns:* `bufptr`.
-``` cpp
-std::streambuf* rdbuf(std::streambuf* bytebuf);
-```
-*Effects:* stores `bytebuf` in `bufptr`.
-*Returns:* The previous value of `bufptr`.
-``` cpp
-typedef typename Codecvt::state_type state_type;
-```
-The type shall be a synonym for `Codecvt::state_type`.
-``` cpp
-explicit wbuffer_convert(std::streambuf* bytebuf = 0,
-    Codecvt* pcvt = new Codecvt, state_type state = state_type());
-```
-*Requires:* `pcvt != nullptr`.
-*Effects:* The constructor constructs a stream buffer object,
-initializes `bufptr` to `bytebuf`, initializes `cvtptr` to `pcvt`, and
-initializes `cvtstate` to `state`.
-``` cpp
-~wbuffer_convert();
-```
-*Effects:* The destructor shall delete `cvtptr`.

   class locale {
   public:
     // types:
     class facet;
     class id;
+ using category = int;
     static const category   // values assigned here are for exposition only
       none     = 0,
       collate  = 0x010, ctype    = 0x020,
       monetary = 0x040, numeric  = 0x080,
       time     = 0x100, messages = 0x200,
 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>&
   }
   return s;
 }
 ```
+— *end example*]
 In the call to `use_facet<Facet>(loc)`, the type argument chooses a
 facet, making available all members of the named type. If `Facet` is not
 present in a locale, it throws the standard exception `bad_cast`. A
 C++program can check if a locale implements a particular facet with the
 function template `has_facet<Facet>()`. User-defined facets may be
 installed in a locale, and used identically as may standard facets (
 [[facets.examples]]).
+[*Note 1*:
 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>&)`
 - 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]]).)
+— *end note*]
 Once a facet reference is obtained from a locale object by calling
 `use_facet<>`, that reference remains usable, and the results from
 member functions of it may be cached and re-used, as long as some locale
 object refers to that facet.
 #### `locale` types <a id="locale.types">[[locale.types]]</a>
 ##### Type `locale::category` <a id="locale.category">[[locale.category]]</a>
 ``` cpp
+using category = int;
 ```
 *Valid* `category` values include the `locale` member bitmask elements
 `collate`, `ctype`, `monetary`, `numeric`, `time`, and `messages`, each
 of which represents a single locale category. In addition, `locale`
 [[tab:localization.category.facets]].
 **Table: Locale category facets** <a id="tab:localization.category.facets">[tab:localization.category.facets]</a>
 | Category | Includes facets                                       |
+| -------- | ----------------------------------------------------- |
 | collate  | `collate<char>`, `collate<wchar_t>`                   |
 | ctype    | `ctype<char>`, `ctype<wchar_t>`                       |
 |          | `codecvt<char, char, mbstate_t>`                      |
 |          | `codecvt<char16_t, char, mbstate_t>`                  |
 |          | `codecvt<char32_t, char, mbstate_t>`                  |
 | messages | `messages<char>`, `messages<wchar_t>`                 |
 For any locale `loc` either constructed, or returned by
 `locale::classic()`, and any facet `Facet` shown in Table
+[[tab:localization.category.facets]], `has_facet<Facet>(loc)` is `true`.
 Each `locale` member function which takes a `locale::category` argument
 operates on the corresponding set of facets.
 An implementation is required to provide those specializations for facet
 templates identified as members of a category, and for those shown in
 Table  [[tab:localization.required.specializations]].
 **Table: Required specializations** <a id="tab:localization.required.specializations">[tab:localization.required.specializations]</a>
 | Category | Includes facets                                           |
+| -------- | --------------------------------------------------------- |
 | collate  | `collate_byname<char>`, `collate_byname<wchar_t>`         |
 | ctype    | `ctype_byname<char>`, `ctype_byname<wchar_t>`             |
 |          | `codecvt_byname<char, char, mbstate_t>`                   |
 |          | `codecvt_byname<char16_t, char, mbstate_t>`               |
 |          | `codecvt_byname<char32_t, char, mbstate_t>`               |
 `InputIterator` or `OutputIterator` indicates the set of all possible
 specializations on parameters that satisfy the requirements of an Input
 Iterator or an Output Iterator, respectively (
 [[iterator.requirements]]). A template parameter with name `C`
 represents the set of types containing `char`, `wchar_t`, and any other
+*implementation-defined* character types that satisfy the requirements
+for a character on which any of the iostream components can be
+instantiated. A template parameter with name `International` represents
+the set of all possible specializations on a bool parameter.
 ##### Class `locale::facet` <a id="locale.facet">[[locale.facet]]</a>
 ``` cpp
 namespace std {
     void operator=(const facet&) = delete;
   };
 }
 ```
+Class `facet` is the base class for locale feature sets. A class is a
+*facet* if it is publicly derived from another facet, or if it is a
+class derived from `locale::facet` and contains a publicly accessible
+declaration as follows: [^3]
+``` cpp
+static ::std::locale::id id;
+```
 Template parameters in this Clause which are required to be facets are
 those named `Facet` in declarations. A program that passes a type that
 is *not* a facet, or a type that refers to a volatile-qualified facet,
 as an (explicit or deduced) template parameter to a locale function
 expecting a facet, is ill-formed. A const-qualified facet is a valid
 template argument to any locale function that expects a Facet template
 parameter.
 The `refs` argument to the constructor is used for lifetime management.
+For `refs == 0`, the implementation performs
 `delete static_cast<locale::facet*>(f)` (where `f` is a pointer to the
+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.
     id(const id&) = delete;
   };
 }
 ```
+The class `locale::id` provides identification of a locale facet
 interface, used as an index for lookup and to encapsulate
 initialization.
+[*Note 1*: Because facets are used by iostreams, potentially while
+static constructors are running, their initialization cannot depend on
 programmed static initialization. One initialization strategy is for
 `locale` to initialize each facet’s `id` member the first time an
 instance of the facet is installed into a locale. This depends only on
 static storage being zero before constructors run (
+[[basic.start.static]]). — *end note*]
 #### `locale` constructors and destructor <a id="locale.cons">[[locale.cons]]</a>
 ``` cpp
 locale() noexcept;
 Default constructor: a snapshot of the current global locale.
 *Effects:* Constructs a copy of the argument last passed to
 `locale::global(locale&)`, if it has been called; else, the resulting
 facets have virtual function semantics identical to those of
+`locale::classic()`.
+[*Note 1*: This constructor is commonly used as the default value for
+arguments of functions that take a `const locale&`
+argument. — *end note*]
 ``` cpp
 locale(const locale& other) noexcept;
 ```
 const locale& operator=(const locale& other) noexcept;
 ```
 *Effects:* Creates a copy of `other`, replacing the current value.
+*Returns:* `*this`.
 ``` cpp
 ~locale();
 ```
 *Effects:* Constructs a locale incorporating all facets from `*this`
 except for that one facet of `other` that is identified by `Facet`.
 *Returns:* The newly created locale.
+*Throws:* `runtime_error` if `has_facet<Facet>(other)` is `false`.
 *Remarks:* The resulting locale has no name.
 ``` cpp
 basic_string<char> name() const;
 ```
 *Returns:* The name of `*this`, if it has one; otherwise, the string
+`"*"`.
 #### `locale` operators <a id="locale.operators">[[locale.operators]]</a>
 ``` cpp
 bool operator==(const locale& other) const;
 ``` cpp
 bool operator!=(const locale& other) const;
 ```
+*Returns:* `!(*this == other)`.
 ``` cpp
 template <class charT, class traits, class Allocator>
   bool operator()(const basic_string<charT, traits, Allocator>& s1,
                   const basic_string<charT, traits, Allocator>& s2) const;
 *Remarks:* This member operator template (and therefore `locale` itself)
 satisfies requirements for a comparator predicate template argument
 (Clause  [[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);
 ```
+— *end example*]
 #### `locale` static members <a id="locale.statics">[[locale.statics]]</a>
 ``` cpp
 static locale global(const locale& loc);
 ```
 *Effects:* Causes future calls to the constructor `locale()` to return a
 copy of the argument. If the argument has a name, does
 ``` cpp
+setlocale(LC_ALL, loc.name().c_str());
 ```
 otherwise, the effect on the C locale, if any, is
 *implementation-defined*. No library function other than
 `locale::global()` shall affect 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();
 ``` cpp
 template <class Facet> bool has_facet(const locale& loc) noexcept;
 ```
+*Returns:* `true` if the facet requested is present in `loc`; otherwise
+`false`.
 ### Convenience interfaces <a id="locale.convenience">[[locale.convenience]]</a>
 #### Character classification <a id="classification">[[classification]]</a>
 template <class charT> bool isalnum (charT c, const locale& loc);
 template <class charT> bool isgraph (charT c, const locale& loc);
 template <class charT> bool isblank (charT c, const locale& loc);
 ```
+Each of these functions `isF` returns the result of the expression:
 ``` cpp
 use_facet<ctype<charT>>(loc).is(ctype_base::F, c)
 ```
+where `F` is the `ctype_base::mask` value corresponding to that
+function ([[category.ctype]]).[^4]
 #### Conversions <a id="conversions">[[conversions]]</a>
 ##### Character conversions <a id="conversions.character">[[conversions.character]]</a>
 template <class charT> charT tolower(charT c, const locale& loc);
 ```
 *Returns:* `use_facet<ctype<charT>>(loc).tolower(c)`.

Diff to HTML by rtfpessoa