From Jason Turner

[locale]

C++14 → C++17 12.4 KB 104 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/tmp6qb9cawy/{from.md → to.md} +53 -33
tmp/tmp6qb9cawy/{from.md → to.md} RENAMED
@@ -5,11 +5,11 @@ namespace std {
5
  class locale {
6
  public:
7
  // types:
8
  class facet;
9
  class id;
10
- typedef int category;
11
  static const category // values assigned here are for exposition only
12
  none = 0,
13
  collate = 0x010, ctype = 0x020,
14
  monetary = 0x040, numeric = 0x080,
15
  time = 0x100, messages = 0x200,
@@ -51,10 +51,12 @@ it’s just a class interface; at the same time, it’s an index into a
51
  locale’s set of facets.
52
 
53
  Access to the facets of a `locale` is via two function templates,
54
  `use_facet<>` and `has_facet<>`.
55
 
 
 
56
  An iostream `operator<<` might be implemented as:[^2]
57
 
58
  ``` cpp
59
  template <class charT, class traits>
60
  basic_ostream<charT, traits>&
@@ -69,18 +71,22 @@ operator<< (basic_ostream<charT,traits>& s, Date d) {
69
  }
70
  return s;
71
  }
72
  ```
73
 
 
 
74
  In the call to `use_facet<Facet>(loc)`, the type argument chooses a
75
  facet, making available all members of the named type. If `Facet` is not
76
  present in a locale, it throws the standard exception `bad_cast`. A
77
  C++program can check if a locale implements a particular facet with the
78
  function template `has_facet<Facet>()`. User-defined facets may be
79
  installed in a locale, and used identically as may standard facets (
80
  [[facets.examples]]).
81
 
 
 
82
  All locale semantics are accessed via `use_facet<>` and `has_facet<>`,
83
  except that:
84
 
85
  - A member operator template
86
  `operator()(const basic_string<C, T, A>&, const basic_string<{}C, T, A>&)`
@@ -89,10 +95,12 @@ except that:
89
  - Convenient global interfaces are provided for traditional `ctype`
90
  functions such as `isdigit()` and `isspace()`, so that given a locale
91
  object `loc` a C++program can call `isspace(c, loc)`. (This eases
92
  upgrading existing extractors ([[istream.formatted]]).)
93
 
 
 
94
  Once a facet reference is obtained from a locale object by calling
95
  `use_facet<>`, that reference remains usable, and the results from
96
  member functions of it may be cached and re-used, as long as some locale
97
  object refers to that facet.
98
 
@@ -115,11 +123,11 @@ implementations are not required to avoid data races on it (
115
  #### `locale` types <a id="locale.types">[[locale.types]]</a>
116
 
117
  ##### Type `locale::category` <a id="locale.category">[[locale.category]]</a>
118
 
119
  ``` cpp
120
- typedef int category;
121
  ```
122
 
123
  *Valid* `category` values include the `locale` member bitmask elements
124
  `collate`, `ctype`, `monetary`, `numeric`, `time`, and `messages`, each
125
  of which represents a single locale category. In addition, `locale`
@@ -145,11 +153,11 @@ including at least those shown in Table 
145
  [[tab:localization.category.facets]].
146
 
147
  **Table: Locale category facets** <a id="tab:localization.category.facets">[tab:localization.category.facets]</a>
148
 
149
  | Category | Includes facets |
150
- | -------- | --------------------------------------------------- |
151
  | collate | `collate<char>`, `collate<wchar_t>` |
152
  | ctype | `ctype<char>`, `ctype<wchar_t>` |
153
  | | `codecvt<char, char, mbstate_t>` |
154
  | | `codecvt<char16_t, char, mbstate_t>` |
155
  | | `codecvt<char32_t, char, mbstate_t>` |
@@ -166,22 +174,22 @@ including at least those shown in Table 
166
  | messages | `messages<char>`, `messages<wchar_t>` |
167
 
168
 
169
  For any locale `loc` either constructed, or returned by
170
  `locale::classic()`, and any facet `Facet` shown in Table 
171
- [[tab:localization.category.facets]], `has_facet<Facet>(loc)` is true.
172
  Each `locale` member function which takes a `locale::category` argument
173
  operates on the corresponding set of facets.
174
 
175
  An implementation is required to provide those specializations for facet
176
  templates identified as members of a category, and for those shown in
177
  Table  [[tab:localization.required.specializations]].
178
 
179
  **Table: Required specializations** <a id="tab:localization.required.specializations">[tab:localization.required.specializations]</a>
180
 
181
  | Category | Includes facets |
182
- | -------- | ------------------------------------------------------- |
183
  | collate | `collate_byname<char>`, `collate_byname<wchar_t>` |
184
  | ctype | `ctype_byname<char>`, `ctype_byname<wchar_t>` |
185
  | | `codecvt_byname<char, char, mbstate_t>` |
186
  | | `codecvt_byname<char16_t, char, mbstate_t>` |
187
  | | `codecvt_byname<char32_t, char, mbstate_t>` |
@@ -213,14 +221,14 @@ In declarations of facets, a template parameter with name
213
  `InputIterator` or `OutputIterator` indicates the set of all possible
214
  specializations on parameters that satisfy the requirements of an Input
215
  Iterator or an Output Iterator, respectively (
216
  [[iterator.requirements]]). A template parameter with name `C`
217
  represents the set of types containing `char`, `wchar_t`, and any other
218
- implementation-defined character types that satisfy the requirements for
219
- a character on which any of the iostream components can be instantiated.
220
- A template parameter with name `International` represents the set of all
221
- possible specializations on a bool parameter.
222
 
223
  ##### Class `locale::facet` <a id="locale.facet">[[locale.facet]]</a>
224
 
225
  ``` cpp
226
  namespace std {
@@ -232,25 +240,32 @@ namespace std {
232
  void operator=(const facet&) = delete;
233
  };
234
  }
235
  ```
236
 
 
 
 
 
 
 
 
 
 
237
  Template parameters in this Clause which are required to be facets are
238
  those named `Facet` in declarations. A program that passes a type that
239
  is *not* a facet, or a type that refers to a volatile-qualified facet,
240
  as an (explicit or deduced) template parameter to a locale function
241
  expecting a facet, is ill-formed. A const-qualified facet is a valid
242
  template argument to any locale function that expects a Facet template
243
  parameter.
244
 
245
  The `refs` argument to the constructor is used for lifetime management.
246
-
247
- - For `refs == 0`, the implementation performs
248
  `delete static_cast<locale::facet*>(f)` (where `f` is a pointer to the
249
- facet) when the last `locale` object containing the facet is
250
- destroyed; for `refs == 1`, the implementation never destroys the
251
- facet.
252
 
253
  Constructors of all facets defined in this Clause take such an argument
254
  and pass it along to their `facet` base class constructor. All
255
  one-argument constructors defined in this Clause are *explicit*,
256
  preventing their participation in automatic conversions.
@@ -278,21 +293,21 @@ namespace std {
278
  id(const id&) = delete;
279
  };
280
  }
281
  ```
282
 
283
- The class locale::id provides identification of a locale facet
284
  interface, used as an index for lookup and to encapsulate
285
  initialization.
286
 
287
- Because facets are used by iostreams, potentially while static
288
- constructors are running, their initialization cannot depend on
289
  programmed static initialization. One initialization strategy is for
290
  `locale` to initialize each facet’s `id` member the first time an
291
  instance of the facet is installed into a locale. This depends only on
292
  static storage being zero before constructors run (
293
- [[basic.start.init]]).
294
 
295
  #### `locale` constructors and destructor <a id="locale.cons">[[locale.cons]]</a>
296
 
297
  ``` cpp
298
  locale() noexcept;
@@ -301,12 +316,15 @@ locale() noexcept;
301
  Default constructor: a snapshot of the current global locale.
302
 
303
  *Effects:* Constructs a copy of the argument last passed to
304
  `locale::global(locale&)`, if it has been called; else, the resulting
305
  facets have virtual function semantics identical to those of
306
- `locale::classic()`. This constructor is commonly used as the default
307
- value for arguments of functions that take a `const locale&` argument.
 
 
 
308
 
309
  ``` cpp
310
  locale(const locale& other) noexcept;
311
  ```
312
 
@@ -375,11 +393,11 @@ arguments have names.
375
  const locale& operator=(const locale& other) noexcept;
376
  ```
377
 
378
  *Effects:* Creates a copy of `other`, replacing the current value.
379
 
380
- *Returns:* `*this`
381
 
382
  ``` cpp
383
  ~locale();
384
  ```
385
 
@@ -394,23 +412,20 @@ template <class Facet> locale combine(const locale& other) const;
394
  *Effects:* Constructs a locale incorporating all facets from `*this`
395
  except for that one facet of `other` that is identified by `Facet`.
396
 
397
  *Returns:* The newly created locale.
398
 
399
- *Throws:* `runtime_error` if `has_facet<Facet>(other)` is false.
400
 
401
  *Remarks:* The resulting locale has no name.
402
 
403
  ``` cpp
404
  basic_string<char> name() const;
405
  ```
406
 
407
  *Returns:* The name of `*this`, if it has one; otherwise, the string
408
- `"*"`. If `*this` has a name, then
409
- `locale(name().c`\textunderscore`str())` is equivalent to `*this`.
410
- Details of the contents of the resulting string are otherwise
411
- implementation-defined.
412
 
413
  #### `locale` operators <a id="locale.operators">[[locale.operators]]</a>
414
 
415
  ``` cpp
416
  bool operator==(const locale& other) const;
@@ -422,11 +437,11 @@ copy of the other, or each has a name and the names are identical;
422
 
423
  ``` cpp
424
  bool operator!=(const locale& other) const;
425
  ```
426
 
427
- *Returns:* The result of the expression: `!(*this == other)`.
428
 
429
  ``` cpp
430
  template <class charT, class traits, class Allocator>
431
  bool operator()(const basic_string<charT, traits, Allocator>& s1,
432
  const basic_string<charT, traits, Allocator>& s2) const;
@@ -436,24 +451,28 @@ template <class charT, class traits, class Allocator>
436
 
437
  *Remarks:* This member operator template (and therefore `locale` itself)
438
  satisfies requirements for a comparator predicate template argument
439
  (Clause  [[algorithms]]) applied to strings.
440
 
441
- *Returns:* The result of the following expression:
442
 
443
  ``` cpp
444
- use_facet< collate<charT> >(*this).compare
445
- (s1.data(), s1.data()+s1.size(), s2.data(), s2.data()+s2.size()) < 0;
446
  ```
447
 
 
 
448
  A vector of strings `v` can be collated according to collation rules in
449
  locale `loc` simply by ([[alg.sort]], [[vector]]):
450
 
451
  ``` cpp
452
  std::sort(v.begin(), v.end(), loc);
453
  ```
454
 
 
 
455
  #### `locale` static members <a id="locale.statics">[[locale.statics]]</a>
456
 
457
  ``` cpp
458
  static locale global(const locale& loc);
459
  ```
@@ -462,18 +481,19 @@ Sets the global locale to its argument.
462
 
463
  *Effects:* Causes future calls to the constructor `locale()` to return a
464
  copy of the argument. If the argument has a name, does
465
 
466
  ``` cpp
467
- std::setlocale(LC_ALL, loc.name().c_str());
468
  ```
469
 
470
  otherwise, the effect on the C locale, if any, is
471
  *implementation-defined*. No library function other than
472
  `locale::global()` shall affect the value returned by `locale()`.
473
- See  [[c.locales]] for data race considerations when `setlocale` is
474
- invoked.
 
475
 
476
  *Returns:* The previous value of `locale()`.
477
 
478
  ``` cpp
479
  static const locale& classic();
 
5
  class locale {
6
  public:
7
  // types:
8
  class facet;
9
  class id;
10
+ using category = int;
11
  static const category // values assigned here are for exposition only
12
  none = 0,
13
  collate = 0x010, ctype = 0x020,
14
  monetary = 0x040, numeric = 0x080,
15
  time = 0x100, messages = 0x200,
 
51
  locale’s set of facets.
52
 
53
  Access to the facets of a `locale` is via two function templates,
54
  `use_facet<>` and `has_facet<>`.
55
 
56
+ [*Example 1*:
57
+
58
  An iostream `operator<<` might be implemented as:[^2]
59
 
60
  ``` cpp
61
  template <class charT, class traits>
62
  basic_ostream<charT, traits>&
 
71
  }
72
  return s;
73
  }
74
  ```
75
 
76
+ — *end example*]
77
+
78
  In the call to `use_facet<Facet>(loc)`, the type argument chooses a
79
  facet, making available all members of the named type. If `Facet` is not
80
  present in a locale, it throws the standard exception `bad_cast`. A
81
  C++program can check if a locale implements a particular facet with the
82
  function template `has_facet<Facet>()`. User-defined facets may be
83
  installed in a locale, and used identically as may standard facets (
84
  [[facets.examples]]).
85
 
86
+ [*Note 1*:
87
+
88
  All locale semantics are accessed via `use_facet<>` and `has_facet<>`,
89
  except that:
90
 
91
  - A member operator template
92
  `operator()(const basic_string<C, T, A>&, const basic_string<{}C, T, A>&)`
 
95
  - Convenient global interfaces are provided for traditional `ctype`
96
  functions such as `isdigit()` and `isspace()`, so that given a locale
97
  object `loc` a C++program can call `isspace(c, loc)`. (This eases
98
  upgrading existing extractors ([[istream.formatted]]).)
99
 
100
+ — *end note*]
101
+
102
  Once a facet reference is obtained from a locale object by calling
103
  `use_facet<>`, that reference remains usable, and the results from
104
  member functions of it may be cached and re-used, as long as some locale
105
  object refers to that facet.
106
 
 
123
  #### `locale` types <a id="locale.types">[[locale.types]]</a>
124
 
125
  ##### Type `locale::category` <a id="locale.category">[[locale.category]]</a>
126
 
127
  ``` cpp
128
+ using category = int;
129
  ```
130
 
131
  *Valid* `category` values include the `locale` member bitmask elements
132
  `collate`, `ctype`, `monetary`, `numeric`, `time`, and `messages`, each
133
  of which represents a single locale category. In addition, `locale`
 
153
  [[tab:localization.category.facets]].
154
 
155
  **Table: Locale category facets** <a id="tab:localization.category.facets">[tab:localization.category.facets]</a>
156
 
157
  | Category | Includes facets |
158
+ | -------- | ----------------------------------------------------- |
159
  | collate | `collate<char>`, `collate<wchar_t>` |
160
  | ctype | `ctype<char>`, `ctype<wchar_t>` |
161
  | | `codecvt<char, char, mbstate_t>` |
162
  | | `codecvt<char16_t, char, mbstate_t>` |
163
  | | `codecvt<char32_t, char, mbstate_t>` |
 
174
  | messages | `messages<char>`, `messages<wchar_t>` |
175
 
176
 
177
  For any locale `loc` either constructed, or returned by
178
  `locale::classic()`, and any facet `Facet` shown in Table 
179
+ [[tab:localization.category.facets]], `has_facet<Facet>(loc)` is `true`.
180
  Each `locale` member function which takes a `locale::category` argument
181
  operates on the corresponding set of facets.
182
 
183
  An implementation is required to provide those specializations for facet
184
  templates identified as members of a category, and for those shown in
185
  Table  [[tab:localization.required.specializations]].
186
 
187
  **Table: Required specializations** <a id="tab:localization.required.specializations">[tab:localization.required.specializations]</a>
188
 
189
  | Category | Includes facets |
190
+ | -------- | --------------------------------------------------------- |
191
  | collate | `collate_byname<char>`, `collate_byname<wchar_t>` |
192
  | ctype | `ctype_byname<char>`, `ctype_byname<wchar_t>` |
193
  | | `codecvt_byname<char, char, mbstate_t>` |
194
  | | `codecvt_byname<char16_t, char, mbstate_t>` |
195
  | | `codecvt_byname<char32_t, char, mbstate_t>` |
 
221
  `InputIterator` or `OutputIterator` indicates the set of all possible
222
  specializations on parameters that satisfy the requirements of an Input
223
  Iterator or an Output Iterator, respectively (
224
  [[iterator.requirements]]). A template parameter with name `C`
225
  represents the set of types containing `char`, `wchar_t`, and any other
226
+ *implementation-defined* character types that satisfy the requirements
227
+ for a character on which any of the iostream components can be
228
+ instantiated. A template parameter with name `International` represents
229
+ the set of all possible specializations on a bool parameter.
230
 
231
  ##### Class `locale::facet` <a id="locale.facet">[[locale.facet]]</a>
232
 
233
  ``` cpp
234
  namespace std {
 
240
  void operator=(const facet&) = delete;
241
  };
242
  }
243
  ```
244
 
245
+ Class `facet` is the base class for locale feature sets. A class is a
246
+ *facet* if it is publicly derived from another facet, or if it is a
247
+ class derived from `locale::facet` and contains a publicly accessible
248
+ declaration as follows: [^3]
249
+
250
+ ``` cpp
251
+ static ::std::locale::id id;
252
+ ```
253
+
254
  Template parameters in this Clause which are required to be facets are
255
  those named `Facet` in declarations. A program that passes a type that
256
  is *not* a facet, or a type that refers to a volatile-qualified facet,
257
  as an (explicit or deduced) template parameter to a locale function
258
  expecting a facet, is ill-formed. A const-qualified facet is a valid
259
  template argument to any locale function that expects a Facet template
260
  parameter.
261
 
262
  The `refs` argument to the constructor is used for lifetime management.
263
+ For `refs == 0`, the implementation performs
 
264
  `delete static_cast<locale::facet*>(f)` (where `f` is a pointer to the
265
+ facet) when the last `locale` object containing the facet is destroyed;
266
+ for `refs == 1`, the implementation never destroys the facet.
 
267
 
268
  Constructors of all facets defined in this Clause take such an argument
269
  and pass it along to their `facet` base class constructor. All
270
  one-argument constructors defined in this Clause are *explicit*,
271
  preventing their participation in automatic conversions.
 
293
  id(const id&) = delete;
294
  };
295
  }
296
  ```
297
 
298
+ The class `locale::id` provides identification of a locale facet
299
  interface, used as an index for lookup and to encapsulate
300
  initialization.
301
 
302
+ [*Note 1*: Because facets are used by iostreams, potentially while
303
+ static constructors are running, their initialization cannot depend on
304
  programmed static initialization. One initialization strategy is for
305
  `locale` to initialize each facet’s `id` member the first time an
306
  instance of the facet is installed into a locale. This depends only on
307
  static storage being zero before constructors run (
308
+ [[basic.start.static]]). — *end note*]
309
 
310
  #### `locale` constructors and destructor <a id="locale.cons">[[locale.cons]]</a>
311
 
312
  ``` cpp
313
  locale() noexcept;
 
316
  Default constructor: a snapshot of the current global locale.
317
 
318
  *Effects:* Constructs a copy of the argument last passed to
319
  `locale::global(locale&)`, if it has been called; else, the resulting
320
  facets have virtual function semantics identical to those of
321
+ `locale::classic()`.
322
+
323
+ [*Note 1*: This constructor is commonly used as the default value for
324
+ arguments of functions that take a `const locale&`
325
+ argument. — *end note*]
326
 
327
  ``` cpp
328
  locale(const locale& other) noexcept;
329
  ```
330
 
 
393
  const locale& operator=(const locale& other) noexcept;
394
  ```
395
 
396
  *Effects:* Creates a copy of `other`, replacing the current value.
397
 
398
+ *Returns:* `*this`.
399
 
400
  ``` cpp
401
  ~locale();
402
  ```
403
 
 
412
  *Effects:* Constructs a locale incorporating all facets from `*this`
413
  except for that one facet of `other` that is identified by `Facet`.
414
 
415
  *Returns:* The newly created locale.
416
 
417
+ *Throws:* `runtime_error` if `has_facet<Facet>(other)` is `false`.
418
 
419
  *Remarks:* The resulting locale has no name.
420
 
421
  ``` cpp
422
  basic_string<char> name() const;
423
  ```
424
 
425
  *Returns:* The name of `*this`, if it has one; otherwise, the string
426
+ `"*"`.
 
 
 
427
 
428
  #### `locale` operators <a id="locale.operators">[[locale.operators]]</a>
429
 
430
  ``` cpp
431
  bool operator==(const locale& other) const;
 
437
 
438
  ``` cpp
439
  bool operator!=(const locale& other) const;
440
  ```
441
 
442
+ *Returns:* `!(*this == other)`.
443
 
444
  ``` cpp
445
  template <class charT, class traits, class Allocator>
446
  bool operator()(const basic_string<charT, traits, Allocator>& s1,
447
  const basic_string<charT, traits, Allocator>& s2) const;
 
451
 
452
  *Remarks:* This member operator template (and therefore `locale` itself)
453
  satisfies requirements for a comparator predicate template argument
454
  (Clause  [[algorithms]]) applied to strings.
455
 
456
+ *Returns:*
457
 
458
  ``` cpp
459
+ use_facet<collate<charT>>(*this).compare(s1.data(), s1.data() + s1.size(),
460
+ s2.data(), s2.data() + s2.size()) < 0
461
  ```
462
 
463
+ [*Example 1*:
464
+
465
  A vector of strings `v` can be collated according to collation rules in
466
  locale `loc` simply by ([[alg.sort]], [[vector]]):
467
 
468
  ``` cpp
469
  std::sort(v.begin(), v.end(), loc);
470
  ```
471
 
472
+ — *end example*]
473
+
474
  #### `locale` static members <a id="locale.statics">[[locale.statics]]</a>
475
 
476
  ``` cpp
477
  static locale global(const locale& loc);
478
  ```
 
481
 
482
  *Effects:* Causes future calls to the constructor `locale()` to return a
483
  copy of the argument. If the argument has a name, does
484
 
485
  ``` cpp
486
+ setlocale(LC_ALL, loc.name().c_str());
487
  ```
488
 
489
  otherwise, the effect on the C locale, if any, is
490
  *implementation-defined*. No library function other than
491
  `locale::global()` shall affect the value returned by `locale()`.
492
+
493
+ [*Note 1*: See  [[c.locales]] for data race considerations when
494
+ `setlocale` is invoked. — *end note*]
495
 
496
  *Returns:* The previous value of `locale()`.
497
 
498
  ``` cpp
499
  static const locale& classic();