locales.tex

\rSec0[localization]{Localization library}

\rSec1[localization.general]{General}

\pnum
This Clause describes components that \Cpp programs may use to
encapsulate (and therefore be more portable when confronting)
cultural differences.
The locale facility includes internationalization
support for character classification and string collation, numeric,
monetary, and date/time formatting and parsing, and message retrieval.

\pnum
The following subclauses describe components for
locales themselves, the standard facets, and facilities
from the ISO C library, as summarized in Table~\ref{tab:localization.lib.summary}.

\begin{libsumtab}{Localization library summary}{tab:localization.lib.summary}
\ref{locales} & Locales                   &   \tcode{<locale>}    \\
\ref{locale.categories} & Standard \tcode{locale} Categories &   \\ \rowsep
\ref{locale.stdcvt} & Standard code conversion facets  &   \tcode{<codecvt>} \\ \rowsep
\ref{c.locales} & C library locales       &   \tcode{<clocale>}   \\
\end{libsumtab}

\rSec1[locale.syn]{Header \tcode{<locale>} synopsis}

\indexlibrary{\idxhdr{locale}}%
\begin{codeblock}
namespace std {
  // \ref{locale}, locale:
  class locale;
  template <class Facet> const Facet& use_facet(const locale&);
  template <class Facet> bool         has_facet(const locale&) noexcept;

  // \ref{locale.convenience}, convenience interfaces:
  template <class charT> bool isspace (charT c, const locale& loc);
  template <class charT> bool isprint (charT c, const locale& loc);
  template <class charT> bool iscntrl (charT c, const locale& loc);
  template <class charT> bool isupper (charT c, const locale& loc);
  template <class charT> bool islower (charT c, const locale& loc);
  template <class charT> bool isalpha (charT c, const locale& loc);
  template <class charT> bool isdigit (charT c, const locale& loc);
  template <class charT> bool ispunct (charT c, const locale& loc);
  template <class charT> bool isxdigit(charT c, const locale& loc);
  template <class charT> bool isalnum (charT c, const locale& loc);
  template <class charT> bool isgraph (charT c, const locale& loc);
  template <class charT> bool isblank (charT c, const locale& loc);
  template <class charT> charT toupper(charT c, const locale& loc);
  template <class charT> charT tolower(charT c, const locale& loc);
  template <class Codecvt, class Elem = wchar_t,
    class Wide_alloc = std::allocator<Elem>,
    class Byte_alloc = std::allocator<char> > class wstring_convert;
  template <class Codecvt, class Elem = wchar_t,
     class Tr = char_traits<Elem@\shr{}@ class wbuffer_convert;

  // \ref{category.ctype}, ctype:
  class ctype_base;
  template <class charT> class ctype;
  template <>            class ctype<char>;             // specialization
  template <class charT> class ctype_byname;
  class codecvt_base;
  template <class internT, class externT, class stateT> class codecvt;
  template <class internT, class externT, class stateT> class codecvt_byname;

  // \ref{category.numeric}, numeric:
  template <class charT, class InputIterator = istreambuf_iterator<charT> >  class num_get;
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> > class num_put;
  template <class charT> class numpunct;
  template <class charT> class numpunct_byname;

  // \ref{category.collate}, collation:
  template <class charT> class collate;
  template <class charT> class collate_byname;

  // \ref{category.time}, date and time:
  class time_base;
  template <class charT, class InputIterator = istreambuf_iterator<charT> >
    class time_get;
  template <class charT, class InputIterator = istreambuf_iterator<charT> >
    class time_get_byname;
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
    class time_put;
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
    class time_put_byname;

  // \ref{category.monetary}, money:
  class money_base;
  template <class charT, class InputIterator = istreambuf_iterator<charT> >  class money_get;
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> > class money_put;
  template <class charT, bool Intl = false> class moneypunct;
  template <class charT, bool Intl = false> class moneypunct_byname;

  // \ref{category.messages}, message retrieval:
  class messages_base;
  template <class charT> class messages;
  template <class charT> class messages_byname;
}
\end{codeblock}

\pnum
The header
\tcode{<locale>}
defines classes and declares functions that encapsulate and manipulate
the information peculiar to a locale.\footnote{In this subclause, the type name
\tcode{struct tm}
is an incomplete type that is defined in
\indexlibrary{\idxhdr{ctime}}%
\tcode{<ctime>}.}

\rSec1[locales]{Locales}

\rSec2[locale]{Class \tcode{locale}}

\indexlibrary{\idxhdr{locale}}%
\begin{codeblock}
namespace std {
  class locale {
  public:
    // types:
    class facet;
    class id;
    typedef int category;
    static const category   // values assigned here are for exposition only
      none     = 0,
      collate  = 0x010, ctype    = 0x020,
      monetary = 0x040, numeric  = 0x080,
      time     = 0x100, messages = 0x200,
      all = collate | ctype | monetary | numeric | time  | messages;

    // construct/copy/destroy:
    locale() noexcept;
    locale(const locale& other) noexcept;
    explicit locale(const char* std_name);
    explicit locale(const string& std_name);
    locale(const locale& other, const char* std_name, category);
    locale(const locale& other, const string& std_name, category);
    template <class Facet> locale(const locale& other, Facet* f);
    locale(const locale& other, const locale& one, category);
    ~locale();                  // not virtual
    const locale& operator=(const locale& other) noexcept;
    template <class Facet> locale combine(const locale& other) const;

    // locale operations:
    basic_string<char>                  name() const;

    bool operator==(const locale& other) const;
    bool operator!=(const locale& other) const;

    template <class charT, class traits, class Allocator>
      bool operator()(const basic_string<charT,traits,Allocator>& s1,
                      const basic_string<charT,traits,Allocator>& s2) const;

    // global locale objects:
    static       locale  global(const locale&);
    static const locale& classic();
  };
}
\end{codeblock}

\pnum
Class
\tcode{locale}
implements a type-safe polymorphic set of facets, indexed by facet
\textit{type}.
In other words, a facet has a dual role: in one
sense, it's just a class interface; at the same time, it's an index
into a locale's set of facets.

\pnum
Access to the facets of a
\tcode{locale}
is via two function templates,
\tcode{use_facet<>}
and
\tcode{has_facet<>}.

\pnum
\enterexample
An iostream
\tcode{operator\shl}
might be implemented as:\footnote{Note that in the call to
\tcode{put}
the stream is implicitly converted to an
\tcode{ostreambuf_iterator<charT,traits>}.}

\begin{codeblock}
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<< (basic_ostream<charT,traits>& s, Date d) {
  typename basic_ostream<charT,traits>::sentry cerberos(s);
  if (cerberos) {
    ios_base::iostate err = ios_base::iostate::goodbit;
    tm tmbuf; d.extract(tmbuf);
    use_facet< time_put<charT,ostreambuf_iterator<charT,traits> > >(
      s.getloc()).put(s, s, s.fill(), err, &tmbuf, 'x');
    s.setstate(err);            // might throw
  }
  return s;
}
\end{codeblock}
\exitexample

\pnum
In the call to
\tcode{use_facet<Facet>(loc)},
the type argument chooses a facet, making available all members
of the named type.
If
\tcode{Facet}
is not present in a
locale,
it throws the standard exception
\tcode{bad_cast}.
A \Cpp program can check if a locale implements a particular
facet with the
function template
\tcode{has_facet<Facet>()}.
User-defined facets may be installed in a locale, and used identically as
may standard facets~(\ref{facets.examples}).

\pnum
\enternote
All locale semantics are accessed via
\tcode{use_facet<>}
and
\tcode{has_facet<>},
except that:

\begin{itemize}
\item
A member operator template
\tcode{operator()(const basic_string<C, T, A>\&, const basic_string<\brk{}C, T, A>\&)}
is provided so that a locale may be used as a predicate argument to
the standard collections, to collate strings.
\item
Convenient global interfaces are provided for traditional
\tcode{ctype}
functions such as
\tcode{isdigit()}
and
\tcode{isspace()},
so that given a locale
object \tcode{loc} a \Cpp program can call
\tcode{isspace(c,loc)}.
(This eases upgrading existing extractors~(\ref{istream.formatted}).)
\exitnote
\end{itemize}

\pnum
Once a facet reference is obtained from a locale object by calling
\tcode{use_facet<>},
that reference remains usable, and the results from member functions
of it may be cached and re-used, as long as some locale object refers
to that facet.

\pnum
In successive calls to a locale facet member function on a facet object
installed in the same locale, the returned result shall be identical.

\pnum
A
\tcode{locale}
constructed from a name string (such as \tcode{"POSIX"}), or from parts of
two named locales, has a name; all others do not.
Named locales may be compared for equality; an unnamed locale is equal
only to (copies of) itself.
For an unnamed locale,
\tcode{locale::name()}
returns the string
\tcode{"*"}.

\pnum
Whether there is one global locale object for the entire program or one global locale
object per thread is \impldef{whether locale object is global or per-thread}.
Implementations should provide one global locale object per
thread. If there is a single global locale object for the entire program,
implementations are not required to avoid data races on it~(\ref{res.on.data.races}).

\rSec3[locale.types]{\tcode{locale} types}


\rSec4[locale.category]{Type \tcode{locale::category}}

\indexlibrary{\idxcode{locale}!\idxcode{category}}%
\indexlibrary{\idxcode{category}!\idxcode{locale}}%
\begin{itemdecl}
typedef int category;
\end{itemdecl}

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

\begin{codeblock}
(collate | ctype | monetary | numeric | time | messages | all) == all
\end{codeblock}

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

