From Jason Turner

[depr.conversions.string]

C++23 → Trunk 7.2 KB 182 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpuyrzx_wl/{from.md → to.md} +0 -179
tmp/tmpuyrzx_wl/{from.md → to.md} RENAMED
@@ -1,179 +0,0 @@
1
- ### Class template `wstring_convert` <a id="depr.conversions.string">[[depr.conversions.string]]</a>
2
-
3
- Class template `wstring_convert` performs conversions between a wide
4
- string and a byte string. It lets you specify a code conversion facet
5
- (like class template `codecvt`) to perform the conversions, without
6
- affecting any streams or locales.
7
-
8
- [*Example 1*:
9
-
10
- If you want to use the code conversion facet `codecvt_utf8` to output to
11
- `cout` a UTF-8 multibyte sequence corresponding to a wide string, but
12
- you don’t want to alter the locale for `cout`, you can write something
13
- like:
14
-
15
- ``` cpp
16
- wstring_convert<std::codecvt_utf8<wchar_t>> myconv;
17
- std::string mbstring = myconv.to_bytes(L"Hello\n");
18
- std::cout << mbstring;
19
- ```
20
-
21
- — *end example*]
22
-
23
- ``` cpp
24
- namespace std {
25
- template<class Codecvt, class Elem = wchar_t,
26
- class WideAlloc = allocator<Elem>,
27
- class ByteAlloc = allocator<char>>
28
- class wstring_convert {
29
- public:
30
- using byte_string = basic_string<char, char_traits<char>, ByteAlloc>;
31
- using wide_string = basic_string<Elem, char_traits<Elem>, WideAlloc>;
32
- using state_type = typename Codecvt::state_type;
33
- using int_type = typename wide_string::traits_type::int_type;
34
-
35
- wstring_convert() : wstring_convert(new Codecvt) {}
36
- explicit wstring_convert(Codecvt* pcvt);
37
- wstring_convert(Codecvt* pcvt, state_type state);
38
- explicit wstring_convert(const byte_string& byte_err,
39
- const wide_string& wide_err = wide_string());
40
- ~wstring_convert();
41
-
42
- wstring_convert(const wstring_convert&) = delete;
43
- wstring_convert& operator=(const wstring_convert&) = delete;
44
-
45
- wide_string from_bytes(char byte);
46
- wide_string from_bytes(const char* ptr);
47
- wide_string from_bytes(const byte_string& str);
48
- wide_string from_bytes(const char* first, const char* last);
49
-
50
- byte_string to_bytes(Elem wchar);
51
- byte_string to_bytes(const Elem* wptr);
52
- byte_string to_bytes(const wide_string& wstr);
53
- byte_string to_bytes(const Elem* first, const Elem* last);
54
-
55
- size_t converted() const noexcept;
56
- state_type state() const;
57
-
58
- private:
59
- byte_string byte_err_string; // exposition only
60
- wide_string wide_err_string; // exposition only
61
- Codecvt* cvtptr; // exposition only
62
- state_type cvtstate; // exposition only
63
- size_t cvtcount; // exposition only
64
- };
65
- }
66
- ```
67
-
68
- The class template describes an object that controls conversions between
69
- wide string objects of class `basic_string<Elem, char_traits<Elem>,
70
- WideAlloc>` and byte string objects of class `basic_string<char,
71
- char_traits<char>, ByteAlloc>`. The class template defines the types
72
- `wide_string` and `byte_string` as synonyms for these two types.
73
- Conversion between a sequence of `Elem` values (stored in a
74
- `wide_string` object) and multibyte sequences (stored in a `byte_string`
75
- object) is performed by an object of class `Codecvt`, which meets the
76
- requirements of the standard code-conversion facet `codecvt<Elem,
77
- char, mbstate_t>`.
78
-
79
- An object of this class template stores:
80
-
81
- - `byte_err_string` — a byte string to display on errors
82
- - `wide_err_string` — a wide string to display on errors
83
- - `cvtptr` — a pointer to the allocated conversion object (which is
84
- freed when the `wstring_convert` object is destroyed)
85
- - `cvtstate` — a conversion state object
86
- - `cvtcount` — a conversion count
87
-
88
- ``` cpp
89
- size_t converted() const noexcept;
90
- ```
91
-
92
- *Returns:* `cvtcount`.
93
-
94
- ``` cpp
95
- wide_string from_bytes(char byte);
96
- wide_string from_bytes(const char* ptr);
97
- wide_string from_bytes(const byte_string& str);
98
- wide_string from_bytes(const char* first, const char* last);
99
- ```
100
-
101
- *Effects:* The first member function shall convert the single-element
102
- sequence `byte` to a wide string. The second member function shall
103
- convert the null-terminated sequence beginning at `ptr` to a wide
104
- string. The third member function shall convert the sequence stored in
105
- `str` to a wide string. The fourth member function shall convert the
106
- sequence defined by the range \[`first`, `last`) to a wide string.
107
-
108
- In all cases:
109
-
110
- - If the `cvtstate` object was not constructed with an explicit value,
111
- it shall be set to its default value (the initial conversion state)
112
- before the conversion begins. Otherwise it shall be left unchanged.
113
- - The number of input elements successfully converted shall be stored in
114
- `cvtcount`.
115
-
116
- *Returns:* If no conversion error occurs, the member function shall
117
- return the converted wide string. Otherwise, if the object was
118
- constructed with a wide-error string, the member function shall return
119
- the wide-error string. Otherwise, the member function throws an object
120
- of class `range_error`.
121
-
122
- ``` cpp
123
- state_type state() const;
124
- ```
125
-
126
- *Returns:* `cvtstate`.
127
-
128
- ``` cpp
129
- byte_string to_bytes(Elem wchar);
130
- byte_string to_bytes(const Elem* wptr);
131
- byte_string to_bytes(const wide_string& wstr);
132
- byte_string to_bytes(const Elem* first, const Elem* last);
133
- ```
134
-
135
- *Effects:* The first member function shall convert the single-element
136
- sequence `wchar` to a byte string. The second member function shall
137
- convert the null-terminated sequence beginning at `wptr` to a byte
138
- string. The third member function shall convert the sequence stored in
139
- `wstr` to a byte string. The fourth member function shall convert the
140
- sequence defined by the range \[`first`, `last`) to a byte string.
141
-
142
- In all cases:
143
-
144
- - If the `cvtstate` object was not constructed with an explicit value,
145
- it shall be set to its default value (the initial conversion state)
146
- before the conversion begins. Otherwise it shall be left unchanged.
147
- - The number of input elements successfully converted shall be stored in
148
- `cvtcount`.
149
-
150
- *Returns:* If no conversion error occurs, the member function shall
151
- return the converted byte string. Otherwise, if the object was
152
- constructed with a byte-error string, the member function shall return
153
- the byte-error string. Otherwise, the member function shall throw an
154
- object of class `range_error`.
155
-
156
- ``` cpp
157
- explicit wstring_convert(Codecvt* pcvt);
158
- wstring_convert(Codecvt* pcvt, state_type state);
159
- explicit wstring_convert(const byte_string& byte_err,
160
- const wide_string& wide_err = wide_string());
161
- ```
162
-
163
- *Requires:* For the first and second constructors, `pcvt != nullptr`.
164
-
165
- *Effects:* The first constructor shall store `pcvt` in `cvtptr` and
166
- default values in `cvtstate`, `byte_err_string`, and `wide_err_string`.
167
- The second constructor shall store `pcvt` in `cvtptr`, `state` in
168
- `cvtstate`, and default values in `byte_err_string` and
169
- `wide_err_string`; moreover the stored state shall be retained between
170
- calls to `from_bytes` and `to_bytes`. The third constructor shall store
171
- `new Codecvt` in `cvtptr`, `state_type()` in `cvtstate`, `byte_err` in
172
- `byte_err_string`, and `wide_err` in `wide_err_string`.
173
-
174
- ``` cpp
175
- ~wstring_convert();
176
- ```
177
-
178
- *Effects:* The destructor shall delete `cvtptr`.
179
-