[depr.conversions] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpn9wruta3/{from.md → to.md} +0 -290

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

@@ -1,290 +0,0 @@
-## Deprecated convenience conversion interfaces <a id="depr.conversions">[[depr.conversions]]</a>
-### General <a id="depr.conversions.general">[[depr.conversions.general]]</a>
-The header `<locale>` has the following additions:
-``` cpp
-namespace std {
-  template<class Codecvt, class Elem = wchar_t,
-           class WideAlloc = allocator<Elem>,
-           class ByteAlloc = allocator<char>>
-    class wstring_convert;
-  template<class Codecvt, class Elem = wchar_t,
-           class Tr = char_traits<Elem>>
-    class wbuffer_convert;
-}
-```
-### 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 WideAlloc = allocator<Elem>,
-           class ByteAlloc = allocator<char>>
-    class wstring_convert {
-    public:
-      using byte_string = basic_string<char, char_traits<char>, ByteAlloc>;
-      using wide_string = basic_string<Elem, char_traits<Elem>, WideAlloc>;
-      using state_type  = typename Codecvt::state_type;
-      using int_type    = typename wide_string::traits_type::int_type;
-      wstring_convert() : wstring_convert(new Codecvt) {}
-      explicit wstring_convert(Codecvt* pcvt);
-      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>,
-WideAlloc>` and byte string objects of class `basic_string<char,
-char_traits<char>, ByteAlloc>`. 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
-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
-state_type state() const;
-```
-*Returns:* `cvtstate`.
-``` 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
-explicit wstring_convert(Codecvt* pcvt);
-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`.
-### Class template `wbuffer_convert` <a id="depr.conversions.buffer">[[depr.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 = char_traits<Elem>>
-    class wbuffer_convert : public basic_streambuf<Elem, Tr> {
-    public:
-      using state_type = typename Codecvt::state_type;
-      wbuffer_convert() : wbuffer_convert(nullptr) {}
-      explicit wbuffer_convert(streambuf* bytebuf,
-                               Codecvt* pcvt = new Codecvt,
-                               state_type state = state_type());
-      ~wbuffer_convert();
-      wbuffer_convert(const wbuffer_convert&) = delete;
-      wbuffer_convert& operator=(const wbuffer_convert&) = delete;
-      streambuf* rdbuf() const;
-      streambuf* rdbuf(streambuf* bytebuf);
-      state_type state() const;
-    private:
-      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
-`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
-`codecvt<Elem, char, 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
-streambuf* rdbuf() const;
-```
-*Returns:* `bufptr`.
-``` cpp
-streambuf* rdbuf(streambuf* bytebuf);
-```
-*Effects:* Stores `bytebuf` in `bufptr`.
-*Returns:* The previous value of `bufptr`.
-``` cpp
-explicit wbuffer_convert(
-    streambuf* bytebuf,
-    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`.

Diff to HTML by rtfpessoa