\pnum
\tcode{locale}
member functions expecting a
\tcode{category}
argument require one of the
\tcode{category}
values defined above, or the union of two or more such values.
Such a
\tcode{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~\ref{tab:localization.category.facets}.

\begin{floattable}{Locale category facets}{tab:localization.category.facets}
{ml}
\topline
\lhdr{Category} &   \rhdr{Includes facets}                                      \\ \capsep
collate     &   \tcode{collate<char>}, \tcode{collate<wchar_t>}                 \\ \rowsep
ctype       &   \tcode{ctype<char>}, \tcode{ctype<wchar_t>}                     \\
            &   \tcode{codecvt<char,char,mbstate_t>}                            \\
            &   \tcode{codecvt<char16_t,char,mbstate_t>}        \\
            &   \tcode{codecvt<char32_t,char,mbstate_t>}        \\
            &   \tcode{codecvt<wchar_t,char,mbstate_t>}                         \\ \rowsep
monetary    &   \tcode{moneypunct<char>}, \tcode{moneypunct<wchar_t>}           \\
            &   \tcode{moneypunct<char,true>}, \tcode{moneypunct<wchar_t,true>} \\
            &   \tcode{money_get<char>}, \tcode{money_get<wchar_t>}             \\
            &   \tcode{money_put<char>}, \tcode{money_put<wchar_t>}             \\ \rowsep
numeric     &   \tcode{numpunct<char>}, \tcode{numpunct<wchar_t>}               \\
            &   \tcode{num_get<char>}, \tcode{num_get<wchar_t>}                 \\
            &   \tcode{num_put<char>}, \tcode{num_put<wchar_t>}                 \\ \rowsep
time        &   \tcode{time_get<char>}, \tcode{time_get<wchar_t>}               \\
            &   \tcode{time_put<char>}, \tcode{time_put<wchar_t>}               \\ \rowsep
messages    &   \tcode{messages<char>}, \tcode{messages<wchar_t>}               \\
\end{floattable}

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

\pnum
An implementation is required to provide those specializations for
facet templates identified as members of a category, and for those
shown in Table~\ref{tab:localization.required.specializations}.

\begin{floattable}{Required specializations}{tab:localization.required.specializations}
{ml}
\topline
\lhdr{Category} &   \rhdr{Includes facets}                                          \\ \capsep
collate     &   \tcode{collate_byname<char>}, \tcode{collate_byname<wchar_t>}       \\ \rowsep
ctype       &   \tcode{ctype_byname<char>}, \tcode{ctype_byname<wchar_t>}           \\
            &   \tcode{codecvt_byname<char,char,mbstate_t>}                         \\
            &   \tcode{codecvt_byname<char16_t,char,mbstate_t>}     \\
            &   \tcode{codecvt_byname<char32_t,char,mbstate_t>}     \\
            &   \tcode{codecvt_byname<wchar_t,char,mbstate_t>}                      \\ \rowsep
monetary    &   \tcode{moneypunct_byname<char,International>}                       \\
            &   \tcode{moneypunct_byname<wchar_t,International>}                    \\
            &   \tcode{money_get<C,InputIterator>}                                  \\
            &   \tcode{money_put<C,OutputIterator>}                                 \\ \rowsep
numeric     &   \tcode{numpunct_byname<char>}, \tcode{numpunct_byname<wchar_t>}     \\
            &   \tcode{num_get<C,InputIterator>}, \tcode{num_put<C,OutputIterator>} \\ \rowsep
time        &   \tcode{time_get<char,InputIterator>}                                \\
            &   \tcode{time_get_byname<char,InputIterator>}                         \\
            &   \tcode{time_get<wchar_t,InputIterator>}                             \\
            &   \tcode{time_get_byname<wchar_t,InputIterator>}                      \\
            &   \tcode{time_put<char,OutputIterator>}                               \\
            &   \tcode{time_put_byname<char,OutputIterator>}                        \\
            &   \tcode{time_put<wchar_t,OutputIterator>}                            \\
            &   \tcode{time_put_byname<wchar_t,OutputIterator>}                     \\ \rowsep
messages    &   \tcode{messages_byname<char>}, \tcode{messages_byname<wchar_t>}     \\
\end{floattable}


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

\pnum
In declarations of facets, a template formal parameter with name
\tcode{InputIterator}
or
\tcode{OutputIterator}
indicates the set of
all possible specializations on parameters that satisfy the
requirements of an Input Iterator or an Output Iterator, respectively~(\ref{iterator.requirements}).
A template formal parameter with name
\tcode{C}
represents the set
of types containing \tcode{char}, \tcode{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 formal parameter with name
\tcode{International}
represents the set of all possible specializations on a bool parameter.

\rSec4[locale.facet]{Class \tcode{locale::facet}}

\indexlibrary{\idxcode{locale}!\idxcode{facet}}%
\indexlibrary{\idxcode{facet}!\idxcode{locale}}%
\begin{codeblock}
namespace std {
  class locale::facet {
  protected:
    explicit facet(size_t refs = 0);
    virtual ~facet();
    facet(const facet&) = delete;
    void operator=(const facet&) = delete;
  };
}
\end{codeblock}

\pnum
Template parameters in this Clause which are required to be facets are those named
\tcode{Facet}
in declarations.
A program that passes a type that is
\textit{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.

\pnum
The \tcode{refs}
argument to the constructor is used for lifetime management.

\begin{itemize}
\item
For
\tcode{refs == 0},
the implementation performs
\tcode{delete static_cast<locale::facet*>(f)}
(where
\tcode{f}
is a point\-er to the facet) when the last
\tcode{locale}
object containing the facet is destroyed;
for
\tcode{refs == 1},
the implementation never destroys the facet.
\end{itemize}

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

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

\rSec4[locale.id]{Class \tcode{locale::id}}

\indexlibrary{\idxcode{locale}!\idxcode{id}}%
\indexlibrary{\idxcode{id}!\idxcode{locale}}%
\begin{codeblock}
namespace std {
  class locale::id {
  public:
    id();
    void operator=(const id&) = delete;
    id(const id&) = delete;
  };
}
\end{codeblock}

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

\pnum
\enternote
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
\tcode{locale}
to initialize each facet's
\tcode{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~(\ref{basic.start.init}).
\exitnote

\rSec3[locale.cons]{\tcode{locale} constructors and destructor}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
locale() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Default constructor: a snapshot of the current global locale.

\pnum
\effects
Constructs a copy of the argument last passed to
\tcode{locale::global(locale\&)},
if it has been called; else, the resulting facets have virtual
function semantics identical to those of
\tcode{locale::classic()}.
\enternote
This constructor is commonly used as the default value for arguments
of functions that take a
\tcode{const locale\&}
argument.
\exitnote
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
locale(const locale& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale which is a copy of \tcode{other}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
explicit locale(const char* std_name);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale using standard C locale names, e.g., \tcode{"POSIX"}.
The resulting locale implements semantics defined to be associated
with that name.

\pnum
\throws
\tcode{runtime_error}
if the argument is not valid, or is null.

\pnum
\notes
The set of valid string argument values is \tcode{"C"}, \tcode{""},
and any \impldef{locale names} values.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
explicit locale(const string& std_name);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects The same as \tcode{locale(std_name.c_str())}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
locale(const locale& other, const char* std_name, category);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale as a copy of
\tcode{other}
except for the facets identified by the
\tcode{category}
argument, which instead implement the same semantics as
\tcode{locale(std_name)}.

\pnum
\throws
\tcode{runtime_error}
if the argument is not valid, or is null.

\pnum
\notes
The locale has a name if and only if
\tcode{other}
has a name.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
locale(const locale& other, const string& std_name, category cat);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects The same as \tcode{locale(other, std_name.c_str(), cat)}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
template <class Facet> locale(const locale& other, Facet* f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale incorporating all facets from the first
argument except that of type
\tcode{Facet},
and installs the second argument as the remaining facet.
If \tcode{f}
is null, the resulting object is a copy of \tcode{other}.

\pnum
\notes
The resulting locale has no name.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!constructor}%
\begin{itemdecl}
locale(const locale& other, const locale& one, category cats);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale incorporating all facets from the first argument
except those that implement
\tcode{cats},
which are instead incorporated from the second argument.

\pnum
\notes
The resulting locale has a name if and only if the first two arguments
have names.
\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{locale}}%
\indexlibrary{\idxcode{locale}!\idxcode{operator=}}%
\begin{itemdecl}
const locale& operator=(const locale& other) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Creates a copy of \tcode{other}, replacing the current value.

\pnum
\returns
\tcode{*this}
\end{itemdescr}

\indexlibrary{\idxcode{locale}!destructor}%
\begin{itemdecl}
~locale();
\end{itemdecl}

\begin{itemdescr}
\pnum
A non-virtual destructor that throws no exceptions.
\end{itemdescr}

\rSec3[locale.members]{\tcode{locale} members}

\indexlibrary{\idxcode{locale}!\idxcode{combine}}%
\indexlibrary{\idxcode{combine}!\idxcode{locale}}%
\begin{itemdecl}
template <class Facet> locale combine(const locale& other) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a locale incorporating
all facets from
\tcode{*this}
except for that one facet of
\tcode{other}
that is identified by
\tcode{Facet}.

\pnum
\returns
The newly created locale.

\pnum
\throws
\tcode{runtime_error}
if
\tcode{has_facet<Facet>(other)}
is false.

\pnum
\notes
The resulting locale has no name.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!\idxcode{name}}%
\indexlibrary{\idxcode{name}!\idxcode{locale}}%
\begin{itemdecl}
basic_string<char> name() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The name of
\tcode{*this},
if it has one; otherwise, the string \tcode{"*"}.
If
\tcode{*this}
has a name, then
\tcode{locale(name().\brk{}c\textunderscore{}str())}
is equivalent to
\tcode{*this}.
Details of the contents of the resulting string are otherwise implementation-defined.%
\indextext{implementation-defined}
\end{itemdescr}

\rSec3[locale.operators]{\tcode{locale} operators}

\indexlibrary{\idxcode{locale}!\idxcode{operators==}}%
\indexlibrary{\idxcode{operators==}!\idxcode{locale}}%
\begin{itemdecl}
bool operator==(const locale& other) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if both arguments are the same locale, or one is a copy of the
other, or each has a name and the names are identical;
\tcode{false}
otherwise.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{locale}}%
\begin{itemdecl}
bool operator!=(const locale& other) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The result of the expression:
\tcode{!(*this == other)}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!\idxcode{operator()}}%
\indexlibrary{\idxcode{operator()}!\idxcode{locale}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
  bool operator()(const basic_string<charT,traits,Allocator>& s1,
                  const basic_string<charT,traits,Allocator>& s2) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Compares two strings according to the
\tcode{collate<charT>}
facet.

\pnum
\notes
This member operator template (and therefore
\tcode{locale}
itself) satisfies requirements for a comparator predicate template argument
(Clause~\ref{algorithms}) applied to strings.

\pnum
\returns
The result of the following expression:

\begin{codeblock}
use_facet< collate<charT> >(*this).compare
  (s1.data(), s1.data()+s1.size(), s2.data(), s2.data()+s2.size()) < 0;
\end{codeblock}

\pnum
\enterexample
A vector of strings
\tcode{v}
can be collated according to collation rules in locale
\tcode{loc}
simply by~(\ref{alg.sort}, \ref{vector}):

\begin{codeblock}
std::sort(v.begin(), v.end(), loc);
\end{codeblock}
\exitexample
\end{itemdescr}

\rSec3[locale.statics]{\tcode{locale} static members}

\indexlibrary{\idxcode{locale}!\idxcode{global}}%
\indexlibrary{\idxcode{global}!\idxcode{locale}}%
\begin{itemdecl}
static locale global(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
Sets the global locale to its argument.

\pnum
\effects
Causes future calls to the constructor
\tcode{locale()}
to return a copy of the argument.
If the argument has a name, does

\begin{codeblock}
std::setlocale(LC_ALL, loc.name().c_str());
\end{codeblock}

otherwise, the effect on the C locale, if any, is \impldef{effect on C locale of calling
\tcode{locale::global}}.
No library function other than
\tcode{locale\colcol{}global()}
shall affect the value returned by
\tcode{locale()}.
\enternote See~\ref{c.locales} for data race considerations when
\tcode{setlocale} is invoked. \exitnote

\pnum
\returns
The previous value of
\tcode{locale()}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!\idxcode{classic}}%
\indexlibrary{\idxcode{classic}!\idxcode{locale}}%
\begin{itemdecl}
static const locale& classic();
\end{itemdecl}

\begin{itemdescr}
\pnum
The \tcode{"C"} locale.

\pnum
\returns
A locale that implements the classic \tcode{"C"} locale semantics, equivalent
to the value \tcode{locale("C")}.

\pnum
\notes
This locale, its facets, and their member functions, do not change
with time.
\end{itemdescr}

\rSec2[locale.global.templates]{\tcode{locale} globals}

\indexlibrary{\idxcode{locale}!\idxcode{use_facet}}%
\indexlibrary{\idxcode{use_facet}!\idxcode{locale}}%
\begin{itemdecl}
template <class Facet> const Facet& use_facet(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{Facet}
is a facet class whose definition contains the public static member
\tcode{id}
as defined in~\ref{locale.facet}.

\pnum
\returns
A reference to the corresponding facet of \tcode{loc}, if present.

\pnum
\throws
\tcode{bad_cast}
if
\tcode{has_facet<Facet>(loc)}
is
\tcode{false}.

\pnum
\notes
The reference returned remains valid at least as long as any copy of
\tcode{loc} exists.
\end{itemdescr}

\indexlibrary{\idxcode{locale}!\idxcode{has_facet}}%
\indexlibrary{\idxcode{has_facet}!\idxcode{locale}}%
\begin{itemdecl}
template <class Facet> bool has_facet(const locale& loc) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
True if the facet requested is present in \tcode{loc}; otherwise false.
\end{itemdescr}

\rSec2[locale.convenience]{Convenience interfaces}

\rSec3[classification]{Character classification}

\indexlibrary{\idxcode{isspace}}%
\indexlibrary{\idxcode{isprint}}%
\indexlibrary{\idxcode{iscntrl}}%
\indexlibrary{\idxcode{isupper}}%
\indexlibrary{\idxcode{islower}}%
\indexlibrary{\idxcode{isalpha}}%
\indexlibrary{\idxcode{isdigit}}%
\indexlibrary{\idxcode{ispunct}}%
\indexlibrary{\idxcode{isxdigit}}%
\indexlibrary{\idxcode{isalnum}}%
\indexlibrary{\idxcode{isgraph}}%
\indexlibrary{\idxcode{isblank}}%
\begin{itemdecl}
template <class charT> bool isspace (charT c, const locale& loc);
template <class charT> bool isprint (charT c, const locale& loc);
template <class charT> bool iscntrl (charT c, const locale& loc);
template <class charT> bool isupper (charT c, const locale& loc);
template <class charT> bool islower (charT c, const locale& loc);
template <class charT> bool isalpha (charT c, const locale& loc);
template <class charT> bool isdigit (charT c, const locale& loc);
template <class charT> bool ispunct (charT c, const locale& loc);
template <class charT> bool isxdigit(charT c, const locale& loc);
template <class charT> bool isalnum (charT c, const locale& loc);
template <class charT> bool isgraph (charT c, const locale& loc);
template <class charT> bool isblank (charT c, const locale& loc);
\end{itemdecl}

\pnum
Each of these functions
\tcode{is\textbf{\textit{F}}}
returns the result of the expression:

\begin{codeblock}
use_facet< ctype<charT> >(loc).is(ctype_base::@\textbf{\textit{F}}@, c)
\end{codeblock}

where \textbf{\textit{F}} is the
\tcode{ctype_base::mask}
value corresponding to that function~(\ref{category.ctype}).\footnote{When
used in a loop, it is faster to cache the
\tcode{ctype<>}
facet and use it directly, or use the vector form of
\tcode{ctype<>::is}.}

\rSec3[conversions]{Conversions}

\rSec4[conversions.character]{Character conversions}

\indexlibrary{\idxcode{toupper}}%
\begin{itemdecl}
template <class charT> charT toupper(charT c, const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{use_facet<ctype<charT> >(loc).toupper(c)}.
\end{itemdescr}

\indexlibrary{\idxcode{tolower}}%
\begin{itemdecl}
template <class charT> charT tolower(charT c, const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{use_facet<ctype<charT> >(loc).tolower(c)}.
\end{itemdescr}

\rSec4[conversions.string]{\tcode{string} conversions}

\pnum
Class template \tcode{wstring_convert} performs conversions between a wide
string and a byte string. It lets you specify a code conversion facet
(like class template \tcode{codecvt}) to perform the conversions, without
affecting any streams or locales. \enterexample If you want to use the code
conversion facet \tcode{codecvt_utf8} to output to \tcode{cout} a UTF-8
multibyte sequence corresponding to a wide string, but you don't want to
alter the locale for \tcode{cout}, you can write something like:

\begin{codeblock}
wstring_convert<std::codecvt_utf8<wchar_t>> myconv;
std::string mbstring = myconv.to_bytes(L"Hello\n");
std::cout << mbstring;
\end{codeblock}
\exitexample

\pnum
\synopsis{Class template \tcode{wstring_convert} synopsis}

\indexlibrary{\idxcode{wstring_convert}}%
\begin{codeblock}
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;    // \expos
    wide_string wide_err_string;    // \expos
    Codecvt *cvtptr;                // \expos
    state_type cvtstate;            // \expos
    size_t cvtcount;                // \expos
  };
}
\end{codeblock}

\pnum
The class template describes an object that controls conversions between wide
string objects of class \tcode{std::basic_string<Elem, char_traits<Elem>,
Wide_alloc>} and byte string objects of class \tcode{std::\\basic_string<char,
char_traits<char>, Byte_alloc>}. The class template defines the types
\tcode{wide_string} and \tcode{byte_string} as synonyms for these two types.
Conversion between a sequence of \tcode{Elem} values (stored in a
\tcode{wide_string} object) and multibyte sequences (stored in a
\tcode{byte_string} object) is performed by an object of class
\tcode{Codecvt}, which meets the
requirements of the standard code-conversion facet \tcode{std::codecvt<Elem,
char, std::mbstate_t>}.

\pnum
An object of this class template stores:

\begin{itemize}
\item \tcode{byte_err_string} --- a byte string to display on errors
\item \tcode{wide_err_string} --- a wide string to display on errors
\item \tcode{cvtptr} --- a pointer to the allocated conversion object
(which is freed when the \tcode{wstring_convert} object is destroyed)
\item \tcode{cvtstate} --- a conversion state object
\item \tcode{cvtcount} --- a conversion count
\end{itemize}

\indexlibrary{\idxcode{byte_string}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{byte_string}}%
\begin{itemdecl}
typedef std::basic_string<char, char_traits<char>, Byte_alloc> byte_string;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type shall be a synonym for \tcode{std::basic_string<char,
char_traits<char>, Byte_alloc>}
\end{itemdescr}

\indexlibrary{\idxcode{converted}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{converted}}%
\begin{itemdecl}
size_t converted() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{cvtcount}.
\end{itemdescr}

\indexlibrary{\idxcode{from_bytes}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{from_bytes}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The first member function shall convert the single-element sequence \tcode{byte} to a
wide string. The second member function shall convert the null-terminated
sequence beginning at \tcode{ptr} to a wide string. The third member function
shall convert the sequence stored in \tcode{str} to a wide string. The fourth member
function shall convert the sequence defined by the range \range{first}{last} to a
wide string.

\pnum
In all cases:

\begin{itemize}
\item If the \tcode{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.

\item The number of input elements successfully converted shall be stored in \tcode{cvtcount}.
\end{itemize}

\pnum
\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 \tcode{std::range_error}.
\end{itemdescr}

\indexlibrary{\idxcode{int_type}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{int_type}}%
\begin{itemdecl}
typedef typename wide_string::traits_type::int_type int_type;
\end{itemdecl}

\begin{itemdescr}
The type shall be a synonym for \tcode{wide_string::traits_type::int_type}.
\end{itemdescr}

\indexlibrary{\idxcode{state}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{state}}%
\begin{itemdecl}
state_type state() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
returns \tcode{cvtstate}.
\end{itemdescr}

\indexlibrary{\idxcode{state_type}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{state_type}}%
\begin{itemdecl}
typedef typename Codecvt::state_type state_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type shall be a synonym for \tcode{Codecvt::state_type}.
\end{itemdescr}

\indexlibrary{\idxcode{to_bytes}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{to_bytes}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The first member function shall convert the single-element sequence \tcode{wchar} to a byte string.
The second member function shall convert the null-terminated sequence beginning at \tcode{wptr} to
a byte string. The third member function shall convert the sequence stored in \tcode{wstr} to a
byte string. The fourth member function shall convert the sequence defined by the
range \range{first}{last} to a byte string.

\pnum
In all cases:

\begin{itemize}
\item If the \tcode{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.
\item The number of input elements successfully converted shall be stored
in \tcode{cvtcount}.
\end{itemize}

\pnum
\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 \tcode{std::range_error}.
\end{itemdescr}

\indexlibrary{\idxcode{wide_string}!\idxcode{wstring_convert}}%
\indexlibrary{\idxcode{wstring_convert}!\idxcode{wide_string}}%
\begin{itemdecl}
typedef std::basic_string<Elem, char_traits<Elem>, Wide_alloc> wide_string;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type shall be a synonym for \tcode{std::basic_string<Elem,
char_traits<Elem>, Wide_alloc>}.
\end{itemdescr}

\indexlibrary{\idxcode{wstring_convert}!constructor}%
\begin{itemdecl}
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());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
For the first and second constructors, \tcode{pcvt != nullptr}.

\pnum
\effects
The first constructor shall store \tcode{pcvt} in \tcode{cvtptr} and
default values in \tcode{cvtstate}, \tcode{byte_err_string}, and
\tcode{wide_err_string}.
The second constructor shall store \tcode{pcvt} in \tcode{cvtptr},
\tcode{state} in \tcode{cvtstate}, and default values in
\tcode{byte_err_string} and \tcode{wide_err_string}; moreover the
stored state shall be retained between calls to \tcode{from_bytes} and
\tcode{to_bytes}.
The third constructor shall store \tcode{new Codecvt} in \tcode{cvtptr},
\tcode{state_type()} in \tcode{cvtstate}, \tcode{byte_err}
in \tcode{byte_err_string}, and \tcode{wide_err} in
\tcode{wide_err_string}.
\end{itemdescr}

\indexlibrary{\idxcode{wstring_convert}!destructor}%
\begin{itemdecl}
~wstring_convert();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects The destructor shall delete \tcode{cvtptr}.
\end{itemdescr}

\rSec4[conversions.buffer]{Buffer conversions}

\pnum
Class template \tcode{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 \tcode{wstring_convert}, it
lets you specify a code conversion facet to perform the conversions,
without affecting any streams or locales.

\pnum
\synopsis{Class template \tcode{wbuffer_convert} synopsis}

\indexlibrary{\idxcode{wbuffer_convert}}%
\begin{codeblock}
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;         // \expos
    Codecvt *cvtptr;                // \expos
    state_type cvtstate;            // \expos
  };
}
\end{codeblock}

\pnum
The class template describes a stream buffer that controls the
transmission of elements of type \tcode{Elem}, whose character traits are
described by the class \tcode{Tr}, to and from a byte stream buffer of type
\tcode{std::streambuf}. Conversion between a sequence of \tcode{Elem} values and
multibyte sequences is performed by an object of class
\tcode{Codecvt}, which shall meet the requirements
of the standard code-conversion facet \tcode{std::codecvt<Elem, char, std::mbstate_t>}.

\pnum
An object of this class template stores:

\begin{itemize}
\item \tcode{bufptr} --- a pointer to its underlying byte stream buffer
\item \tcode{cvtptr} --- a pointer to the allocated conversion object
(which is freed when the \tcode{wbuffer_convert} object is destroyed)
\item \tcode{cvtstate} --- a conversion state object
\end{itemize}

\indexlibrary{\idxcode{state}!\idxcode{wbuffer_convert}}%
\indexlibrary{\idxcode{wbuffer_convert}!\idxcode{state}}%
\begin{itemdecl}
state_type state() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{cvtstate}.
\end{itemdescr}

\indexlibrary{\idxcode{rdbuf}!\idxcode{wbuffer_convert}}%
\indexlibrary{\idxcode{wbuffer_convert}!\idxcode{rdbuf}}%
\begin{itemdecl}
std::streambuf *rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{bufptr}.
\end{itemdescr}

\indexlibrary{\idxcode{rdbuf}!\idxcode{wbuffer_convert}}%
\indexlibrary{\idxcode{wbuffer_convert}!\idxcode{rdbuf}}%
\begin{itemdecl}
std::streambuf *rdbuf(std::streambuf *bytebuf);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects stores \tcode{bytebuf} in \tcode{bufptr}.

\pnum
\returns The previous value of \tcode{bufptr}.
\end{itemdescr}

\indexlibrary{\idxcode{state_type}!\idxcode{wbuffer_convert}}%
\indexlibrary{\idxcode{wbuffer_convert}!\idxcode{state_type}}%
\begin{itemdecl}
typedef typename Codecvt::state_type state_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type shall be a synonym for \tcode{Codecvt::state_type}.
\end{itemdescr}

\indexlibrary{\idxcode{wbuffer_convert}!constructor}%
\begin{itemdecl}
explicit wbuffer_convert(std::streambuf *bytebuf = 0,
    Codecvt *pcvt = new Codecvt, state_type state = state_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pcvt != nullptr}.

\pnum
\effects The constructor constructs a stream buffer object, initializes
\tcode{bufptr} to \tcode{bytebuf}, initializes \tcode{cvtptr}
to \tcode{pcvt}, and initializes \tcode{cvtstate} to \tcode{state}.
\end{itemdescr}

\indexlibrary{\idxcode{wbuffer_convert}!destructor}%
\begin{itemdecl}
~wbuffer_convert();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects The destructor shall delete \tcode{cvtptr}.
\end{itemdescr}

\rSec1[locale.categories]{Standard \tcode{locale} categories}

\pnum
Each of the standard categories includes a family of facets.
Some of these implement formatting or parsing of a datum, for use
by standard or users' iostream operators
\tcode{\shl}
and
\tcode{\shr},
as members
\tcode{put()}
and
\tcode{get()},
respectively.
Each such member function takes an
\indexlibrary{\idxcode{flags}!\idxcode{ios_base}}%
\tcode{ios_base\&}
argument whose members
\indexlibrary{\idxcode{flags}!\idxcode{ios_base}}%
\tcode{flags()},
\indexlibrary{\idxcode{precision}!\idxcode{ios_base}}%
\tcode{precision()},
and
\indexlibrary{\idxcode{width}!\idxcode{ios_base}}%
\tcode{width()},
specify the format of the corresponding datum~(\ref{ios.base}).
Those functions which need to use other facets call its member
\tcode{getloc()}
to retrieve the locale imbued there.
Formatting facets use the character argument
\tcode{fill}
to fill out the specified width where necessary.

\pnum
The
\tcode{put()}
members make no provision for error reporting.
(Any failures of the
OutputIterator argument must be extracted from the returned iterator.)
The
\tcode{get()}
members take an
\tcode{ios_base::iostate\&}
argument whose value they ignore, but set to
\tcode{ios_base::failbit}
in case of a parse error.

\pnum
Within this clause it is unspecified whether one virtual function calls another
virtual function.

\rSec2[category.ctype]{The \tcode{ctype} category}

\indexlibrary{\idxcode{ctype_base}}%
\begin{codeblock}
namespace std {
  class ctype_base {
  public:
    typedef @\textbf{\textit{T}}@ mask;

    // numeric values are for exposition only.
    static const mask space = 1 << 0;
    static const mask print = 1 << 1;
    static const mask cntrl = 1 << 2;
    static const mask upper = 1 << 3;
    static const mask lower = 1 << 4;
    static const mask alpha = 1 << 5;
    static const mask digit = 1 << 6;
    static const mask punct = 1 << 7;
    static const mask xdigit = 1 << 8;
    static const mask blank = 1 << 9;
    static const mask alnum = alpha | digit;
    static const mask graph = alnum | punct;
  };
}
\end{codeblock}

\pnum
The type
\tcode{mask}
is a bitmask type~(\ref{bitmask.types}).

\rSec3[locale.ctype]{Class template \tcode{ctype}}

\indexlibrary{\idxcode{ctype}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class ctype : public locale::facet, public ctype_base {
  public:
    typedef charT char_type;

    explicit ctype(size_t refs = 0);

    bool         is(mask m, charT c) const;
    const charT* is(const charT* low, const charT* high, mask* vec) const;
    const charT* scan_is(mask m,
                         const charT* low, const charT* high) const;
    const charT* scan_not(mask m,
                          const charT* low, const charT* high) const;
    charT        toupper(charT c) const;
    const charT* toupper(charT* low, const charT* high) const;
    charT        tolower(charT c) const;
    const charT* tolower(charT* low, const charT* high) const;

    charT        widen(char c) const;
    const char*  widen(const char* low, const char* high, charT* to) const;
    char         narrow(charT c, char dfault) const;
    const charT* narrow(const charT* low, const charT*, char dfault,
                        char* to) const;

    static locale::id id;

  protected:
   ~ctype();
    virtual bool         do_is(mask m, charT c) const;
    virtual const charT* do_is(const charT* low, const charT* high,
                               mask* vec) const;
    virtual const charT* do_scan_is(mask m,
                                    const charT* low, const charT* high) const;
    virtual const charT* do_scan_not(mask m,
                                     const charT* low, const charT* high) const;
    virtual charT        do_toupper(charT) const;
    virtual const charT* do_toupper(charT* low, const charT* high) const;
    virtual charT        do_tolower(charT) const;
    virtual const charT* do_tolower(charT* low, const charT* high) const;
    virtual charT        do_widen(char) const;
    virtual const char*  do_widen(const char* low, const char* high,
                                  charT* dest) const;
    virtual char         do_narrow(charT, char dfault) const;
    virtual const charT* do_narrow(const charT* low, const charT* high,
                                   char dfault, char* dest) const;
  };
}
\end{codeblock}

\pnum
Class
\tcode{ctype}
encapsulates the C library
\tcode{<cctype>}
features.
\tcode{istream}
members are required to use
\tcode{ctype<>}
for character classing during input parsing.

\pnum
The specializations required in Table~\ref{tab:localization.category.facets}~(\ref{locale.category}), namely
\tcode{ctype<char>}
and
\tcode{ctype<wchar_t>},
implement character classing appropriate
to the implementation's native character set.

\rSec4[locale.ctype.members]{\tcode{ctype} members}

\indexlibrary{\idxcode{ctype}!\idxcode{is}}%
\indexlibrary{\idxcode{is}!\idxcode{ctype}}%
\begin{itemdecl}
bool         is(mask m, charT c) const;
const charT* is(const charT* low, const charT* high,
                mask* vec) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_is(m,c)}
or
\tcode{do_is(low,high,vec)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{scan_is}}%
\indexlibrary{\idxcode{scan_is}!\idxcode{ctype}}%
\begin{itemdecl}
const charT* scan_is(mask m,
                     const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_scan_is(m,low,high)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{scan_not}}%
\indexlibrary{\idxcode{scan_not}!\idxcode{ctype}}%
\begin{itemdecl}
const charT* scan_not(mask m,
                      const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_scan_not(m,low,high)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{toupper}}%
\indexlibrary{\idxcode{toupper}!\idxcode{ctype}}%
\begin{itemdecl}
charT        toupper(charT) const;
const charT* toupper(charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_toupper(c)}
or
\tcode{do_toupper(low,high)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{tolower}}%
\indexlibrary{\idxcode{tolower}!\idxcode{ctype}}%
\begin{itemdecl}
charT        tolower(charT c) const;
const charT* tolower(charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_tolower(c)}
or
\tcode{do_tolower(low,high)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{widen}}%
\indexlibrary{\idxcode{widen}!\idxcode{ctype}}%
\begin{itemdecl}
charT       widen(char c) const;
const char* widen(const char* low, const char* high, charT* to) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_widen(c)}
or
\tcode{do_widen(low,high,to)}
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{narrow}}%
\indexlibrary{\idxcode{narrow}!\idxcode{ctype}}%
\begin{itemdecl}
char         narrow(charT c, char dfault) const;
const charT* narrow(const charT* low, const charT*, char dfault,
                    char* to) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_narrow(c,dfault)}
or
\tcode{do_narrow(low,high,dfault,to)}
\end{itemdescr}

\rSec4[locale.ctype.virtuals]{\tcode{ctype} virtual functions}

\indexlibrary{\idxcode{ctype}!\idxcode{do_is}}%
\indexlibrary{\idxcode{do_is}!\idxcode{ctype}}%
\begin{itemdecl}
bool         do_is(mask m, charT c) const;
const charT* do_is(const charT* low, const charT* high,
                   mask* vec) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Classifies a character or sequence of characters.
For each argument character, identifies a value
\tcode{M}
of type
\tcode{ctype_base::mask}.
The second form identifies a value \tcode{M} of type
\tcode{ctype_base::mask}
for each
\tcode{*p}
where
\tcode{(low<=p \&\& p<high)},
and places it into
\tcode{vec[p-low]}.

\pnum
\returns
The first form returns the result of the expression
\tcode{(M \& m) != 0};
i.e.,
\tcode{true}
if the character has the characteristics specified.
The second form returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype_base}!\idxcode{do_scan_is}}%
\indexlibrary{\idxcode{do_scan_is}!\idxcode{ctype_base}}%
\begin{itemdecl}
const charT* do_scan_is(mask m,
                       const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Locates a character in a buffer that conforms to a classification
\tcode{m}.

\pnum
\returns
The smallest pointer \tcode{p} in the range
\tcode{[low, high)}
such that
\tcode{is(m,*p)}
would return
\tcode{true};
otherwise, returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{do_scan_not}}%
\indexlibrary{\idxcode{do_scan_not}!\idxcode{ctype}}%
\begin{itemdecl}
const charT* do_scan_not(mask m,
                        const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Locates a character in a buffer that fails to conform to a classification
\tcode{m}.

\pnum
\returns
The smallest pointer \tcode{p}, if any, in the range
\range{low}{high}
such that
\tcode{is(m,*p)}
would return
\tcode{false};
otherwise, returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{do_toupper}}%
\indexlibrary{\idxcode{do_toupper}!\idxcode{ctype}}%
\begin{itemdecl}
charT        do_toupper(charT c) const;
const charT* do_toupper(charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Converts a character or characters to upper case.
The second form replaces each character
\tcode{*p}
in the range
\range{low}{high}
for which a corresponding upper-case character exists, with
that character.

\pnum
\returns
The first form returns the corresponding upper-case character if it
is known to exist, or its argument if not.
The second form returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{do_tolower}}%
\indexlibrary{\idxcode{do_tolower}!\idxcode{ctype}}%
\begin{itemdecl}
charT        do_tolower(charT c) const;
const charT* do_tolower(charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Converts a character or characters to lower case.
The second form replaces each character
\tcode{*p}
in the range
\range{low}{high}
and for which a corresponding lower-case character exists,
with that character.

\pnum
\returns
The first form returns the corresponding lower-case character if it
is known to exist, or its argument if not.
The second form returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{do_widen}}%
\indexlibrary{\idxcode{do_widen}!\idxcode{ctype}}%
\begin{itemdecl}
charT        do_widen(char c) const;
const char*  do_widen(const char* low, const char* high,
                      charT* dest) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Applies the simplest reasonable transformation from a
