22 Localization library [localization]

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: Say, for example, you have a code conversion facet called codecvt_utf8 that you want to use 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:

wstring_convert<codecvt_utf8<wchar_t>> myconv;
std::string mbstring = myconv.to_bytes(L"Hello\n");
std::cout << mbstring;

 — end example ]

Class template wstring_convert synopsis

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;

    wstring_convert(Codecvt *pcvt = new Codecvt);
    wstring_convert(Codecvt *pcvt, state_type state);
    wstring_convert(const byte_string& byte_err,
                    const wide_string& wide_err = wide_string());
    ~wstring_convert();

    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;
    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<Elem, char, std::mbstate_t>, which meets the requirements of the standard code-conversion facet std::codecvt<Elem, char, std::mbstate_t>.

An object of this class template stores:

• (4.1)

  byte_err_string — a byte string to display on errors

• (4.2)

  wide_err_string — a wide string to display on errors

• (4.3)

  cvtptr — a pointer to the allocated conversion object (which is freed when the wstring_convert object is destroyed)

• (4.4)

  cvtstate — a conversion state object

• (4.5)

  cvtcount — a conversion count

typedef std::basic_string<char> byte_string;