22 Localization library [localization]

Valid category values include the locale member bitmask elements collate, ctype, monetary, numeric, time, and messages, each of which represents a single locale category. In addition, locale member bitmask constant none is defined as zero and represents no category. And locale member bitmask constant all is defined such that the expression

(collate | ctype | monetary | numeric | time | messages | all) == all

is true, and represents the union of all categories. Further, the expression (X | Y), where X and Y each represent a single category, represents the union of the two categories.

locale member functions expecting a category argument require one of the category values defined above, or the union of two or more such values. Such a category value identifies a set of locale categories. Each locale category, in turn, identifies a set of locale facets, including at least those shown in Table [tab:localization.category.facets].

For any locale loc either constructed, or returned by locale::classic(), and any facet Facet shown in Table [tab:localization.category.facets], has_facet<Facet>(loc) is true. Each locale member function which takes a locale::category argument operates on the corresponding set of facets.

An implementation is required to provide those specializations for facet templates identified as members of a category, and for those shown in Table [tab:localization.required.specializations].

The provided implementation of members of facets num_get<charT> and num_put<charT> calls use_facet <F> (l) only for facet F of types numpunct<charT> and ctype<charT>, and for locale l the value obtained by calling member getloc() on the ios_base& argument to these functions.

In declarations of facets, a template parameter with name InputIterator or OutputIterator indicates the set of all possible specializations on parameters that satisfy the requirements of an Input Iterator or an Output Iterator, respectively ([iterator.requirements]). A template parameter with name C represents the set of types containing char, wchar_t, and any other implementation-defined character types that satisfy the requirements for a character on which any of the iostream components can be instantiated. A template parameter with name International represents the set of all possible specializations on a bool parameter.

Template parameters in this Clause which are required to be facets are those named Facet in declarations. A program that passes a type that is not a facet, or a type that refers to a volatile-qualified facet, as an (explicit or deduced) template parameter to a locale function expecting a facet, is ill-formed. A const-qualified facet is a valid template argument to any locale function that expects a Facet template parameter.

The refs argument to the constructor is used for lifetime management.

• (2.1)

  For refs == 0, the implementation performs delete static_cast<locale::facet*>(f) (where f is a pointer to the facet) when the last locale object containing the facet is destroyed; for refs == 1, the implementation never destroys the facet.

Constructors of all facets defined in this Clause take such an argument and pass it along to their facet base class constructor. All one-argument constructors defined in this Clause are explicit, preventing their participation in automatic conversions.

For some standard facets a standard “…_byname” class, derived from it, implements the virtual function semantics equivalent to that facet of the locale constructed by locale(const char*) with the same name. Each such facet provides a constructor that takes a const char* argument, which names the locale, and a refs argument, which is passed to the base class constructor. Each such facet also provides a constructor that takes a string argument str and a refs argument, which has the same effect as calling the first constructor with the two arguments str.c_str() and refs. If there is no “…_byname” version of a facet, the base class implements named locale semantics itself by reference to other facets.

The class locale::id provides identification of a locale facet interface, used as an index for lookup and to encapsulate initialization.

[ Note: Because facets are used by iostreams, potentially while static constructors are running, their initialization cannot depend on programmed static initialization. One initialization strategy is for locale to initialize each facet's id member the first time an instance of the facet is installed into a locale. This depends only on static storage being zero before constructors run ([basic.start.init]).  — end note ]

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: 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:

wstring_convert<std::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;

    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 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, 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, char_traits<char>, Byte_alloc> byte_string;

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.

Class template wbuffer_convert synopsis

namespace std {
template<class Codecvt,
    class Elem = wchar_t,
    class Tr = std::char_traits<Elem> >
  class wbuffer_convert
    : public std::basic_streambuf<Elem, Tr> {
  public:
    typedef typename Codecvt::state_type state_type;

    explicit wbuffer_convert(std::streambuf* bytebuf = 0,
                             Codecvt* pcvt = new Codecvt,
                             state_type state = state_type());

    ~wbuffer_convert();

    wbuffer_convert(const wbuffer_convert&) = delete;
    wbuffer_convert& operator=(const wbuffer_convert&) = delete;

    std::streambuf* rdbuf() const;
    std::streambuf* rdbuf(std::streambuf* bytebuf);

    state_type state() const;

  private:
    std::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 std::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 std::codecvt<Elem, char, std::mbstate_t>.

An object of this class template stores:

• (4.1)

  bufptr — a pointer to its underlying byte stream buffer

• (4.2)

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

• (4.3)

  cvtstate — a conversion state object

state_type state() const;