\tcode{char}
value or sequence of
\tcode{char}
values to the corresponding
\tcode{charT}
value or values.\footnote{The char argument of
\tcode{do_widen}
is intended to accept values derived from character literals for conversion
to the locale's encoding.}
The only characters for which unique transformations are required
are those in the basic source character set~(\ref{lex.charset}).

For any named
\tcode{ctype}
category with a
\tcode{ctype<charT>}
facet \tcode{ctc} and valid
\tcode{ctype_base::mask}
value \tcode{M},
\tcode{(ctc.\brk{}is(M, c) || !is(M, do_widen(c)) )}
is
\tcode{true}.\footnote{In other words, the transformed character is not a member
of any character classification that \tcode{c} is not also a member of.}

The second form transforms each character
\tcode{*p}
in the range
\range{low}{high},
placing the result in
\tcode{dest[p-low]}.

\pnum
\returns
The first form returns the transformed value.
The second form returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype}!\idxcode{do_narrow}}%
\indexlibrary{\idxcode{do_narrow}!\idxcode{ctype}}%
\begin{itemdecl}
char         do_narrow(charT c, char dfault) const;
const charT* do_narrow(const charT* low, const charT* high,
                       char dfault, char* dest) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Applies the simplest reasonable transformation from a
\tcode{charT}
value or sequence of
\tcode{charT}
values to the corresponding
\tcode{char}
value or values.

For any character \tcode{c} in the basic source character set~(\ref{lex.charset})
the transformation is such that

\begin{codeblock}
do_widen(do_narrow(c,0)) == c
\end{codeblock}

For any named
\tcode{ctype}
category with a
\tcode{ctype<char>}
facet \tcode{ctc} however, and
\tcode{ctype_base::mask}
value \tcode{M},

\begin{codeblock}
(is(M,c) || !ctc.is(M, do_narrow(c,dfault)) )
\end{codeblock}

is
\tcode{true}
(unless
\tcode{do_narrow}
returns
\tcode{dfault}).
In addition, for any digit character \tcode{c},
the expression
\tcode{(do_narrow(c, dfault) - '0')}
evaluates to the digit value of the character.
The second form transforms each character
\tcode{*p}
in the range
\range{low}{high},
placing the result (or \tcode{dfault}
if no simple transformation is readily available) in
\tcode{dest[p-low]}.

\pnum
\returns
The first form returns the transformed value; or \tcode{dfault}
if no mapping is readily available.
The second form returns \tcode{high}.
\end{itemdescr}

\rSec3[locale.ctype.byname]{Class template \tcode{ctype_byname}}

\indexlibrary{\idxcode{ctype_byname}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class ctype_byname : public ctype<charT> {
  public:
    typedef typename ctype<charT>::mask mask;
    explicit ctype_byname(const char*, size_t refs = 0);
    explicit ctype_byname(const string&, size_t refs = 0);
  protected:
   ~ctype_byname();
  };
}
\end{codeblock}

\rSec3[facet.ctype.special]{\tcode{ctype} specializations}

\indexlibrary{\idxcode{ctype<char>}}%
\begin{codeblock}
namespace std {
  template <> class ctype<char>
    : public locale::facet, public ctype_base {
  public:
    typedef char char_type;

    explicit ctype(const mask* tab = 0, bool del = false,
                   size_t refs = 0);

    bool is(mask m, char c) const;
    const char* is(const char* low, const char* high, mask* vec) const;
    const char* scan_is (mask m,
                         const char* low, const char* high) const;
    const char* scan_not(mask m,
                         const char* low, const char* high) const;

    char        toupper(char c) const;
    const char* toupper(char* low, const char* high) const;
    char        tolower(char c) const;
    const char* tolower(char* low, const char* high) const;

    char  widen(char c) const;
    const char* widen(const char* low, const char* high, char* to) const;
    char  narrow(char c, char dfault) const;
    const char* narrow(const char* low, const char* high, char dfault,
                       char* to) const;

    static locale::id id;
    static const size_t table_size = @\impdef@;

    const mask* table() const noexcept;
    static const mask* classic_table() noexcept;

  protected:
   ~ctype();
    virtual char        do_toupper(char c) const;
    virtual const char* do_toupper(char* low, const char* high) const;
    virtual char        do_tolower(char c) const;
    virtual const char* do_tolower(char* low, const char* high) const;

    virtual char        do_widen(char c) const;
    virtual const char* do_widen(const char* low,
                                 const char* high,
                                 char* to) const;
    virtual char        do_narrow(char c, char dfault) const;
    virtual const char* do_narrow(const char* low,
                                  const char* high,
                                  char dfault, char* to) const;
  };
}
\end{codeblock}

\pnum
A specialization
\tcode{ctype<char>}
is provided so that the member functions on type
\tcode{char}
can be implemented
\tcode{inline}.\footnote{Only the
\tcode{char}
(not
\tcode{unsigned char}
and
\tcode{signed char})
form is provided.
The specialization is specified in the standard, and not left as an
implementation detail, because it affects the derivation interface for
\tcode{ctype<char>}.}
The \impldef{value of \tcode{ctype<char>::table_size}} value of member
\tcode{table_size}
is at least 256.

\rSec4[facet.ctype.char.dtor]{\tcode{ctype<char>} destructor}

\indexlibrary{\idxcode{ctype<char>}!destructor}%
\begin{itemdecl}
~ctype();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If the constructor's first argument was nonzero, and its second argument
was true, does
\tcode{delete [] table()}.
\end{itemdescr}

\rSec4[facet.ctype.char.members]{\tcode{ctype<char>} members}

\pnum
\indexlibrary{\idxcode{ctype<char>}!\idxcode{ctype<char>}}%
In the following member descriptions, for
\tcode{unsigned char}
values \tcode{v} where \tcode{v >= table_size},
\tcode{table()[v]} is assumed to have an
implementation-specific value (possibly different for each
such value \tcode{v}) without performing the array lookup.

\indexlibrary{\idxcode{ctype<char>}!constructor}%
\begin{itemdecl}
explicit ctype(const mask* tbl = 0, bool del = false,
               size_t refs = 0);
\end{itemdecl}

\begin{itemdescr}
\pnum
\precondition
\tcode{tbl} either 0 or an array of at least
\tcode{table_size}
elements.

\pnum
\effects
Passes its \tcode{refs} argument to its base class constructor.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{is}}%
\indexlibrary{\idxcode{is}!\idxcode{ctype<char>}}%
\begin{itemdecl}
bool        is(mask m, char c) const;
const char* is(const char* low, const char* high,
               mask* vec) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The second form, for all
\tcode{*p}
in the range
\range{low}{high},
assigns
into
\tcode{vec[p-low]}
the value
\tcode{table()[\,(un\-signed char)*p]}.

\pnum
\returns
The first form returns
\tcode{table()[(unsigned char)c] \& m};
the second form returns \tcode{high}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{scan_is}}%
\indexlibrary{\idxcode{scan_is}!\idxcode{ctype<char>}}%
\begin{itemdecl}
const char* scan_is(mask m,
                    const char* low, const char* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The smallest
\tcode{p}
in the range
\range{low}{high}
such that
\begin{codeblock}
table()[(unsigned char) *p] & m
\end{codeblock}
is
\tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{scan_not}}%
\indexlibrary{\idxcode{scan_not}!\idxcode{ctype<char>}}%
\begin{itemdecl}
const char* scan_not(mask m,
                     const char* low, const char* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The smallest
\tcode{p}
in the range
\range{low}{high}
such that
\begin{codeblock}
table()[(unsigned char) *p] & m
\end{codeblock}
is
\tcode{false}.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{toupper}}%
\indexlibrary{\idxcode{toupper}!\idxcode{ctype<char>}}%
\begin{itemdecl}
char        toupper(char c) const;
const char* toupper(char* low, const char* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_toupper(c)}
or
\tcode{do_toupper(low,high)},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{tolower}}%
\indexlibrary{\idxcode{tolower}!\idxcode{ctype<char>}}%
\begin{itemdecl}
char        tolower(char c) const;
const char* tolower(char* low, const char* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_tolower(c)}
or
\tcode{do_tolower(low,high)},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{widen}}%
\indexlibrary{\idxcode{widen}!\idxcode{ctype<char>}}%
\begin{itemdecl}
char  widen(char c) const;
const char* widen(const char* low, const char* high,
    char* to) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_widen(c)}
or
\indexlibrary{\idxcode{do_widen}}%
\tcode{do_widen(low, high, to)},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{narrow}}%
\indexlibrary{\idxcode{narrow}!\idxcode{ctype<char>}}%
\begin{itemdecl}
char        narrow(char c, char dfault) const;
const char* narrow(const char* low, const char* high,
                   char dfault, char* to) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\indexlibrary{\idxcode{do_narrow}}%
\tcode{do_narrow(c, dfault)}
or
\indexlibrary{\idxcode{do_narrow}}%
\tcode{do_narrow(low, high, dfault, to)},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{table}}%
\indexlibrary{\idxcode{table}!\idxcode{ctype<char>}}%
\begin{itemdecl}
const mask* table() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The first constructor argument, if it was non-zero, otherwise
\tcode{classic_table()}.
\end{itemdescr}

\rSec4[facet.ctype.char.statics]{\tcode{ctype<char>} static members}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{classic_table}}%
\indexlibrary{\idxcode{classic_table}!\idxcode{ctype<char>}}%
\begin{itemdecl}
static const mask* classic_table() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to the initial element of an array of size
\tcode{table_size}
which represents the classifications of characters in the "C" locale.
\end{itemdescr}

\rSec4[facet.ctype.char.virtuals]{\tcode{ctype<char>} virtual functions}

\indexlibrary{\idxcode{ctype<char>}!\idxcode{do_toupper}}%
\indexlibrary{\idxcode{do_toupper}!\idxcode{ctype<char>}}%
\indexlibrary{\idxcode{ctype<char>}!\idxcode{do_tolower}}%
\indexlibrary{\idxcode{do_tolower}!\idxcode{ctype<char>}}%
\indexlibrary{\idxcode{ctype<char>}!\idxcode{do_widen}}%
\indexlibrary{\idxcode{do_widen}!\idxcode{ctype<char>}}%
\indexlibrary{\idxcode{ctype<char>}!\idxcode{do_narrow}}%
\indexlibrary{\idxcode{do_narrow}!\idxcode{ctype<char>}}%
\begin{codeblock}
char        do_toupper(char) const;
const char* do_toupper(char* low, const char* high) const;
char        do_tolower(char) const;
const char* do_tolower(char* low, const char* high) const;

virtual char        do_widen(char c) const;
virtual const char* do_widen(const char* low,
                             const char* high,
                             char* to) const;
virtual char        do_narrow(char c, char dfault) const;
virtual const char* do_narrow(const char* low,
                              const char* high,
                              char dfault, char* to) const;
\end{codeblock}

These functions are described identically as those members of the
same name in the
\tcode{ctype}
class template~(\ref{locale.ctype.members}).

\rSec3[locale.codecvt]{Class template \tcode{codecvt}}

\indexlibrary{\idxcode{codecvt}}%
\begin{codeblock}
namespace std {
  class codecvt_base {
  public:
    enum result { ok, partial, error, noconv };
  };

  template <class internT, class externT, class stateT>
  class codecvt : public locale::facet, public codecvt_base {
  public:
    typedef internT  intern_type;
    typedef externT  extern_type;
    typedef stateT state_type;

    explicit codecvt(size_t refs = 0);

    result out(stateT& state,
               const internT* from, const internT* from_end, const internT*& from_next,
               externT*   to,       externT* to_end, externT*& to_next) const;
    result unshift(stateT& state,
                   externT*   to,        externT* to_end, externT*& to_next) const;
    result in(stateT& state,
              const externT* from, const externT* from_end, const externT*& from_next,
              internT*   to,       internT* to_end, internT*& to_next) const;
    int encoding() const noexcept;
    bool always_noconv() const noexcept;
    int length(stateT&, const externT* from, const externT* end,
               size_t max) const;
    int max_length() const noexcept;

    static locale::id id;

  protected:
    ~codecvt();
    virtual result do_out(stateT& state,
                          const internT* from, const internT* from_end, const internT*& from_next,
                          externT* to,         externT* to_end, externT*& to_next) const;
    virtual result do_in(stateT& state,
                         const externT* from, const externT* from_end, const externT*& from_next,
                         internT* to,         internT* to_end, internT*& to_next) const;
    virtual result do_unshift(stateT& state,
                              externT* to,         externT* to_end, externT*& to_next) const;
    virtual int do_encoding() const noexcept;
    virtual bool do_always_noconv() const noexcept;
    virtual int do_length(stateT&, const externT* from,
                          const externT* end, size_t max) const;
    virtual int do_max_length() const noexcept;
  };
}
\end{codeblock}

\pnum
The class
\tcode{codecvt<internT,externT,stateT>}
is for use when
converting from one character encoding to another, such as from wide characters
to multibyte  characters or between wide character encodings such as
Unicode and EUC.

\pnum
The
\tcode{stateT}
argument selects the pair of character encodings being mapped between.

\pnum
The specializations required in Table~\ref{tab:localization.category.facets}~(\ref{locale.category})
convert the implementation-defined native character set.
\tcode{codecvt<char, char, mbstate_t>}
implements a degenerate conversion;
it does not convert at all.
The specialization \tcode{codecvt<char16_t,} \tcode{char, mbstate_t>}
converts between the UTF-16 and UTF-8 encoding forms, and
the specialization \tcode{codecvt} \tcode{<char32_t, char, mbstate_t>}
converts between the UTF-32 and UTF-8 encoding forms.
\tcode{codecvt<wchar_t,char,mbstate_t>}
converts between the native character sets for narrow and wide characters.
Specializations on
\tcode{mbstate_t}
perform conversion between encodings known to the library implementer.
Other encodings can be converted by specializing on a user-defined
\tcode{stateT}
type.
Objects of type
\tcode{stateT}
can contain any state that is useful to communicate to or from
the specialized
\tcode{do_in}
or
\tcode{do_out}
members.

