[depr.conversions.string] - C++14 → C++17

Files changed (1) hide show

tmp/tmpu2vde9_b/{from.md → to.md} +204 -0

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

	@@ -0,0 +1,204 @@

+### Class template `wstring_convert` <a id="depr.conversions.string">[[depr.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.
+[*Example 1*:
+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;
+```
+— *end example*]
+``` cpp
+namespace std {
+  template <class Codecvt, class Elem = wchar_t,
+            class Wide_alloc = allocator<Elem>,
+            class Byte_alloc = allocator<char>>
+    class wstring_convert {
+    public:
+      using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
+      using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
+      using state_type  = typename Codecvt::state_type;
+      using int_type    = typename wide_string::traits_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 `basic_string<Elem, char_traits<Elem>,
+Wide_alloc>` and byte string objects of class `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 `codecvt<Elem,
+char, 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
+using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
+```
+The type shall be a synonym for
+`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 `range_error`.
+``` cpp
+using int_type = typename wide_string::traits_type::int_type;
+```
+The type shall be a synonym for `wide_string::traits_type::int_type`.
+``` cpp
+state_type state() const;
+```
+returns `cvtstate`.
+``` cpp
+using state_type = typename Codecvt::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 `range_error`.
+``` cpp
+using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
+```
+The type shall be a synonym for
+`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`.

Diff to HTML by rtfpessoa