\rSec4[locale.codecvt.members]{\tcode{codecvt} members}

\indexlibrary{\idxcode{codecvt}!\idxcode{out}}%
\indexlibrary{\idxcode{out}!\idxcode{codecvt}}%
\begin{itemdecl}
result out(stateT& state,
  const internT* from, const internT* from_end, const internT*& from_next,
        externT* to, externT* to_end, externT*& to_next) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_out(state, from, from_end, from_next, to, to_end, to_next)}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{unshift}}%
\indexlibrary{\idxcode{unshift}!\idxcode{codecvt}}%
\begin{itemdecl}
result unshift(stateT& state,
        externT* to, externT* to_end, externT*& to_next) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_unshift(state, to, to_end, to_next)}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{in}}%
\indexlibrary{\idxcode{in}!\idxcode{codecvt}}%
\begin{itemdecl}
result in(stateT& state,
  const externT* from, const externT* from_end, const externT*& from_next,
        internT* to, internT* to_end, internT*& to_next) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_in(state, from, from_end, from_next, to, to_end, to_next)}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{encoding}}%
\indexlibrary{\idxcode{encoding}!\idxcode{codecvt}}%
\begin{itemdecl}
int encoding() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_encoding()}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{always_noconv}}%
\indexlibrary{\idxcode{always_noconv}!\idxcode{codecvt}}%
\begin{itemdecl}
bool always_noconv() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_always_noconv()}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{length}}%
\indexlibrary{\idxcode{length}!\idxcode{codecvt}}%
\begin{itemdecl}
int length(stateT& state, const externT* from, const externT* from_end,
           size_t max) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_length(state, from,from_end,max)}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{max_length}}%
\indexlibrary{\idxcode{max_length}!\idxcode{codecvt}}%
\begin{itemdecl}
int max_length() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_max_length()}
\end{itemdescr}

\rSec4[locale.codecvt.virtuals]{\tcode{codecvt} virtual functions}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_out}}%
\indexlibrary{\idxcode{do_out}!\idxcode{codecvt}}%
\indexlibrary{\idxcode{codecvt}!\idxcode{do_in}}%
\indexlibrary{\idxcode{do_in}!\idxcode{codecvt}}%
\begin{itemdecl}
result do_out(stateT& state,
  const internT* from, const internT* from_end, const internT*& from_next,
  externT* to, externT* to_end, externT*& to_next) const;

result do_in(stateT& state,
  const externT* from, const externT* from_end, const externT*& from_next,
        internT* to, internT* to_end, internT*& to_next) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\preconditions
\tcode{(from<=from_end \&\& to<=to_end)}
well-defined and
\tcode{true};
\tcode{state} initialized, if at the beginning of a sequence, or else equal to
the result of converting the preceding characters in the sequence.

\pnum
\effects
Translates characters in the source range
\tcode{[from,from_end)},
placing the results in sequential positions starting at destination \tcode{to}.
Converts no more than
\tcode{(from_end-from)}
source elements, and
stores no more than
\tcode{(to_end-to)}
destination elements.

Stops if it encounters a character it cannot convert.
It always leaves the \tcode{from_next} and \tcode{to_next} pointers
pointing one beyond the last element successfully converted.
If returns
\tcode{noconv},
\tcode{internT}
and
\tcode{externT}
are the same type and the converted sequence is
identical to the input sequence
\tcode{[from, from_next)}.
\tcode{to_next} is set equal to \tcode{to}, the value of \tcode{state} is
unchanged, and there are no changes to the values in
\tcode{[to, to_end)}.

\pnum
A
\tcode{codecvt}
facet that is used by
\tcode{basic_filebuf}~(\ref{file.streams}) shall have the property that if
\begin{codeblock}
do_out(state, from, from_end, from_next, to, to_end, to_next)
\end{codeblock}
would return
\tcode{ok},
where
\tcode{from != from_end},
then
\begin{codeblock}
do_out(state, from, from + 1, from_next, to, to_end, to_next)
\end{codeblock}
shall also return
\tcode{ok},
and that if
\begin{codeblock}
do_in(state, from, from_end, from_next, to, to_end, to_next)
\end{codeblock}
would return
\tcode{ok},
where
\tcode{to != to_end},
then
\begin{codeblock}
do_in(state, from, from_end, from_next, to, to + 1, to_next)
\end{codeblock}
shall also return
\tcode{ok}.\footnote{Informally, this means that
\tcode{basic_filebuf}
assumes that the mappings from internal to external characters is
1 to N: a
\tcode{codecvt}
facet that is used by
\tcode{basic_filebuf}
must be able to translate characters one internal character at a time.
}
\enternote As a result of operations on \tcode{state}, it can return \tcode{ok} or \tcode{partial} and set \tcode{from_next == from} and \tcode{to_next != to}. \exitnote

\pnum
\notes
Its operations on \tcode{state} are unspecified.
\enternote
This argument can be used, for example, to maintain
shift state, to specify conversion options (such as count only), or to
identify a cache of seek offsets.
\exitnote

\pnum
\returns
An enumeration value, as summarized in Table~\ref{tab:localization.convert.result.values.out.in}.

\begin{floattable}{\tcode{do_in/do_out} result values}{tab:localization.convert.result.values.out.in}
{lp{3in}}
\topline
\lhdr{Value}    &   \rhdr{Meaning}                                  \\ \capsep
\tcode{ok}                  &   completed the conversion            \\
\tcode{partial}             &   not all source characters converted \\
\tcode{error}               &
encountered a character in \tcode{[from,from_end)}
that it could not convert                                           \\
\tcode{noconv}              &
\tcode{internT} and \tcode{externT} are the same type, and input
sequence is identical to converted sequence                         \\
\end{floattable}

A return value of
\tcode{partial},
if
\tcode{(from_next==from_end)},
indicates that either the destination sequence has not absorbed all the
available destination elements, or that additional source elements are
needed before another destination element can be produced.
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_unshift}}%
\indexlibrary{\idxcode{do_unshift}!\idxcode{codecvt}}%
\begin{itemdecl}
result do_unshift(stateT& state,
  externT* to, externT* to_end, externT*& to_next) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{(to <= to_end)}
well defined and true; state initialized, if at the beginning of a sequence,
or else equal to the result of converting the preceding characters in the
sequence.

\pnum
\effects
Places characters starting at \tcode{to} that should be appended
to terminate a sequence when the current
\tcode{stateT}
is given by \tcode{state}.\footnote{Typically these will be characters to return the state to
\tcode{stateT()}}
Stores no more than
\tcode{(to_end-to)}
destination elements, and leaves the \tcode{to_next} pointer
pointing one beyond the last element successfully stored.

\pnum
\returns
An enumeration value, as summarized in Table~\ref{tab:localization.convert.result.values.unshift}.

\begin{floattable}{\tcode{do_unshift} result values}{tab:localization.convert.result.values.unshift}
{lp{.50\hsize}}
\topline
\lhdr{Value}                &   \rhdr{Meaning}                                          \\ \capsep
\tcode{ok}                  &   completed the sequence                                  \\
\tcode{partial}             &
space for more than \tcode{to_end-to} destination elements was needed
to terminate a sequence given the value of \tcode{state}\\
\tcode{error}               &   an unspecified error has occurred \\
\tcode{noconv}              &   no termination is needed for this \tcode{state_type}    \\
\end{floattable}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_encoding}}%
\indexlibrary{\idxcode{do_encoding}!\idxcode{codecvt}}%
\begin{itemdecl}
int do_encoding() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
-1 if the encoding of the \tcode{externT} sequence is state-dependent; else the
constant number of \tcode{externT} characters needed to produce an internal
character; or 0 if this number is not a constant.\footnote{If \tcode{encoding()}
yields -1, then more than \tcode{max_length()} \tcode{externT} elements
may be consumed when producing a single \tcode{internT} character, and additional
\tcode{externT} elements may appear at the end of a sequence after those that
yield the final \tcode{internT} character.}
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_always_noconv}}%
\indexlibrary{\idxcode{do_always_noconv}!\idxcode{codecvt}}%
\begin{itemdecl}
bool do_always_noconv() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if
\tcode{do_in()}
and
\tcode{do_out()}
return
\tcode{noconv}
for all valid argument values.
\tcode{codecvt<char, char, mbstate_t>}
returns
\tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_length}}%
\indexlibrary{\idxcode{do_length}!\idxcode{codecvt}}%
\begin{itemdecl}
int do_length(stateT& state, const externT* from, const externT* from_end,
              size_t max) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\preconditions
\tcode{(from<=from_end)}
well-defined and
\tcode{true};
\tcode{state} initialized, if at the beginning of a sequence, or else equal to
the result of converting the preceding characters in the sequence.

\pnum
\effects
The effect on the \tcode{state} argument is ``as if'' it called
\tcode{do_in(state, from, from_end, from, to, to+max, to)}
for \tcode{to} pointing to a buffer of at least \tcode{max} elements.

\pnum
\returns
\tcode{(from_next-from)}
where
\tcode{from_next}
is the largest value in the range
\tcode{[from,from_end]}
such that the sequence of values in the range
\range{from}{from_next}
represents
\tcode{max}
or fewer valid complete characters of type
\tcode{internT}.
The specialization
\tcode{codecvt<char, char, mbstate_t>},
returns the lesser of
\tcode{max}
and
\tcode{(from_end-from)}.
\end{itemdescr}

\indexlibrary{\idxcode{codecvt}!\idxcode{do_max_length}}%
\indexlibrary{\idxcode{do_max_length}!\idxcode{codecvt}}%
\begin{itemdecl}
int do_max_length() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The maximum value that
\tcode{do_length(state, from, from_end, 1)}
can return for any valid range
\tcode{[from, from_end)}
and
\tcode{stateT}
value
\tcode{state}.
The specialization
\tcode{codecvt<char, char, mbstate_t>\colcol{}do_max_length()}
returns 1.
\end{itemdescr}

\rSec3[locale.codecvt.byname]{Class template \tcode{codecvt_byname}}

\indexlibrary{\idxcode{codecvt_byname}}%
\begin{codeblock}
namespace std {
  template <class internT, class externT, class stateT>
  class codecvt_byname : public codecvt<internT, externT, stateT> {
  public:
    explicit codecvt_byname(const char*, size_t refs = 0);
    explicit codecvt_byname(const string&, size_t refs = 0);
  protected:
    ~codecvt_byname();
  };
}
\end{codeblock}

\rSec2[category.numeric]{The numeric category}

\pnum
The classes
\tcode{num_get<>}
and
\tcode{num_put<>}
handle numeric formatting and parsing.
Virtual functions are provided for several numeric types.
Implementations may (but are not required to) delegate extraction
of smaller types to extractors for larger types.\footnote{Parsing
\tcode{"-1"} correctly into, e.g., an
\tcode{unsigned short}
requires that the corresponding member
\tcode{get()}
at least extract the sign before delegating.}

\pnum
All specifications of member functions for
\tcode{num_put}
and
\tcode{num_get}
in the subclauses of~\ref{category.numeric} only apply to the
specializations required in Tables~\ref{tab:localization.category.facets}
and~\ref{tab:localization.required.specializations}~(\ref{locale.category}), namely
\tcode{num_get<char>},
\tcode{num_get<wchar_t>},
\tcode{num_get<C, InputIterator>},
\tcode{num_put<char>},
\tcode{num_put<wchar_t>},
and
\tcode{num_put<C,OutputIterator>}.
These specializations refer to the
\tcode{ios_base\&}
argument for formatting specifications~(\ref{locale.categories}),
and to its imbued locale for the
\tcode{numpunct<>}
facet to identify all numeric punctuation preferences,
and also for the
\tcode{ctype<>}
facet to perform character classification.

\pnum
Extractor and inserter members of the standard iostreams use
\tcode{num_get<>}
and
\tcode{num_put<>}
member functions for formatting and parsing numeric values~(\ref{istream.formatted.reqmts}, \ref{ostream.formatted.reqmts}).

\rSec3[locale.num.get]{Class template \tcode{num_get}}

\indexlibrary{\idxcode{num_get}}%
\begin{codeblock}
namespace std {
  template <class charT, class InputIterator = istreambuf_iterator<charT> >
  class num_get : public locale::facet {
  public:
    typedef charT            char_type;
    typedef InputIterator    iter_type;

    explicit num_get(size_t refs = 0);

    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, bool& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, long long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned short& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned int& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, unsigned long long& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, float& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, double& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, long double& v) const;
    iter_type get(iter_type in, iter_type end, ios_base&,
                  ios_base::iostate& err, void*& v) const;

    static locale::id id;

  protected:
    ~num_get();
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, bool& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned short& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned int& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, unsigned long long& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, float& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, double& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, long double& v) const;
    virtual iter_type do_get(iter_type, iter_type, ios_base&,
                             ios_base::iostate& err, void*& v) const;
  };
}
\end{codeblock}
 
\pnum
The facet
\tcode{num_get}
is used to parse numeric values from an input sequence such as an istream.

\rSec4[facet.num.get.members]{\tcode{num_get} members}

\indexlibrary{\idxcode{num_get}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{num_get}}%
\begin{itemdecl}
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, bool& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long long& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned short& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned int& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned long& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned long long& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, float& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, double& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long double& val) const;
iter_type get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, void*& val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get(in, end, str, err, val)}.
\end{itemdescr}

\rSec4[facet.num.get.virtuals]{\tcode{num_get} virtual functions}

\indexlibrary{\idxcode{num_get}!\idxcode{do_get}}%
\indexlibrary{\idxcode{do_get}!\idxcode{num_get}}%
\begin{itemdecl}
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long long& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned short& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned int& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned long& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, unsigned long long& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, float& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, double& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, long double& val) const;
iter_type do_get(iter_type in, iter_type end, ios_base& str,
  ios_base::iostate& err, void*& val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters from \tcode{in},
interpreting them according to
\tcode{str.flags()},
\tcode{use_facet<ctype<\brk{}charT> >(loc)},
and
\tcode{use_facet< numpunct<charT> >(loc)},
where
\tcode{loc}
is
\tcode{str.getloc()}.

\pnum
The details of this operation occur in three stages

\begin{itemize}
\item
Stage 1:
Determine a conversion specifier
\item
Stage 2: Extract characters from \tcode{in} and determine a corresponding
\tcode{char}
value for the format expected by the conversion specification determined
in stage 1.
\item
Stage 3:
Store results
\end{itemize}

\pnum
The details of the stages are presented below.

\begin{description}
\stage{1}
The function initializes local variables via

\begin{codeblock}
fmtflags flags = str .flags();
fmtflags basefield = (flags & ios_base::basefield);
fmtflags uppercase = (flags & ios_base::uppercase);
fmtflags boolalpha = (flags & ios_base::boolalpha);
\end{codeblock}

For conversion to an integral type, the
function determines the integral conversion specifier as indicated in
Table~\ref{tab:localization.integer.conversions.in}.
The table is ordered.
That is, the first line whose condition is true applies.

\begin{floattable}{Integer conversions}{tab:localization.integer.conversions.in}
{lc}
\topline
\lhdr{State}                    &   \tcode{stdio} equivalent   \\ \capsep
\tcode{basefield == oct}        &   \tcode{\%o}                 \\ \rowsep
\tcode{basefield == hex}        &   \tcode{\%X}                 \\ \rowsep
\tcode{basefield == 0}          &   \tcode{\%i}                 \\ \capsep
\tcode{signed} integral type    &   \tcode{\%d}                 \\ \rowsep
\tcode{unsigned} integral type  &   \tcode{\%u}                 \\
\end{floattable}

For conversions to a  floating type the specifier is
\tcode{\%g}.

For conversions to
\tcode{void*}
the specifier is
\tcode{\%p}.

A length modifier is added to the conversion specification, if needed,
as indicated in Table~\ref{tab:localization.length.modifier.in}.

\begin{floattable}{Length modifier}{tab:localization.length.modifier.in}
{lc}
\topline
\lhdr{Type}                 &   Length modifier \\ \capsep
\tcode{short}               &   \tcode{h}       \\ \rowsep
\tcode{unsigned short}      &   \tcode{h}       \\ \rowsep
\tcode{long}                &   \tcode{l}       \\ \rowsep
\tcode{unsigned long}       &   \tcode{l}       \\ \rowsep
\tcode{long long}           &   \tcode{ll}      \\ \rowsep
\tcode{unsigned long long}  &   \tcode{ll}      \\ \rowsep
\tcode{double}              &   \tcode{l}       \\ \rowsep
\tcode{long double}         &   \tcode{L}       \\
\end{floattable}

\stage{2}
If
\tcode{in==end}
then stage 2 terminates.
Otherwise a
\tcode{charT}
is taken from \tcode{in} and local variables are initialized as if by

\begin{codeblock}
char_type ct = *in ;
char c = src[find(atoms, atoms + sizeof(src) - 1, ct) - atoms];
if (ct ==  use_facet<numpunct<charT> >(loc).decimal_point())
c = '.';
bool discard =
  ct == use_facet<numpunct<charT> >(loc).thousands_sep()
  && use_facet<numpunct<charT> >(loc).grouping().length() != 0;
\end{codeblock}

where the values
\tcode{src}
and
\tcode{atoms}
are defined as if by:

\begin{codeblock}
static const char src[] = "0123456789abcdefxABCDEFX+-";
char_type atoms[sizeof(src)];
use_facet<ctype<charT> >(loc).widen(src, src + sizeof(src), atoms);
\end{codeblock}

for this value of
\tcode{loc}.

If \tcode{discard} is true, then if
\tcode{'.'}
has not yet been accumulated, then the position of the character is remembered,
but the character is otherwise ignored.
Otherwise, if
\tcode{'.'}
has already been accumulated, the character is discarded and
Stage 2 terminates.
If it is not discarded, then a check is made to determine if \tcode{c} is
allowed as the next character of an input field of the conversion specifier
returned by Stage 1. If so, it is accumulated.

If the character is either discarded or accumulated then \tcode{in}
is advanced by
\tcode{++in}
and processing returns to the beginning of stage 2.

\stage{3}
The sequence of \tcode{char}{s} accumulated in stage 2 (the field) is converted to a numeric value by the rules of one of the functions declared in the header \tcode{<cstdlib>}:

\begin{itemize}
\item For a signed integer value, the function \tcode{strtoll}.

\item For an unsigned integer value, the function \tcode{strtoull}.

\item For a floating-point value, the function \tcode{strtold}.
\end{itemize}

The numeric value to be stored can be one of:

\begin{itemize}
\item zero, if the conversion function fails to convert the entire field. \tcode{ios_base::failbit} is assigned to \tcode{err}.

\item the most positive representable value, if the field represents a value too large positive to be represented in \tcode{val}. \tcode{ios_base::failbit} is assigned to \tcode{err}.

\item the most negative representable value or zero for an unsigned integer type, if the field represents a value too large negative to be represented in \tcode{val}. \tcode{ios_base::failbit} is assigned to \tcode{err}.

\item the converted value, otherwise.
\end{itemize}

The resultant numeric value is stored in \tcode{val}.

\end{description}

\pnum
Digit grouping is checked.
That is, the positions of discarded
separators is examined for consistency with
\tcode{use_facet<numpunct<charT> >(loc).grouping()}.
If they are not consistent then
\tcode{ios_base::failbit}
is assigned to \tcode{err}.

\pnum
In any case, if stage 2 processing was terminated by the test for
\tcode{in==end}
then
\tcode{err |=ios_base::eofbit}
is performed.
\end{itemdescr}

\indexlibrary{\idxcode{do_get}!\idxcode{num_get}}%
\indexlibrary{\idxcode{num_get}!\idxcode{do_get}}%
\begin{itemdecl}
iter_type do_get(iter_type in, iter_type end, ios_base& str,
                 ios_base::iostate& err, bool& val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{(str\tcode{.flags()\&ios_base::boolalpha)==0}}
then input proceeds as it would for a
\tcode{long}
except that if a value is being stored into \tcode{val},
the value is determined according to the following:
If the value to be stored is 0 then
\tcode{false}
is stored.
If the value is 1
then
\tcode{true}
is stored.
Otherwise \tcode{true} is stored and \tcode{ios_base::failbit} is assigned to \tcode{err}.

\pnum
Otherwise target sequences are determined ``as if'' by calling the
members
\tcode{falsename()}
and
\tcode{truename()}
of the facet obtained by
\tcode{use_facet<numpunct<charT> >(str.getloc())}.
Successive characters in the range
\range{in}{end}
(see~\ref{sequence.reqmts}) are obtained and
matched against corresponding positions in the target sequences only
as necessary to identify a unique match. The input iterator \tcode{in} is
compared to \tcode{end} only when necessary to obtain a character. If a target sequence is uniquely matched, \tcode{val} is set to the
corresponding value. Otherwise \tcode{false} is stored and \tcode{ios_base::failbit} is assigned to \tcode{err}.

\pnum
The \tcode{in} iterator is always left pointing one position beyond the last
character successfully matched. If \tcode{val} is set, then \tcode{err} is set to
\tcode{str.goodbit};
or to
\tcode{str.eofbit}
if, when seeking another character to match, it is found that
\tcode{(in == end)}.
If \tcode{val} is not set, then \tcode{err} is set to
\tcode{str.failbit};
or to
\tcode{(str.failbit|str.eofbit)}
if the reason for the failure was that
\tcode{(in == end)}.
\enterexample
For targets
\tcode{true}:
\tcode{"a"}
and
\tcode{false}:
\tcode{"abb"},
the input sequence
 \tcode{"a"}
yields
\tcode{val == true}
and
\tcode{err == str.eofbit};
the input sequence
 \tcode{"abc"}
yields
\tcode{err = str.failbit},
with \tcode{in} ending at the
\tcode{'c'}
element. For targets
\tcode{true}:
\tcode{"1"}
and
\tcode{false}:
\tcode{"0"}, the input sequence \tcode{"1"} yields
\tcode{val == true}
and
\tcode{err == str.goodbit}.
For empty targets \tcode{("")}, any input sequence yields
\tcode{err == str.failbit}.
\exitexample

\pnum
\returns
\tcode{in}.
\end{itemdescr}

\rSec3[locale.nm.put]{Class template \tcode{num_put}}

\indexlibrary{\idxcode{num_put}}%
\begin{codeblock}
namespace std {
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
  class num_put : public locale::facet {
  public:
    typedef charT            char_type;
    typedef OutputIterator   iter_type;

    explicit num_put(size_t refs = 0);

    iter_type put(iter_type s, ios_base& f, char_type fill, bool v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill, long v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill, long long v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  unsigned long v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  unsigned long long v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  double v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  long double v) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  const void* v) const;

    static locale::id id;

  protected:
    ~num_put();
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             bool v) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             long v) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             long long v) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             unsigned long) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             unsigned long long) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             double v) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             long double v) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type fill,
                             const void* v) const;
  };
}
\end{codeblock}

\pnum
The facet
\tcode{num_put}
is used to format numeric values to a character sequence such as an ostream.

\rSec4[facet.num.put.members]{\tcode{num_put} members}

\indexlibrary{\idxcode{num_put}!\idxcode{put}}%
\indexlibrary{\idxcode{put}!\idxcode{num_put}}%
\begin{itemdecl}
iter_type put(iter_type out, ios_base& str, char_type fill,
  bool val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  long val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  long long val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  unsigned long val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  unsigned long long val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  double val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  long double val) const;
iter_type put(iter_type out, ios_base& str, char_type fill,
  const void* val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_put(out, str, fill, val)}.
\end{itemdescr}

\rSec4[facet.num.put.virtuals]{\tcode{num_put} virtual functions}

\indexlibrary{\idxcode{num_put}!\idxcode{do_put}}%
\indexlibrary{\idxcode{do_put}!\idxcode{num_put}}%
\begin{itemdecl}
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  long val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  long long val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  unsigned long val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  unsigned long long val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  double val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  long double val) const;
iter_type do_put(iter_type out, ios_base& str, char_type fill,
  const void* val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Writes characters to the sequence \tcode{out},
formatting \tcode{val} as desired.
In the following description,
a local variable initialized with

\begin{codeblock}
locale loc = str.getloc();
\end{codeblock}

\pnum
The details of this operation occur in several stages:

\begin{itemize}
\item
Stage 1:
Determine a printf conversion specifier \tcode{spec} and
determining the characters that would be printed by
\tcode{printf}~(\ref{c.files})
given this conversion specifier for

\begin{codeblock}
printf(spec, val )
\end{codeblock}

assuming that the current locale is
the \tcode{"C"} locale.
\item
Stage 2:
Adjust the representation by converting each
\tcode{char}
determined by stage 1 to a
\tcode{charT}
using a conversion and values returned by members of
\tcode{use_facet< numpunct<charT> >(str.getloc())}
\item
Stage 3:
Determine where padding is required.
\item
Stage 4:
Insert the sequence into the \tcode{out}.
\end{itemize}

\pnum
Detailed descriptions of each stage follow.

\pnum
\returns
\tcode{out}.

\pnum
\begin{description}
\stage{1}
The first action of stage 1 is to determine a conversion specifier.
The tables that describe this determination use the following local variables

\begin{codeblock}
fmtflags flags = str.flags() ;
fmtflags basefield =  (flags & (ios_base::basefield));
fmtflags uppercase =  (flags & (ios_base::uppercase));
fmtflags floatfield = (flags & (ios_base::floatfield));
fmtflags showpos =    (flags & (ios_base::showpos));
fmtflags showbase =   (flags & (ios_base::showbase));
\end{codeblock}

All tables used in describing stage 1 are ordered.
That is, the first line whose condition is true applies.
A line without a condition is the default behavior when none of the earlier
lines apply.

For conversion from an integral type other than a character type, the
function determines the integral conversion specifier as indicated in
Table~\ref{tab:localization.integer.conversions.out}.

\begin{floattable}{Integer conversions}{tab:localization.integer.conversions.out}
{lc}
\topline
\lhdr{State}                        &   \tcode{stdio} equivalent       \\ \capsep
\tcode{basefield == ios_base::oct}                      &   \tcode{\%o} \\ \rowsep
\tcode{(basefield == ios_base::hex) \&\& !uppercase}    &   \tcode{\%x} \\ \rowsep
\tcode{(basefield == ios_base::hex)}                    &   \tcode{\%X} \\ \rowsep
for a \tcode{signed} integral type                     &   \tcode{\%d} \\ \rowsep
for an \tcode{unsigned} integral type                  &   \tcode{\%u} \\
\end{floattable}

For conversion from a floating-point type, the function determines
the floating-point conversion specifier as indicated in Table~\ref{tab:localization.fp.conversions.out}.

\begin{floattable}{Floating-point conversions}{tab:localization.fp.conversions.out}
{lc}
\topline
\lhdr{State}            &   \tcode{stdio} equivalent                       \\ \capsep
\tcode{floatfield == ios_base::fixed}                       &   \tcode{\%f} \\ \rowsep
\tcode{floatfield == ios_base::scientific \&\& !uppercase}  &   \tcode{\%e} \\ \rowsep
\tcode{floatfield == ios_base::scientific}                  &   \tcode{\%E} \\ \rowsep
\tcode{floatfield == (ios_base::fixed | ios_base::scientific) \&\& !uppercase} & \tcode{\%a} \\ \rowsep
\tcode{floatfield == (ios_base::fixed | ios_base::scientific)} & \tcode{\%A} \\ \rowsep
\tcode{!uppercase}                                          &   \tcode{\%g} \\ \rowsep
\textit{otherwise}                                          &   \tcode{\%G} \\
\end{floattable}
 
For conversions from an integral or floating-point
type a length modifier is added to the
conversion specifier as indicated in  Table~\ref{tab:localization.length.modifier.out}.

\begin{floattable}{Length modifier}{tab:localization.length.modifier.out}
{lc}
\topline
\lhdr{Type}                 &   Length modifier \\ \capsep
\tcode{long}                &   \tcode{l}       \\ \rowsep
\tcode{long long}           &   \tcode{ll}      \\ \rowsep
\tcode{unsigned long}       &   \tcode{l}       \\ \rowsep
\tcode{unsigned long long}  &   \tcode{ll}      \\ \rowsep
\tcode{long double}         &   \tcode{L}       \\ \rowsep
\textit{otherwise}          &   \textit{none}   \\
\end{floattable}

The conversion specifier has the following optional additional qualifiers
prepended as indicated in Table~\ref{tab:localization.numeric.conversions}.

\begin{floattable}{Numeric conversions}{tab:localization.numeric.conversions}
{llc}
\topline
\lhdr{Type(s)}                  &   \chdr{State}                &   \tcode{stdio} equivalent   \\ \capsep
an integral type                &   \tcode{flags \& showpos}    &   \tcode{+}                   \\
                                &   \tcode{flags \& showbase}   &   \tcode{\#}                  \\ \rowsep
a floating-point type           &   \tcode{flags \& showpos}    &   \tcode{+}                   \\
                                &   \tcode{flags \& showpoint}  &   \tcode{\#}                  \\
\end{floattable}

For conversion from a floating-point type,
if \tcode{floatfield != (ios_base::fixed | ios_base::\brk{}scientific)},
\tcode{str.precision()}
is specified as precision in the conversion specification.
Otherwise, no precision is specified.
 
For conversion from
\tcode{void*}
the specifier is
\tcode{\%p}.
 
The representations at the end of stage 1 consists of the
\tcode{char}'s
that would be printed by a call of
\tcode{printf(s, val)}
where \tcode{s} is the conversion specifier determined above.

\stage{2}
Any character \tcode{c} other than a decimal point(.) is converted to a
\tcode{charT}
via
\tcode{use_facet<ctype<charT> >(loc).widen( c )}

A local variable \tcode{punct} is initialized via
\begin{codeblock}
const numpunct<charT>& punct = use_facet< numpunct<charT> >(str.getloc());
\end{codeblock}
 
For arithmetic types,
\tcode{punct.thousands_sep()}
characters are inserted into the sequence as determined by the value returned
by
\tcode{punct.do_grouping()}
using the method described in~\ref{facet.numpunct.virtuals}
 
Decimal point characters(.) are replaced by
\tcode{punct.decimal_point()}

\stage{3}
A local variable is initialized as

\begin{codeblock}
fmtflags adjustfield=   (flags & (ios_base::adjustfield));
\end{codeblock}
 
The location of any padding\footnote{The conversion specification
\tcode{\#o}
generates a leading
\tcode{0}
which is
\textit{not}
a padding character.} is determined according to Table~\ref{tab:localization.fill.padding}.

\begin{floattable}{Fill padding}{tab:localization.fill.padding}
{p{3in}l}
\topline
\lhdr{State}                            &   \rhdr{Location}                 \\ \capsep
\tcode{adjustfield == ios_base::left}   &   pad after                       \\ \rowsep
\tcode{adjustfield == ios_base::right}  &   pad before                      \\ \rowsep
\tcode{adjustfield == internal} and a sign occurs in the representation
                                        &   pad after the sign              \\ \rowsep
\tcode{adjustfield == internal} and representation after stage 1
began with 0x or 0X                     &   pad after x or X                \\ \rowsep
\textit{otherwise}                      &   pad before                      \\
\end{floattable}

If
\tcode{str.width()}
is nonzero and the number of
\tcode{charT}'s
in the sequence after stage 2 is less than
\tcode{str.\brk{}width()},
then enough \tcode{fill} characters are added to the sequence at the position
indicated for padding to bring the length of the sequence to
\tcode{str.width()}.
 
\tcode{str.width(0)}
is called.

\stage{4}
The sequence of
\tcode{charT}'s
at the end of stage 3 are output via

\begin{codeblock}
*out++ = c
\end{codeblock}
\end{description}
\end{itemdescr}

\indexlibrary{\idxcode{do_put}!\idxcode{num_put}}%
\indexlibrary{\idxcode{num_put}!\idxcode{do_put}}%
\begin{itemdecl}
iter_type do_put(iter_type out, ios_base& str, char_type fill,
                 bool val) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If
\tcode{(str.flags() \& ios_base::boolalpha) == 0}
returns
\tcode{do_put(out, str, fill,\\(int)val)},
otherwise obtains a string
\tcode{s}
as if by
\begin{codeblock}
string_type s =
  val ? use_facet<ctype<charT> >(loc).truename()
    : use_facet<ctype<charT> >(loc).falsename();
\end{codeblock}
and then inserts each character
\tcode{c}
of
\tcode{s}
into
\tcode{out}
via
\tcode{*out++ = c}
and returns
\tcode{out}.
\end{itemdescr}

\rSec2[facet.numpunct]{The numeric punctuation facet}

\rSec3[locale.numpunct]{Class template \tcode{numpunct}}

\indexlibrary{\idxcode{numpunct}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class numpunct : public locale::facet {
  public:
    typedef charT               char_type;
    typedef basic_string<charT> string_type;

    explicit numpunct(size_t refs = 0);

    char_type    decimal_point()   const;
    char_type    thousands_sep()   const;
    string       grouping()        const;
    string_type  truename()        const;
    string_type  falsename()       const;

    static locale::id id;

  protected:
   ~numpunct();                 // virtual
    virtual char_type    do_decimal_point() const;
    virtual char_type    do_thousands_sep() const;
    virtual string       do_grouping()      const;
    virtual string_type  do_truename()      const;      // for \tcode{bool}
    virtual string_type  do_falsename()     const;      // for \tcode{bool}
  };
}
\end{codeblock}

\pnum
\tcode{numpunct<>}
specifies numeric punctuation.
The specializations required in Table~\ref{tab:localization.category.facets}~(\ref{locale.category}), namely
\tcode{numpunct<\brk{}wchar_t>}
and
\tcode{numpunct<char>},
provide classic
\tcode{"C"}
numeric formats,
i.e., they contain information equivalent to that contained in the
\tcode{"C"}
locale or their wide character counterparts as if obtained by
a call to
\tcode{widen}.

\pnum
The syntax for number formats is as follows, where
\tcode{digit}
represents the radix set specified by the
\tcode{fmtflags}
argument value, and
\tcode{thousands-sep}
and
\tcode{decimal-point}
are the results of corresponding
\tcode{numpunct<charT>}
members.
Integer values have the format:

\begin{codeblock}
integer   ::= [sign] units
sign      ::= plusminus
plusminus ::= '+' | '-'
units     ::= digits [thousands-sep units]
digits    ::= digit [digits]
\end{codeblock}

and floating-point values have:

\begin{codeblock}
floatval ::= [sign] units [decimal-point [digits]] [e [sign] digits] |
             [sign]        decimal-point  digits   [e [sign] digits]
e        ::= 'e' | 'E'
\end{codeblock}

where the number of digits between
\tcode{thousands-sep}s
is as specified by
\tcode{do_grouping()}.
For parsing, if the
\tcode{digits}
portion contains no thousands-separators, no grouping constraint
is applied.

\rSec4[facet.numpunct.members]{\tcode{numpunct} members}

\indexlibrary{\idxcode{numpunct}!\idxcode{decimal_point}}%
\indexlibrary{\idxcode{decimal_point}!\idxcode{numpunct}}%
\begin{itemdecl}
char_type decimal_point() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_decimal_point()}
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{thousands_sep}}%
\indexlibrary{\idxcode{thousands_sep}!\idxcode{numpunct}}%
\begin{itemdecl}
char_type thousands_sep() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_thousands_sep()}
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{grouping}}%
\indexlibrary{\idxcode{grouping}!\idxcode{numpunct}}%
\begin{itemdecl}
string grouping()  const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_grouping()}
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{truename}}%
\indexlibrary{\idxcode{truename}!\idxcode{numpunct}}%
\indexlibrary{\idxcode{numpunct}!\idxcode{falsename}}%
\indexlibrary{\idxcode{falsename}!\idxcode{numpunct}}%
\begin{itemdecl}
string_type truename()  const;
string_type falsename() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_truename()}
or
\tcode{do_falsename()},
respectively.
\end{itemdescr}

\rSec4[facet.numpunct.virtuals]{\tcode{numpunct} virtual functions}

\indexlibrary{\idxcode{numpunct}!\idxcode{do_decimal_point}}%
\indexlibrary{\idxcode{do_decimal_point}!\idxcode{numpunct}}%
\begin{itemdecl}
char_type do_decimal_point() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A character for use as the decimal radix separator.
The required specializations return \tcode{'.'} or \tcode{L'.'}.
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{do_thousands_sep}}%
\indexlibrary{\idxcode{do_thousands_sep}!\idxcode{numpunct}}%
\begin{itemdecl}
char_type do_thousands_sep() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A character for use as the digit group separator.
The required specializations return \tcode{','} or \tcode{L','}.
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{do_grouping}}%
\indexlibrary{\idxcode{do_grouping}!\idxcode{numpunct}}%
\begin{itemdecl}
string do_grouping() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A basic_string<char> \tcode{vec} used as a vector of integer values,
in which each element
\tcode{vec[i]}
represents the number of digits\footnote{Thus, the string
\tcode{"\textbackslash003"} specifies groups of 3 digits each, and
\tcode{"3"} probably indicates groups of 51 (!) digits each,
because 51 is the ASCII value of \tcode{"3"}.}
in the group at position \tcode{i}, starting with position 0 as the
rightmost group.
If
\tcode{vec.size() <= i},
the number is the same as group
\tcode{(i-1)};
if
\tcode{(i<0 || vec[i]<=0 || vec[i]==CHAR_MAX)},
the size of the digit group is unlimited.

\pnum
The required specializations return the empty string, indicating
no grouping.
\end{itemdescr}

\indexlibrary{\idxcode{numpunct}!\idxcode{do_truename}}%
\indexlibrary{\idxcode{do_truename}!\idxcode{numpunct}}%
\indexlibrary{\idxcode{numpunct}!\idxcode{do_falsename}}%
\indexlibrary{\idxcode{do_falsename}!\idxcode{numpunct}}%
\begin{itemdecl}
string_type do_truename()  const;
string_type do_falsename() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A string representing the name of the boolean value
\tcode{true}
or
\tcode{false},
respectively.

\pnum
In the base class implementation these names are
\tcode{"true"} and \tcode{"false"}, or \tcode{L"true"} and \tcode{L"false"}.
\end{itemdescr}

\rSec3[locale.numpunct.byname]{Class template \tcode{numpunct_byname}}

\indexlibrary{\idxcode{numpunct_byname}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class numpunct_byname : public numpunct<charT> {
  // this class is specialized for \tcode{char} and \tcode{wchar_t}.
  public:
    typedef charT                char_type;
    typedef basic_string<charT>  string_type;
    explicit numpunct_byname(const char*, size_t refs = 0);
    explicit numpunct_byname(const string&, size_t refs = 0);
  protected:
   ~numpunct_byname();
  };
}
\end{codeblock}

\rSec2[category.collate]{The collate category}

\rSec3[locale.collate]{Class template \tcode{collate}}

\indexlibrary{\idxcode{collate}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class collate : public locale::facet {
  public:
    typedef charT               char_type;
    typedef basic_string<charT> string_type;

    explicit collate(size_t refs = 0);

    int compare(const charT* low1, const charT* high1,
                const charT* low2, const charT* high2) const;
    string_type transform(const charT* low, const charT* high) const;
    long hash(const charT* low, const charT* high) const;

    static locale::id id;

  protected:
    ~collate();
    virtual int do_compare(const charT* low1, const charT* high1,
                           const charT* low2, const charT* high2) const;
    virtual string_type do_transform(const charT* low, const charT* high) const;
    virtual long do_hash (const charT* low, const charT* high) const;
  };
}
\end{codeblock}

\pnum
The class
\tcode{collate<charT>}
provides features for use in the
collation (comparison) and hashing of strings.
A locale member function template,
\tcode{operator()},
uses the collate facet to allow a locale to act directly as the predicate
argument for standard algorithms (Clause~\ref{algorithms}) and containers operating on strings.
The specializations required in Table~\ref{tab:localization.category.facets}~(\ref{locale.category}), namely
\tcode{collate<char>}
and
\tcode{collate<wchar_t>},
apply lexicographic ordering~(\ref{alg.lex.comparison}).

\pnum
Each function compares a string of characters
\tcode{*p}
in the range
\range{low}{high}.

\rSec4[locale.collate.members]{\tcode{collate} members}

\indexlibrary{\idxcode{collate}!\idxcode{compare}}%
\indexlibrary{\idxcode{compare}!\idxcode{collate}}%
\begin{itemdecl}
int compare(const charT* low1, const charT* high1,
            const charT* low2, const charT* high2) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_compare(low1, high1, low2, high2)}
\end{itemdescr}

\indexlibrary{\idxcode{collate}!\idxcode{transform}}%
\indexlibrary{\idxcode{transform}!\idxcode{collate}}%
\begin{itemdecl}
string_type transform(const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_transform(low, high)}
\end{itemdescr}

\indexlibrary{\idxcode{collate}!\idxcode{hash}}%
\indexlibrary{\idxcode{hash}!\idxcode{collate}}%
\begin{itemdecl}
long hash(const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_hash(low, high)}
\end{itemdescr}

\rSec4[locale.collate.virtuals]{\tcode{collate} virtual functions}

\indexlibrary{\idxcode{collate}!\idxcode{do_compare}}%
\indexlibrary{\idxcode{do_compare}!\idxcode{collate}}%
\begin{itemdecl}
int do_compare(const charT* low1, const charT* high1,
               const charT* low2, const charT* high2) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{1}
if the first string is greater than the second,
\tcode{-1}
if less, zero otherwise.
The specializations required in Table~\ref{tab:localization.category.facets}~(\ref{locale.category}), namely
\tcode{collate<char>}
and
\tcode{collate<wchar_t>},
implement
a lexicographical comparison~(\ref{alg.lex.comparison}).
\end{itemdescr}

\indexlibrary{\idxcode{collate}!\idxcode{do_transform}}%
\indexlibrary{\idxcode{do_transform}!\idxcode{collate}}%
\begin{itemdecl}
string_type do_transform(const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A
\tcode{basic_string<charT>}
value that, compared lexicographically with the result of calling
\tcode{transform()}
on another string, yields the same result as calling
\tcode{do_compare()}
on the same two strings.\footnote{This function is useful when one string is
being compared to many other strings.}
\end{itemdescr}

\indexlibrary{\idxcode{collate}!\idxcode{do_hash}}%
\indexlibrary{\idxcode{do_hash}!\idxcode{collate}}%
\begin{itemdecl}
long do_hash(const charT* low, const charT* high) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An integer value equal to the result of calling
\tcode{hash()}
on any other string for which
\tcode{do_compare()}
returns 0 (equal) when passed the two strings.
\enternote
The probability that the result equals that for another string which does
not compare equal should be very small, approaching
\tcode{(1.0/numeric_limits<unsigned long>::max())}.
\exitnote
\end{itemdescr}

\rSec3[locale.collate.byname]{Class template \tcode{collate_byname}}

\indexlibrary{\idxcode{collate_byname}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class collate_byname : public collate<charT> {
  public:
    typedef basic_string<charT> string_type;
    explicit collate_byname(const char*, size_t refs = 0);
    explicit collate_byname(const string&, size_t refs = 0);
  protected:
    ~collate_byname();
  };
}
\end{codeblock}

\rSec2[category.time]{The time category}

\pnum
Templates
\tcode{time_get<charT,InputIterator>}
and
\tcode{time_put<charT,OutputIterator>}
provide date and time formatting and parsing.
All specifications of member functions for
\tcode{time_put}
and
\tcode{time_get}
in the subclauses of~\ref{category.time} only apply to the
specializations required in Tables~\ref{tab:localization.category.facets}
and~\ref{tab:localization.required.specializations}~(\ref{locale.category}).
Their members use their
\tcode{ios_base\&},
\tcode{ios_base::iostate\&},
and
\tcode{fill}
arguments as described in~(\ref{locale.categories}), and the
\tcode{ctype<>}
facet, to determine formatting details.

\rSec3[locale.time.get]{Class template \tcode{time_get}}

\indexlibrary{\idxcode{time_get}}%
\begin{codeblock}
namespace std {
  class time_base {
  public:
    enum dateorder { no_order, dmy, mdy, ymd, ydm };
  };

  template <class charT, class InputIterator = istreambuf_iterator<charT> >
  class time_get : public locale::facet, public time_base {
  public:
    typedef charT            char_type;
    typedef InputIterator    iter_type;

    explicit time_get(size_t refs = 0);

    dateorder date_order()  const { return do_date_order(); }
    iter_type get_time(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm* t)  const;
    iter_type get_date(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm* t)  const;
    iter_type get_weekday(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm* t) const;
    iter_type get_monthname(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm* t) const;
    iter_type get_year(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm* t) const;
    iter_type get(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm *t, char format, char modifier = 0) const;
    iter_type get(iter_type s, iter_type end, ios_base& f,
                       ios_base::iostate& err, tm *t, const char_type *fmt,
                       const char_type *fmtend) const;

    static locale::id id;

  protected:
    ~time_get();
    virtual dateorder do_date_order()  const;
    virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&,
                                  ios_base::iostate& err, tm* t) const;
    virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&,
                                  ios_base::iostate& err, tm* t) const;
    virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
                                     ios_base::iostate& err, tm* t) const;
    virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&,
                                       ios_base::iostate& err, tm* t) const;
    virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&,
                                  ios_base::iostate& err, tm* t) const;
    virtual iter_type do_get(iter_type s, iter_type end, ios_base& f,
                             ios_base::iostate& err, tm *t, char format, char modifier) const;
  };
}
\end{codeblock}

\pnum
\tcode{time_get}
is used to
parse a character sequence, extracting components of a time or date
into a
\tcode{struct tm}
record.
Each
\tcode{get}
member parses a format as produced by a corresponding format specifier to
\tcode{time_put<>::put}.
If the sequence being parsed matches the correct format, the corresponding
members of the
\tcode{struct tm}
argument are set to the values used to produce the sequence; otherwise
either an error is reported or unspecified values are assigned.\footnote{In
other words, user confirmation is required for reliable parsing of
user-entered dates and times, but machine-generated formats can be
parsed reliably.
This allows parsers to be aggressive about
interpreting user variations on standard formats.}

\pnum
If the end iterator is reached during parsing by any of the
\tcode{get()}
member functions, the member sets
\tcode{ios_base::eof\-bit}
in \tcode{err}.

\rSec4[locale.time.get.members]{\tcode{time_get} members}

\indexlibrary{\idxcode{time_get}!\idxcode{date_order}}%
\indexlibrary{\idxcode{date_order}!\idxcode{time_get}}%
\begin{itemdecl}
dateorder date_order() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_date_order()}
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{get_time}}%
\indexlibrary{\idxcode{get_time}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type get_time(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get_time(s, end, str, err, t)}
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{get_date}}%
\indexlibrary{\idxcode{get_date}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type get_date(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get_date(s, end, str, err, t)}
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{get_weekday}}%
\indexlibrary{\idxcode{get_weekday}!\idxcode{time_get}}%
\indexlibrary{\idxcode{time_get}!\idxcode{get_monthname}}%
\indexlibrary{\idxcode{get_monthname}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type get_weekday(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
iter_type get_monthname(iter_type s, iter_type end, ios_base& str,
                        ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get_weekday(s, end, str, err, t)}
or
\tcode{do_get_monthname(s, end, str, err, t)}
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{get_year}}%
\indexlibrary{\idxcode{get_year}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type get_year(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get_year(s, end, str, err, t)}
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{time_get}}%
\indexlibrary{\idxcode{time_get}!\idxcode{get}}%
\begin{itemdecl}
iter_type get(iter_type s, iter_type end, ios_base& f,
    ios_base::iostate& err, tm *t, char format, char modifier = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{do_get(s, end, f, err, t, format, modifier)}
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{time_get}}%
\indexlibrary{\idxcode{time_get}!\idxcode{get}}%
\begin{itemdecl}
iter_type get(iter_type s, iter_type end, ios_base& f,
    ios_base::iostate& err, tm *t, const char_type *fmt, const char_type *fmtend) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{fmt}{fmtend} shall be a valid range.

\pnum
\effects The function starts by evaluating
\tcode{err = ios_base::goodbit}. It then enters a loop, reading zero or more
characters from \tcode{s} at each iteration. Unless otherwise specified below,
the loop terminates when the first of the following conditions holds:

\begin{itemize}
\item The expression \tcode{fmt == fmtend} evaluates to true.

\item The expression \tcode{err == ios_base::goodbit} evaluates to false.

\item The expression \tcode{s == end} evaluates to true,
in which case the function
evaluates \tcode{err = ios_base::eofbit | ios_base::failbit}.

\item The next element of \tcode{fmt} is equal to
\tcode{'\%'}, optionally followed by a
modifier character, followed by a conversion specifier character,
\tcode{format}, together forming a conversion specification valid for the
ISO/IEC 9945 function \tcode{strptime}. If the number of elements in the range
\range{fmt}{fmtend} is not sufficient to unambiguously determine whether the
conversion specification is complete and valid, the function evaluates
\tcode{err = ios_base::failbit}. Otherwise, the function evaluates
\tcode{s = do_get(s, end, f, err, t, format, modifier)}, where the value
of \tcode{modifier} is \tcode{'\textbackslash0'}
when the optional modifier is absent from the conversion specification.
If \tcode{err == ios_base::goodbit} holds after the evaluation of the
expression, the function increments \tcode{fmt} to point just past the end of
the conversion specification and continues looping.

\item The expression \tcode{isspace(*fmt, f.getloc())} evaluates to true,
in which case
the function first increments \tcode{fmt} until
\tcode{fmt == fmtend || !isspace(*fmt, f.getloc())} evaluates to true,
then advances \tcode{s} until
\tcode{s == end || !isspace(*s, f.getloc())} is true, and finally resumes looping.

\item The next character read from \tcode{s} matches the element
pointed to by \tcode{fmt} in
a case-insensitive comparison, in which case the function evaluates
\tcode{++fmt, ++s} and continues looping. Otherwise, the function evaluates
\tcode{err = ios_base::failbit}.
\end{itemize}

\pnum
\enternote The function uses the \tcode{ctype<charT>}
facet installed in \tcode{f}'s locale
to determine valid whitespace characters. It is unspecified by what
means the function performs case-insensitive comparison or whether
multi-character sequences are considered while doing so. \exitnote

\pnum
\returns \tcode{s}
\end{itemdescr}

\rSec4[locale.time.get.virtuals]{\tcode{time_get} virtual functions}

\indexlibrary{\idxcode{time_get}!\idxcode{do_date_order}}%
\indexlibrary{\idxcode{do_date_order}!\idxcode{time_get}}%
\begin{itemdecl}
dateorder do_date_order() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An enumeration value indicating the preferred order of components for
those date formats that are composed of day, month, and year.\footnote{This
function is intended as a convenience only, for common
formats, and may return
\tcode{no_order}
in valid locales.}
Returns
\tcode{no_order}
if the date format specified by
\tcode{'x'}
contains other variable components (e.g., Julian day, week number, week day).
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{do_get_time}}%
\indexlibrary{\idxcode{do_get_time}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters starting at \tcode{s}
until it has extracted those
\tcode{struct tm}
members, and remaining format characters, used by
\tcode{time_put<>::put}
to produce the format specified by
\tcode{"\%H:\%M:\%S"},
or until it encounters an error or end of sequence.

\pnum
\returns
An iterator pointing immediately beyond the last character recognized
as possibly part of a valid time.
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{do_get_date}}%
\indexlibrary{\idxcode{do_get_date}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type do_get_date(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters starting at \tcode{s}
until it has extracted those
\tcode{struct tm}
members and remaining format characters used by
\tcode{time_put<>::put}
to produce one of the following formats,
or until it encounters an error. The format depends on the value returned
by \tcode{date_order()} as shown in
Table~\ref{tab:lib.locale.time.get.virtuals.dogetdate}.

\begin{libtab2}{\tcode{do_get_date} effects}{tab:lib.locale.time.get.virtuals.dogetdate}
{ll}{\tcode{date_order()}}{Format}
\tcode{no_order}  & \tcode{"\%m\%d\%y"} \\
\tcode{dmy}       & \tcode{"\%d\%m\%y"} \\
\tcode{mdy}       & \tcode{"\%m\%d\%y"} \\
\tcode{ymd}       & \tcode{"\%y\%m\%d"} \\
\tcode{ydm}       & \tcode{"\%y\%d\%m"} \\
\end{libtab2}

\pnum
An implementation may also accept additional \impldef{additional formats for \tcode{time_get::do_get_date}} formats.

\pnum
\returns
An iterator pointing immediately beyond the last character recognized
as possibly part of a valid date.
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{do_get_weekday}}%
\indexlibrary{\idxcode{do_get_weekday}!\idxcode{time_get}}%
\indexlibrary{\idxcode{time_get}!\idxcode{do_get_monthname}}%
\indexlibrary{\idxcode{do_get_monthname}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type do_get_weekday(iter_type s, iter_type end, ios_base& str,
                         ios_base::iostate& err, tm* t) const;
iter_type do_get_monthname(iter_type s, iter_type end, ios_base& str,
                           ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters starting at \tcode{s}
until it has extracted the (perhaps abbreviated) name of a weekday or month.
If it finds an abbreviation that is followed by characters that could
match a full name, it continues reading until it matches the full name or
fails.
It sets the appropriate
\tcode{struct tm}
member accordingly.

\pnum
\returns
An iterator pointing immediately beyond the last character recognized
as part of a valid name.
\end{itemdescr}

\indexlibrary{\idxcode{time_get}!\idxcode{do_get_year}}%
\indexlibrary{\idxcode{do_get_year}!\idxcode{time_get}}%
\begin{itemdecl}
iter_type do_get_year(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters starting at \tcode{s}
until it has extracted an unambiguous year identifier.
It is
\impldef{whether \tcode{time_get::do_get_year} accepts two-digit year numbers} whether
two-digit year numbers are accepted,
and (if so) what century they are assumed to lie in.
Sets the
\tcode{t->tm_year}
member accordingly.

\pnum
\returns
An iterator pointing immediately beyond the last character recognized
as part of a valid year identifier.
\end{itemdescr}

\indexlibrary{\idxcode{do_get}!\idxcode{time_get}}%
\indexlibrary{\idxcode{time_get}!\idxcode{do_get}}%
\begin{itemdecl}
iter_type do_get(iter_type s, iter_type end, ios_base& f,
    ios_base::iostate& err, tm *t, char format, char modifier) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{t} shall point to an object.

\pnum
\effects The function starts by evaluating
\tcode{err = ios_base::goodbit}. It
then reads characters starting at \tcode{s} until it encounters an error, or
until it has extracted and assigned those \tcode{struct tm} members, and any
remaining format characters, corresponding to a conversion directive
appropriate for the ISO/IEC 9945 function \tcode{strptime}, formed by
concatenating \tcode{'\%'}, the \tcode{modifier} character,
when non-NUL, and the \tcode{format}
character. When the concatenation fails to yield a complete valid
directive the function leaves the object pointed to by \tcode{t} unchanged and
evaluates \tcode{err |= ios_base::failbit}. When \tcode{s == end}
evaluates to true after reading a character the function evaluates
\tcode{err |= ios_base::eofbit}.

\pnum
For complex conversion directives such as \tcode{\%c},
\tcode{\%x}, or \tcode{\%X}, or directives
that involve the optional modifiers \tcode{E} or \tcode{O},
when the function is unable
to unambiguously determine some or all \tcode{struct tm} members from the input
sequence \range{s}{end}, it evaluates \tcode{err |= ios_base::eofbit}.
In such cases the values of those \tcode{struct tm} members are unspecified
and may be outside their valid range.

\pnum
\note It is unspecified whether multiple calls to
\tcode{do_get()} with the
address of the same \tcode{struct tm} object will update the current contents of
the object or simply overwrite its members. Portable programs must zero
out the object before invoking the function.

\pnum
\returns An iterator pointing immediately beyond the last character
recognized as possibly part of a valid input sequence for the given
\tcode{format} and \tcode{modifier}.
\end{itemdescr}

\rSec3[locale.time.get.byname]{Class template \tcode{time_get_byname}}

\indexlibrary{\idxcode{time_get_byname}}%
\begin{codeblock}
namespace std {
  template <class charT, class InputIterator = istreambuf_iterator<charT> >
  class time_get_byname : public time_get<charT, InputIterator> {
  public:
    typedef time_base::dateorder dateorder;
    typedef InputIterator        iter_type;

    explicit time_get_byname(const char*, size_t refs = 0);
    explicit time_get_byname(const string&, size_t refs = 0);
  protected:
    ~time_get_byname();
  };
}
\end{codeblock}

\rSec3[locale.time.put]{Class template \tcode{time_put}}

\indexlibrary{\idxcode{time_put}}%
\begin{codeblock}
namespace std {
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
  class time_put : public locale::facet {
  public:
    typedef charT            char_type;
    typedef OutputIterator   iter_type;

    explicit time_put(size_t refs = 0);

    // the following is implemented in terms of other member functions.
    iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb,
                  const charT* pattern, const charT* pat_end) const;
    iter_type put(iter_type s, ios_base& f, char_type fill,
                  const tm* tmb, char format, char modifier = 0) const;

    static locale::id id;

  protected:
    ~time_put();
    virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t,
                             char format, char modifier) const;
  };
}
\end{codeblock}

\rSec4[locale.time.put.members]{\tcode{time_put} members}

\indexlibrary{\idxcode{time_put}!\idxcode{put}}%
\indexlibrary{\idxcode{put}!\idxcode{time_put}}%
\begin{itemdecl}
iter_type put(iter_type s, ios_base& str, char_type fill, const tm* t,
              const charT* pattern, const charT* pat_end) const;
iter_type put(iter_type s, ios_base& str, char_type fill, const tm* t,
              char format, char modifier = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The first form steps through the sequence from
\tcode{pattern}
to
\tcode{pat_end},
identifying characters that are part of a format sequence.
Each character that is not part of a format sequence is written to
\tcode{s}
immediately, and each format sequence, as it is identified, results in
a call to
\tcode{do_put};
thus, format elements and other characters are interleaved in the output
in the order in which they appear in the pattern.
Format sequences are identified by converting each character
\tcode{c}
to a
\tcode{char}
value as if by
\tcode{ct.narrow(c,0)},
where
\tcode{ct}
is a reference to
\tcode{ctype<charT>}
obtained from
\tcode{str.getloc()}.
The first character of each sequence is equal to
\tcode{'\%'},
followed by an optional modifier character
\tcode{mod}\footnote{Although the C programming language defines no modifiers,
most vendors do.} and a format specifier character
\tcode{spec}
as defined for the function
\tcode{strftime}.
If no modifier character is present,
\tcode{mod}
is zero.
For each valid format sequence identified, calls
\tcode{do_put(s, str, fill, t, spec, mod)}.

\pnum
The second form calls
\tcode{do_put(s, str, fill, t, format, modifier)}.

\pnum
\enternote
The \tcode{fill} argument may be used in the implementation-defined
formats or by derivations. A space character is a reasonable
default for this argument.
\exitnote

\pnum
\returns
An iterator pointing immediately after the last character produced.
\end{itemdescr}

\rSec4[locale.time.put.virtuals]{\tcode{time_put} virtual functions}

\indexlibrary{\idxcode{time_put}!\idxcode{do_put}}%
\indexlibrary{\idxcode{do_put}!\idxcode{time_put}}%
\begin{itemdecl}
iter_type do_put(iter_type s, ios_base&, char_type fill, const tm* t,
                 char format, char modifier) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Formats the contents of the parameter \tcode{t}
into characters placed on the output sequence \tcode{s}.
Formatting is controlled by the parameters \tcode{format} and \tcode{modifier},
interpreted identically as the format specifiers in the string
argument to the standard library function
\indexlibrary{\idxcode{strftime}}%
\tcode{strftime()}\footnote{Interpretation of the \tcode{modifier}
argument is implementation-defined, but should follow POSIX
conventions.},
except that the sequence of characters produced for those specifiers
that are described as depending on the C locale are instead \impldef{formatted character
sequence generated by \tcode{time_put::do_put} in C
locale}.\footnote{Implementations are encouraged to refer to other standards
such as POSIX
for these definitions.}

\pnum
\returns
An iterator pointing immediately after the last character produced.
\enternote
The \tcode{fill} argument may be used in the implementation-defined
formats or by derivations. A space character is a reasonable
default for this argument.
\exitnote
\end{itemdescr}

\rSec3[locale.time.put.byname]{Class template \tcode{time_put_byname}}

\indexlibrary{\idxcode{time_put_byname}}%
\begin{codeblock}
namespace std {
  template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
  class time_put_byname : public time_put<charT, OutputIterator>
  {
  public:
    typedef charT          char_type;
    typedef OutputIterator iter_type;

    explicit time_put_byname(const char*, size_t refs = 0);
    explicit time_put_byname(const string&, size_t refs = 0);
  protected:
    ~time_put_byname();
  };
}
\end{codeblock}

\rSec2[category.monetary]{The monetary category}

\pnum
These templates handle monetary formats.
A template parameter indicates whether
local or international monetary formats are to be used.

\pnum
All specifications of member functions for
\tcode{money_put}
and
\tcode{money_get}
in the subclauses of~\ref{category.monetary} only apply to the
specializations required in Tables~\ref{tab:localization.category.facets}
and~\ref{tab:localization.required.specializations}~(\ref{locale.category}).
Their members use their
\tcode{ios_base\&},
\tcode{ios_base\,::\,io\-state\&},
and
\tcode{fill}
arguments as described in~(\ref{locale.categories}), and the
\tcode{moneypunct<>}
and
\tcode{ctype<>}
facets, to determine formatting details.

\rSec3[locale.money.get]{Class template \tcode{money_get}}

\indexlibrary{\idxcode{money_get}}%
\begin{codeblock}
namespace std {
  template <class charT,
    class InputIterator = istreambuf_iterator<charT> >
  class money_get : public locale::facet {
  public:
    typedef charT               char_type;
    typedef InputIterator       iter_type;
    typedef basic_string<charT> string_type;

    explicit money_get(size_t refs = 0);

    iter_type get(iter_type s, iter_type end, bool intl,
                  ios_base& f, ios_base::iostate& err,
                  long double& units) const;
    iter_type get(iter_type s, iter_type end, bool intl,
                  ios_base& f, ios_base::iostate& err,
                  string_type& digits) const;

    static locale::id id;

  protected:
    ~money_get();
    virtual iter_type do_get(iter_type, iter_type, bool, ios_base&,
                             ios_base::iostate& err, long double& units) const;
    virtual iter_type do_get(iter_type, iter_type, bool, ios_base&,
                             ios_base::iostate& err, string_type& digits) const;
  };
}
\end{codeblock}

\rSec4[locale.money.get.members]{\tcode{money_get} members}

\indexlibrary{\idxcode{money_get}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{money_get}}%
\begin{itemdecl}
iter_type get(iter_type s, iter_type end, bool intl,
              ios_base& f, ios_base::iostate& err,
              long double& quant) const;
iter_type get(s, iter_type end, bool intl, ios_base&f,
              ios_base::iostate& err, string_type& quant) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get(s, end, intl, f, err, quant)}
\end{itemdescr}

\rSec4[locale.money.get.virtuals]{\tcode{money_get} virtual functions}

\indexlibrary{\idxcode{money_get}!\idxcode{do_get}}%
\indexlibrary{\idxcode{do_get}!\idxcode{money_get}}%
\begin{itemdecl}
iter_type do_get(iter_type s, iter_type end, bool intl,
                 ios_base& str, ios_base::iostate& err,
                 long double& units) const;
iter_type do_get(iter_type s, iter_type end, bool intl,
                 ios_base& str, ios_base::iostate& err,
                 string_type& digits) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reads characters from
\tcode{s}
to parse and construct a monetary value according to the
format specified by a
\tcode{moneypunct<charT,Intl>}
facet reference
\tcode{mp}
and the character mapping specified by a
\tcode{ctype<charT>}
facet reference
\tcode{ct}
obtained from the locale returned by
\tcode{str.getloc()},
and
\tcode{str.flags()}.
If a valid sequence is recognized,
does not change \tcode{err};
otherwise, sets \tcode{err} to
\tcode{(err|str.failbit)},
or
\tcode{(err|str.failbit|str.eof\-bit)}
if no more characters are available,
and does not change \tcode{units} or \tcode{digits}.
Uses the pattern returned by
\tcode{mp.neg_format()}
to parse all values.
The result is returned as an integral value stored in
\tcode{units}
or as a sequence of digits possibly preceded by a minus sign
(as produced by
\tcode{ct.widen(c)}
where
\tcode{c}
is
\tcode{'-'}
or in the range from
\tcode{'0'}
through
\tcode{'9'},
inclusive)
stored in
\tcode{digits}.
\enterexample
The sequence
\tcode{\$1,056.23}
in a common United States locale would yield, for
\tcode{units},
\tcode{105623},
or, for
\tcode{digits},
\tcode{"105623"}.
\exitexample
If
\tcode{mp.grouping()}
indicates that no thousands separators are permitted,
any such characters are not read, and parsing is terminated at the point
where they first appear.
Otherwise, thousands separators are optional;
if present, they are checked for correct placement only after
all format components have been read.

\pnum
Where
\tcode{money_base::space}
or
\tcode{money_base::none}
appears as the last element in the format pattern,
no white space is consumed. Otherwise, where \tcode{money_base::space} appears in any of the
initial elements of the format pattern, at least one white space character is required. Where
\tcode{money_base::none} appears in any of the initial elements of the format pattern, white
space is allowed but not required.
If
\tcode{(str.flags() \& str.showbase)}
is false, the currency symbol is optional and is consumed only if
other characters are needed to complete the format;
otherwise, the currency symbol is required.

\pnum
If the first character (if any) in the string
\tcode{pos}
returned by
\tcode{mp.positive_sign()}
or the string
\tcode{neg}
returned by
\tcode{mp.neg\-a\-tive_sign()}
is recognized in the position indicated by
\tcode{sign}
in the format pattern, it is consumed and any remaining characters
in the string are required after all the other format components.
\enterexample
If
\tcode{showbase}
is off, then for a
\tcode{neg}
value of \tcode{"()"} and a currency symbol of \tcode{"L"},
in \tcode{"(100 L)"} the \tcode{"L"} is consumed;
but if
\tcode{neg}
is \tcode{"-"}, the \tcode{"L"} in \tcode{"-100 L"} is not consumed.
\exitexample
If
\tcode{pos}
or
\tcode{neg}
is empty, the sign component is optional, and if no sign is
detected, the result is given the sign that corresponds to the source
of the empty string.
Otherwise, the character in the indicated position must
match the first character of
\tcode{pos}
or
\tcode{neg},
and the result is given the corresponding sign.
If the first character of
\tcode{pos}
is equal to the first character of
\tcode{neg},
or if both strings are empty, the result is given a positive sign.

\pnum
Digits in the numeric monetary component are extracted and placed in
\tcode{digits},
or into a character buffer
\tcode{buf1}
for conversion to produce a value for
\tcode{units},
in the order in which they appear,
preceded by a minus sign if and only if the result is negative.
The value
\tcode{units}
is produced as if by\footnote{The semantics here are different from
\tcode{ct.narrow}.}

\begin{codeblock}
for (int i = 0; i < n; ++i)
  buf2[i] = src[find(atoms, atoms+sizeof(src), buf1[i]) - atoms];
buf2[n] = 0;
sscanf(buf2, "%Lf", &units);
\end{codeblock}

where
\tcode{n}
is the number of characters placed in
\tcode{buf1},
\tcode{buf2}
is a character buffer, and the values
\tcode{src}
and
\tcode{atoms}
are defined as if by

\begin{codeblock}
static const char src[] = "0123456789-";
charT atoms[sizeof(src)];
ct.widen(src, src + sizeof(src) - 1, atoms);
\end{codeblock}

\pnum
\returns
An iterator pointing immediately beyond the last character recognized
as part of a valid monetary quantity.
\end{itemdescr}

\rSec3[locale.money.put]{Class template \tcode{money_put}}

\indexlibrary{\idxcode{money_put}}%
\begin{codeblock}
namespace std {
  template <class charT,
    class OutputIterator = ostreambuf_iterator<charT> >
  class money_put : public locale::facet {
  public:
    typedef charT               char_type;
    typedef OutputIterator      iter_type;
    typedef basic_string<charT> string_type;

    explicit money_put(size_t refs = 0);

    iter_type put(iter_type s, bool intl, ios_base& f,
                  char_type fill, long double units) const;
    iter_type put(iter_type s, bool intl, ios_base& f,
                  char_type fill, const string_type& digits) const;

    static locale::id id;

  protected:
    ~money_put();
    virtual iter_type do_put(iter_type, bool, ios_base&, char_type fill,
                             long double units) const;
    virtual iter_type do_put(iter_type, bool, ios_base&, char_type fill,
                             const string_type& digits) const;
  };
}
\end{codeblock}

\rSec4[locale.money.put.members]{\tcode{money_put} members}

\indexlibrary{\idxcode{money_put}!\idxcode{put}}%
\indexlibrary{\idxcode{put}!\idxcode{money_put}}%
\begin{itemdecl}
iter_type put(iter_type s, bool intl, ios_base& f, char_type fill,
              long double quant) const;
iter_type put(iter_type s, bool intl, ios_base& f, char_type fill,
              const string_type& quant) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_put(s, intl, f, loc, quant)}
\end{itemdescr}

\rSec4[locale.money.put.virtuals]{\tcode{money_put} virtual functions}

\indexlibrary{\idxcode{money_put}!\idxcode{do_put}}%
\indexlibrary{\idxcode{do_put}!\idxcode{money_put}}%
\begin{itemdecl}
iter_type do_put(iter_type s, bool intl, ios_base& str,
                 char_type fill, long double units) const;
iter_type do_put(iter_type s, bool intl, ios_base& str,
                 char_type fill, const string_type& digits) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Writes characters to
\tcode{s}
according to the format specified by a
\tcode{moneypunct<charT,Intl>}
facet reference
\tcode{mp}
and the character mapping specified by a
\tcode{ctype<charT>}
facet reference
\tcode{ct}
obtained from the locale returned by
\tcode{str.getloc()},
and
\tcode{str.flags()}.
The argument
\tcode{units}
is transformed into a sequence of wide characters as if by

\begin{codeblock}
ct.widen(buf1, buf1 + sprintf(buf1, "%.0Lf", units), buf2)
\end{codeblock}

for character buffers
\tcode{buf1}
and
\tcode{buf2}.
If the first character in
\tcode{digits}
or
\tcode{buf2}
is equal to
\tcode{ct.widen('-')},
then the pattern used for formatting is the result of
\tcode{mp.neg_format()};
otherwise the pattern is the result of
\tcode{mp.pos_format()}.
Digit characters are written, interspersed with any thousands separators
and decimal point specified by the format, in the order they appear
(after the optional leading minus sign)
in
\tcode{digits}
or
\tcode{buf2}.
In
\tcode{digits},
only the optional leading minus sign and the immediately subsequent
digit characters (as classified according to
\tcode{ct})
are used; any trailing characters (including digits appearing
after a non-digit character) are ignored.
Calls
\tcode{str.width(0)}.

\pnum
\notes
% issues 22-021, 22-030, 22-034 from 97-0058/N1096, 97-0036/N1074
The currency symbol is generated if and only if
\tcode{(str.flags() \& str.showbase)}
is nonzero.
If the number of characters generated for the specified format is less than the value
returned by
\tcode{str.width()}
on entry to the function, then copies of
\tcode{fill}
are inserted as necessary to pad to the specified width.
For the value
\tcode{af}
equal to
\tcode{(str.flags() \& str.adjustfield)},
if
\tcode{(af == str.internal)}
is true, the fill characters are placed where
\tcode{none}
or
\tcode{space}
appears in the formatting pattern; otherwise if
\tcode{(af == str.left)}
is true, they are placed after the other characters;
otherwise, they are placed before the other characters.
\enternote
It is possible, with some combinations of format patterns and flag values,
to produce output that cannot be parsed using
\tcode{num_get<>::get}.
\exitnote

\pnum
\returns
An iterator pointing immediately after the last character produced.
\end{itemdescr}

\rSec3[locale.moneypunct]{Class template \tcode{moneypunct}}

\indexlibrary{\idxcode{moneypunct}}%
\begin{codeblock}
namespace std {
  class money_base {
  public:
    enum part { none, space, symbol, sign, value };
    struct pattern { char field[4]; };
  };

  template <class charT, bool International = false>
  class moneypunct : public locale::facet, public money_base {
  public:
    typedef charT char_type;
    typedef basic_string<charT> string_type;

    explicit moneypunct(size_t refs = 0);

    charT        decimal_point() const;
    charT        thousands_sep() const;
    string       grouping()      const;
    string_type  curr_symbol()   const;
    string_type  positive_sign() const;
    string_type  negative_sign() const;
    int          frac_digits()   const;
    pattern      pos_format()    const;
    pattern      neg_format()    const;

    static locale::id id;
    static const bool intl = International;

  protected:
    ~moneypunct();
    virtual charT        do_decimal_point() const;
    virtual charT        do_thousands_sep() const;
    virtual string       do_grouping()      const;
    virtual string_type  do_curr_symbol()   const;
    virtual string_type  do_positive_sign() const;
    virtual string_type  do_negative_sign() const;
    virtual int          do_frac_digits()   const;
    virtual pattern      do_pos_format()    const;
    virtual pattern      do_neg_format()    const;
  };
}
\end{codeblock}

\pnum
The
\tcode{moneypunct<>}
facet defines monetary formatting parameters used by
\tcode{money_get<>}
and
\tcode{money_put<>}.
A monetary format is a sequence of four components,
specified by a
\tcode{pattern}
value
\tcode{p},
such that the
\tcode{part}
value
\tcode{static_cast<part>(p.field[i])}
determines the
\tcode{i}th
component of the format\footnote{An array of
\tcode{char},
rather than an array of
\tcode{part},
is specified for
\tcode{pattern::field}
purely for efficiency.}
In the
\tcode{field}
member of a
\tcode{pattern}
object, each value
\tcode{symbol},
\tcode{sign},
\tcode{value},
and either
\tcode{space}
or
\tcode{none}
appears exactly once.
The value
\tcode{none},
if present, is not first;
the value
\tcode{space},
if present, is neither first nor last.

\pnum
Where
\tcode{none}
or
\tcode{space}
appears, white space is permitted in the format,
except where
\tcode{none}
appears at the end, in which case no white space is permitted.
The value
\tcode{space}
indicates that at least one space is required at that position.
Where
\tcode{symbol}
appears, the sequence of characters returned by
\tcode{curr_symbol()}
is permitted, and can be required.
Where
\tcode{sign}
appears, the first (if any) of the sequence of characters returned by
\tcode{positive_sign()}
or
\tcode{negative_sign()}
(respectively as the monetary value is non-negative or negative) is required.
Any remaining characters of the sign sequence are required after all
other format components.
Where
\tcode{value}
appears, the absolute numeric monetary value is required.

\pnum
The format of the numeric monetary value is a decimal number:

\begin{codeblock}
value ::= units [ decimal-point [ digits ]] |
  decimal-point digits
\end{codeblock}

if
\tcode{frac_digits()}
returns a positive value, or

\begin{codeblock}
value ::= units
\end{codeblock}

otherwise.
The symbol
\tcode{decimal-point}
indicates the character returned by
\tcode{decimal_point()}.
The other symbols are defined as follows:

\begin{codeblock}
units ::= digits [ thousands-sep units ]
digits ::= adigit [ digits ]
\end{codeblock}

In the syntax specification, the symbol
\tcode{adigit}
is any of the values
\tcode{ct.widen(c)}
for
\tcode{c}
in the range
\tcode{'0'}
through
\tcode{'9'},
inclusive, and
\tcode{ct}
is a reference of type
\tcode{const ctype<charT>\&}
obtained as described in the definitions of
\tcode{money_get<>}
and
\tcode{money_put<>}.
The symbol
\tcode{thousands-sep}
is the character returned by
\tcode{thousands_sep()}.
The space character used is the value
\tcode{ct.widen(' ')}.
White space characters are those characters
\tcode{c}
for which
\tcode{ci.is(space,c)}
returns
\tcode{true}.
The number of digits required after the decimal point (if any)
is exactly the value returned by
\tcode{frac_digits()}.

\pnum
The placement of thousands-separator characters (if any)
is determined by the value returned by
\tcode{grouping()},
defined identically as the member
\tcode{numpunct<>::do_grouping()}.

\rSec4[locale.moneypunct.members]{\tcode{moneypunct} members}

\indexlibrary{\idxcode{moneypunct}!\idxcode{decimal_point}}%
\indexlibrary{\idxcode{decimal_point}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{thousands_sep}}%
\indexlibrary{\idxcode{thousands_sep}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{grouping}}%
\indexlibrary{\idxcode{grouping}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{curr_symbol}}%
\indexlibrary{\idxcode{curr_symbol}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{positive_sign}}%
\indexlibrary{\idxcode{positive_sign}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{negative_sign}}%
\indexlibrary{\idxcode{negative_sign}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{frac_digits}}%
\indexlibrary{\idxcode{frac_digits}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{positive_sign}}%
\indexlibrary{\idxcode{positive_sign}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{negative_sign}}%
\indexlibrary{\idxcode{negative_sign}!\idxcode{moneypunct}}%
\begin{codeblock}
charT        decimal_point() const;
charT        thousands_sep() const;
string       grouping()      const;
string_type  curr_symbol()   const;
string_type  positive_sign() const;
string_type  negative_sign() const;
int          frac_digits()   const;
pattern      pos_format()    const;
pattern      neg_format()    const;
\end{codeblock}

\pnum
Each of these functions \tcode{F}
returns the result of calling the corresponding
virtual member function
\tcode{do_}\textbf\textit{{F}}\tcode{()}.

\rSec4[locale.moneypunct.virtuals]{\tcode{moneypunct} virtual functions}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_decimal_point}}%
\indexlibrary{\idxcode{do_decimal_point}!\idxcode{moneypunct}}%
\begin{itemdecl}
charT do_decimal_point() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The radix separator to use in case
\tcode{do_frac_digits()}
is greater than zero.\footnote{In common U.S. locales this is
\tcode{'.'}.}
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_thousands_sep}}%
\indexlibrary{\idxcode{do_thousands_sep}!\idxcode{moneypunct}}%
\begin{itemdecl}
charT do_thousands_sep() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The digit group separator to use in case
\tcode{do_grouping()}
specifies a digit grouping pattern.\footnote{In common U.S. locales this is
\tcode{','}.}
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_grouping}}%
\indexlibrary{\idxcode{do_grouping}!\idxcode{moneypunct}}%
\begin{itemdecl}
string do_grouping() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pattern defined identically as, but not necessarily equal to, the result of
\tcode{numpunct<charT>::\brk{}do_grouping()}.\footnote{To specify grouping by 3s,
the value is \tcode{"\textbackslash003"}
\textit{not}
\tcode{"3"}.}
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_curr_symbol}}%
\indexlibrary{\idxcode{do_curr_symbol}!\idxcode{moneypunct}}%
\begin{itemdecl}
string_type do_curr_symbol() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A string to use as the currency identifier symbol.\footnote{For international
specializations (second template parameter
\tcode{true})
this is typically four characters long, usually three letters and a space.}
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_positive_sign}}%
\indexlibrary{\idxcode{do_positive_sign}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{do_negative_sign}}%
\indexlibrary{\idxcode{do_negative_sign}!\idxcode{moneypunct}}%
\begin{itemdecl}
string_type do_positive_sign() const;
string_type do_negative_sign() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_positive_sign()}
returns the string to use to indicate a
positive monetary value;\footnote{This is usually the empty string.}
\tcode{do_negative_sign()}
returns the string to use to indicate a negative value.
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_frac_digits}}%
\indexlibrary{\idxcode{do_frac_digits}!\idxcode{moneypunct}}%
\begin{itemdecl}
int do_frac_digits() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The number of digits after the decimal radix separator, if any.\footnote{In
common U.S. locales, this is 2.}
\end{itemdescr}

\indexlibrary{\idxcode{moneypunct}!\idxcode{do_pos_format}}%
\indexlibrary{\idxcode{do_pos_format}!\idxcode{moneypunct}}%
\indexlibrary{\idxcode{moneypunct}!\idxcode{do_neg_format}}%
\indexlibrary{\idxcode{do_neg_format}!\idxcode{moneypunct}}%
\begin{itemdecl}
pattern do_pos_format() const;
pattern do_neg_format() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The specializations required in Table~\ref{tab:localization.required.specializations}~(\ref{locale.category}), namely
\tcode{moneypunct<char>},
\tcode{moneypunct<\brk{}wchar_t>},
\tcode{moneypunct<char,true>},
and
\tcode{moneypunct<wchar_t,true>},
return an object of type
\tcode{pattern}
initialized to
\tcode{\{ symbol, sign, none, value \}}.\footnote{Note that the international
symbol returned by
\tcode{do_curr_sym()}
usually contains a space, itself;
for example, \tcode{"USD "}.}
\end{itemdescr}

\rSec3[locale.moneypunct.byname]{Class template \tcode{moneypunct_byname}}

\indexlibrary{\idxcode{moneypunct_byname}}%
\begin{codeblock}
namespace std {
  template <class charT, bool Intl = false>
  class moneypunct_byname : public moneypunct<charT, Intl> {
  public:
    typedef money_base::pattern pattern;
    typedef basic_string<charT> string_type;

    explicit moneypunct_byname(const char*, size_t refs = 0);
    explicit moneypunct_byname(const string&, size_t refs = 0);
  protected:
    ~moneypunct_byname();
  };
}
\end{codeblock}

\rSec2[category.messages]{The message retrieval category}

\pnum
Class
\tcode{messages<charT>}
implements retrieval of strings from message catalogs.

\rSec3[locale.messages]{Class template \tcode{messages}}

\indexlibrary{\idxcode{messages}}%
\begin{codeblock}
namespace std {
  class messages_base {
  public:
    typedef @\textit{unspecified signed integer type}@ catalog;
  };

  template <class charT>
  class messages : public locale::facet, public messages_base {
  public:
    typedef charT char_type;
    typedef basic_string<charT> string_type;

    explicit messages(size_t refs = 0);

    catalog open(const basic_string<char>& fn, const locale&) const;
    string_type get(catalog c, int set, int msgid,
                     const string_type& dfault) const;
    void close(catalog c) const;

    static locale::id id;

  protected:
    ~messages();
    virtual catalog do_open(const basic_string<char>&, const locale&) const;
    virtual string_type do_get(catalog, int set, int msgid,
                               const string_type& dfault) const;
    virtual void do_close(catalog) const;
  };
}
\end{codeblock}

\pnum
Values of type
\tcode{messages_base::catalog}
usable as arguments to members
\tcode{get}
and
\tcode{close}
can be obtained only by calling member
\tcode{open}.

\rSec4[locale.messages.members]{\tcode{messages} members}

\indexlibrary{\idxcode{messages}!\idxcode{open}}%
\indexlibrary{\idxcode{open}!\idxcode{messages}}%
\begin{itemdecl}
catalog open(const basic_string<char>& name, const locale& loc) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_open(name, loc)}.
\end{itemdescr}

\indexlibrary{\idxcode{messages}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{messages}}%
\begin{itemdecl}
string_type get(catalog cat, int set, int msgid,
                const string_type& dfault) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{do_get(cat, set, msgid, dfault)}.
\end{itemdescr}

\indexlibrary{\idxcode{messages}!\idxcode{close}}%
\indexlibrary{\idxcode{close}!\idxcode{messages}}%
\begin{itemdecl}
void  close(catalog cat) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{do_close(cat)}.
\end{itemdescr}

\rSec4[locale.messages.virtuals]{\tcode{messages} virtual functions}

\indexlibrary{\idxcode{messages}!\idxcode{do_open}}%
\indexlibrary{\idxcode{do_open}!\idxcode{messages}}%
\begin{itemdecl}
catalog do_open(const basic_string<char>& name,
                const locale& loc) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A value that may be passed to
\tcode{get()}
to retrieve a message from the message catalog identified by the string
\tcode{name} according to an \impldef{mapping from name to catalog when calling
\tcode{messages\colcol{}do_open}} mapping.
The result can be used until it is passed to
\tcode{close()}.

\pnum
Returns a value less than 0 if no such catalog can be opened.

\pnum
\notes
The locale argument \tcode{loc}
is used for character set code conversion when retrieving
messages, if needed.
\end{itemdescr}

\indexlibrary{\idxcode{messages}!\idxcode{do_get}}%
\indexlibrary{\idxcode{do_get}!\idxcode{messages}}%
\begin{itemdecl}
string_type do_get(catalog cat, int set, int msgid,
              const string_type& dfault) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{cat} shall be a catalog obtained from
\tcode{open()}
and not yet closed.

\pnum
\returns
A message identified by arguments \tcode{set}, \tcode{msgid}, and \tcode{dfault}, according
to an \impldef{mapping to message when calling \tcode{messages::do_get}} mapping. If no
such message can be found, returns \tcode{dfault}.
\end{itemdescr}

\indexlibrary{\idxcode{message}!\idxcode{do_close}}%
\indexlibrary{\idxcode{do_close}!\idxcode{message}}%
\begin{itemdecl}
void do_close(catalog cat) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{cat} shall be a catalog obtained from
\tcode{open()}
and not yet closed.

\pnum
\effects
Releases unspecified resources associated with  \tcode{cat}.

\pnum
\notes
The limit on such resources, if any, is implementation-defined.
\end{itemdescr}

\rSec3[locale.messages.byname]{Class template \tcode{messages_byname}}

\indexlibrary{\idxcode{messages_byname}}%
\begin{codeblock}
namespace std {
  template <class charT>
  class messages_byname : public messages<charT> {
  public:
    typedef messages_base::catalog catalog;
    typedef basic_string<charT>    string_type;

    explicit messages_byname(const char*, size_t refs = 0);
    explicit messages_byname(const string&, size_t refs = 0);
  protected:
    ~messages_byname();
  };
}
\end{codeblock}

\rSec2[facets.examples]{Program-defined facets}

\pnum
A \Cpp program may define facets to be added to a locale and used identically as
the built-in facets.
To create a new facet interface, \Cpp programs simply derive from
\tcode{locale::facet}
a class containing a static member:
\tcode{static locale::id id}.

\pnum
\enternote
The locale member function templates verify its type and storage class.
\exitnote

\pnum
\enterexample
Traditional global localization is still easy:

\begin{codeblock}
#include <iostream>
#include <locale>
int main(int argc, char** argv) {
  using namespace std;
  locale::global(locale(""));           // set the global locale
                                        // imbue it on all the std streams
  cin.imbue(locale());
  cout.imbue(locale());
  cerr.imbue(locale());
  wcin.imbue(locale());
  wcout.imbue(locale());
  wcerr.imbue(locale());

  return MyObject(argc, argv).doit();
}
\end{codeblock}
\exitexample

\pnum
\enterexample
Greater flexibility is possible:

\begin{codeblock}
#include <iostream>
#include <locale>
int main() {
  using namespace std;
  cin.imbue(locale(""));        // the user's preferred locale
  cout.imbue(locale::classic());
  double f;
  while (cin >> f) cout << f << endl;
  return (cin.fail() != 0);
}
\end{codeblock}

In a European locale, with input
\tcode{3.456,78},
output is
\tcode{3456.78}.
\exitexample

\pnum
This can be important even for simple programs, which may need to
write a data file in a fixed format, regardless of a user's preference.

\pnum
\enterexample
Here is an example of the use of locales in a library interface.

\begin{codeblock}
// file: \tcode{Date.h}
#include <iosfwd>
#include <string>
#include <locale>

class Date {
public:
  Date(unsigned day, unsigned month, unsigned year);
  std::string asString(const std::locale& = std::locale());
};

std::istream& operator>>(std::istream& s, Date& d);
std::ostream& operator<<(std::ostream& s, Date d);
\end{codeblock}

\pnum
This example illustrates two architectural uses of class
\tcode{locale}.

\pnum
The first is as a default argument in
\tcode{Date::asString()},
where the
default is the global (presumably user-preferred) locale.

\pnum
The second is in the operators
\tcode{\shl}
and
\tcode{\shr},
where a locale ``hitchhikes''
on another object, in this case a stream, to the point where it
is needed.

\begin{codeblock}
// file: \tcode{Date.C}
#include "Date"                 // includes \tcode{<ctime>}
#include <sstream>
std::string Date::asString(const std::locale& l) {
  using namespace std;
  ostringstream s; s.imbue(l);
  s << *this; return s.str();
}

std::istream& operator>>(std::istream& s, Date& d) {
  using namespace std;
  istream::sentry cerberos(s);
  if (cerberos) {
    ios_base::iostate err = goodbit;
    struct tm t;
    use_facet< time_get<char> >(s.getloc()).get_date(s, 0, s, err, &t);
    if (!err) d = Date(t.tm_day, t.tm_mon + 1, t.tm_year + 1900);
    s.setstate(err);
  }
  return s;
}
\end{codeblock}
\exitexample

\pnum
A locale object may be extended with a new facet simply by constructing
it with an instance of a class derived from
\tcode{locale::facet}.
The only member a \Cpp program must define is the static member
\tcode{id},
which identifies your class interface as a new facet.

\pnum
\enterexample
Classifying Japanese characters:

\begin{codeblock}
// file: \tcode{<jctype>}
#include <locale>
namespace My {
  using namespace std;
  class JCtype : public locale::facet {
  public:
    static locale::id id;       // required for use as a new locale facet
    bool is_kanji (wchar_t c) const;
    JCtype() { }
  protected:
    ~JCtype() { }
  };
}

// file: \tcode{filt.C}
#include <iostream>
#include <locale>
#include "jctype"               // above
std::locale::id My::JCtype::id; // the static \tcode{JCtype} member declared above.

int main() {
  using namespace std;
  typedef ctype<wchar_t> wctype;
  locale loc(locale(""),        // the user's preferred locale ...
         new My::JCtype);       // and a new feature ...
  wchar_t c = use_facet<wctype>(loc).widen('!');
  if (!use_facet<My::JCtype>(loc).is_kanji(c))
    cout << "no it isn't!" << endl;
  return 0;
}
\end{codeblock}

\pnum
The new facet is used exactly like the built-in facets.
\exitexample

\pnum
\enterexample
Replacing an existing facet is even easier.
The code does not define a member
\tcode{id}
because it is reusing the
\tcode{numpunct<charT>}
facet interface:

\begin{codeblock}
// file: \tcode{my_bool.C}
#include <iostream>
#include <locale>
#include <string>
namespace My {
  using namespace std;
  typedef numpunct_byname<char> cnumpunct;
  class BoolNames : public cnumpunct {
  protected:
    string do_truename()  const { return "Oui Oui!"; }
    string do_falsename() const { return "Mais Non!"; }
    ~BoolNames() { }
  public:
    BoolNames(const char* name) : cnumpunct(name) { }
  };
}

int main(int argc, char** argv) {
  using namespace std;
  // make the user's preferred locale, except for...
  locale loc(locale(""), new My::BoolNames(""));
  cout.imbue(loc);
  cout << boolalpha << "Any arguments today? " << (argc > 1) << endl;
  return 0;
}
\end{codeblock}
\exitexample

\rSec1[locale.stdcvt]{Standard code conversion facets}

\pnum
The header \tcode{<codecvt>} provides code conversion facets for various character encodings.

\pnum
\synopsis{Header \tcode{<codecvt>} synopsis}

\indexlibrary{\idxcode{codecvt}}%
\begin{codeblock}
namespace std {
  enum codecvt_mode {
    consume_header = 4,
    generate_header = 2,
    little_endian = 1
  };

  template<class Elem, unsigned long Maxcode = 0x10ffff,
    codecvt_mode Mode = (codecvt_mode)0>
  class codecvt_utf8
    : public codecvt<Elem, char, mbstate_t> {
  public:
    explicit codecvt_utf8(size_t refs = 0);
    ~codecvt_utf8();
  };

  template<class Elem, unsigned long Maxcode = 0x10ffff,
    codecvt_mode Mode = (codecvt_mode)0>
  class codecvt_utf16
    : public codecvt<Elem, char, mbstate_t> {
  public:
    explicit codecvt_utf16(size_t refs = 0);
    ~codecvt_utf16();
  };

  template<class Elem, unsigned long Maxcode = 0x10ffff,
    codecvt_mode Mode = (codecvt_mode)0>
  class codecvt_utf8_utf16
    : public codecvt<Elem, char, mbstate_t> {
  public:
    explicit codecvt_utf8_utf16(size_t refs = 0);
    ~codecvt_utf8_utf16();
  };
}
\end{codeblock}

\pnum
For each of the three code conversion facets \tcode{codecvt_utf8}, \tcode{codecvt_utf16}, and \tcode{codecvt_utf8_utf16}:

\begin{itemize}
\item \tcode{Elem} is the wide-character type, such as \tcode{wchar_t}, \tcode{char16_t}, or \tcode{char32_t}.
\item \tcode{Maxcode} is the largest wide-character code that the facet will read or write without reporting a conversion error.
\item If \tcode{(Mode \& consume_header)}, the facet shall consume an initial header sequence, if present, when reading a multibyte sequence to determine the endianness of the subsequent multibyte sequence to be read.
\item If \tcode{(Mode \& generate_header)}, the facet shall generate an initial header sequence when writing a multibyte sequence to advertise the endianness of the subsequent multibyte sequence to be written.
\item If \tcode{(Mode \& little_endian)}, the facet shall generate a multibyte sequence in little-endian order, as opposed to the default big-endian order.
\end{itemize}

\pnum
For the facet \tcode{codecvt_utf8}:

\begin{itemize}
\item The facet shall convert between UTF-8 multibyte sequences and UCS2 or UCS4 (depending on the size of \tcode{Elem}) within the program.
\item Endianness shall not affect how multibyte sequences are read or written.
\item The multibyte sequences may be written as either a text or a binary file.
\end{itemize}

\pnum
For the facet \tcode{codecvt_utf16}:

\begin{itemize}
\item The facet shall convert between UTF-16 multibyte sequences and UCS2 or UCS4 (depending on the size of \tcode{Elem}) within the program.
\item Multibyte sequences shall be read or written according to the \tcode{Mode} flag, as set out above.
\item The multibyte sequences may be written only as a binary file. Attempting to write to a text file produces undefined behavior.
\end{itemize}

\pnum
For the facet \tcode{codecvt_utf8_utf16}:

\begin{itemize}
\item The facet shall convert between UTF-8 multibyte sequences and UTF-16 (one or two 16-bit codes) within the program.
\item Endianness shall not affect how multibyte sequences are read or written.
\item The multibyte sequences may be written as either a text or a binary file.
\end{itemize}

\xref ISO/IEC 10646-1:1993.

\rSec1[c.locales]{C library locales}

\pnum
Table~\ref{tab:localization.hdr.clocale} describes header
\tcode{<clocale>}.

\begin{libsyntab4}{clocale}{tab:localization.hdr.clocale}
\macros             &
 \tcode{LC_ALL}     &
 \tcode{LC_COLLATE} &
 \tcode{LC_CTYPE}   \\
                    &
 \tcode{LC_MONETARY}    &
 \tcode{LC_NUMERIC} &
 \tcode{LC_TIME}    \\
                    &
 \tcode{NULL}       &
                    &
                    \\ \rowsep
\struct             &
 \tcode{lconv}      &
                    &
                    \\ \rowsep
\functions          &
 \tcode{localeconv} &
 \tcode{setlocale}  &
                    \\
\end{libsyntab4}

\pnum
The contents are the same as the Standard C library header
\tcode{<locale.h>}.

\pnum
Calls to the function \tcode{setlocale} may introduce a data
race~(\ref{res.on.data.races}) with other calls to \tcode{setlocale} or with calls to
the functions listed in Table~\ref{tab:setlocale.data.races}.

\begin{floattable}
{Potential \tcode{setlocale} data races}
{tab:setlocale.data.races}
{lllll}
\topline

\tcode{fprintf}     &
\tcode{isprint}     &
\tcode{iswdigit}    &
\tcode{localeconv}  &
\tcode{tolower}     \\

\tcode{fscanf}      &
\tcode{ispunct}     &
\tcode{iswgraph}    &
\tcode{mblen}       &
\tcode{toupper}     \\

\tcode{isalnum}     &
\tcode{isspace}     &
\tcode{iswlower}    &
\tcode{mbstowcs}    &
\tcode{towlower}    \\

\tcode{isalpha}     &
\tcode{isupper}     &
\tcode{iswprint}    &
\tcode{mbtowc}      &
\tcode{towupper}    \\

\tcode{isblank}     &
\tcode{iswalnum}    &
\tcode{iswpunct}    &
\tcode{setlocale}   &
\tcode{wcscoll}     \\

\tcode{iscntrl}     &
\tcode{iswalpha}    &
\tcode{iswspace}    &
\tcode{strcoll}     &
\tcode{wcstod}      \\

\tcode{isdigit}     &
\tcode{iswblank}    &
\tcode{iswupper}    &
\tcode{strerror}    &
\tcode{wcstombs}    \\

\tcode{isgraph}     &
\tcode{iswcntrl}    &
\tcode{iswxdigit}   &
\tcode{strtod}      &
\tcode{wcsxfrm}     \\

\tcode{islower}     &
\tcode{iswctype}    &
\tcode{isxdigit}    &
\tcode{strxfrm}     &
\tcode{wctomb}      \\



\end{floattable}

\xref
ISO C Clause 7.4.