%!TEX root = std.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 \tref{localization.summary}.

\begin{libsumtab}{Localization library summary}{localization.summary}

\ref{locales} & Locales & \tcode{<locale>} \\

\ref{locale.categories} & Standard \tcode{locale} categories & \\ \rowsep

\ref{c.locales} & C library locales & \tcode{<clocale>} \\ \rowsep

\ref{text.encoding} & Text encodings identification & \tcode{<text_encoding>} \\

\end{libsumtab}

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

\indexheader{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);

// \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 \libheader{locale}

defines classes and declares functions

that encapsulate and manipulate the information peculiar to a locale.

\begin{footnote}

In this subclause, the type name \tcode{tm}

is an incomplete type that is defined in \libheaderref{ctime}.

\end{footnote}

\rSec1[locales]{Locales}

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

\rSec3[locale.general]{General}

\begin{codeblock}

namespace std {

class locale {

public:

// \ref{locale.types}, types

// \ref{locale.facet}, class \tcode{locale::facet}

class facet;

// \ref{locale.id}, class \tcode{locale::id}

class id;

// \ref{locale.category}, type \tcode{locale::category}

using category = int;

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;

// \ref{locale.cons}, 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;

// \ref{locale.members}, locale operations

template<class Facet> locale combine(const locale& other) const;

string name() const;

text_encoding encoding() 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;

// \ref{locale.statics}, 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

\begin{example}

An iostream \tcode{operator<<} can be implemented as:

\begin{footnote}

Note that in the call to \tcode{put},

the stream is implicitly converted

to an \tcode{ostreambuf_iterator<charT, traits>}.

\end{footnote}

\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) {

tm tmbuf; d.extract(tmbuf);

bool failed =

use_facet<time_put<charT, ostreambuf_iterator<charT, traits>>>(

s.getloc()).put(s, s, s.fill(), &tmbuf, 'x').failed();

if (failed)

s.setstate(s.badbit); // can throw

}

return s;

}

\end{codeblock}

\end{example}

\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.

\pnum

\begin{note}

All locale semantics are accessed via

\tcode{use_facet<>} and \tcode{has_facet<>},

except that:

\begin{itemize}

\item

A member operator template

\begin{codeblock}

operator()(const basic_string<C, T, A>&, const basic_string<C, T, A>&)

\end{codeblock}

is provided so that a locale can 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\iref{istream.formatted}.)

\end{itemize}

\end{note}

\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\iref{res.on.data.races}.

\rSec3[locale.types]{Types}

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

\indexlibrarymember{locale}{category}%

\begin{itemdecl}

using category = int;

\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 \tref{locale.category.facets}.

\begin{floattable}{Locale category facets}{locale.category.facets}

{ll}

\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, char8_t, mbstate_t>} \\

& \tcode{codecvt<char32_t, char8_t, 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 \tref{locale.category.facets},

\tcode{has_facet<Facet>(loc)} is \tcode{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 \tref{locale.spec}.

\begin{floattable}{Required specializations}{locale.spec}

{ll}

\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, char8_t, mbstate_t>} \\

& \tcode{codecvt_byname<char32_t, char8_t, 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 parameter with name \tcode{InputIterator} or \tcode{OutputIterator}

indicates the set of all possible specializations on parameters that meet the

\oldconcept{InputIterator} requirements or

\oldconcept{OutputIterator} requirements,

respectively\iref{iterator.requirements}.

A template parameter with name \tcode{C} represents

the set of types containing \keyword{char}, \keyword{wchar_t}, and any other

\impldef{set of character types

that iostreams templates can be instantiated for}

character types

that meet the requirements for a character

on which any of the iostream components can be instantiated.

A template parameter with name \tcode{International}

represents the set of all possible specializations on a bool parameter.

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

\indexlibrarymember{locale}{facet}%

\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

Class \tcode{facet} is the base class for locale feature sets.

A class is a \defn{facet}

if it is publicly derived from another facet, or

if it is a class derived from \tcode{locale::facet} and

contains a publicly accessible declaration as follows:

\begin{footnote}

This is a complete list of requirements; there are no other requirements.

Thus, a facet class need not have a public

copy constructor, assignment, default constructor, destructor, etc.

\end{footnote}

\begin{codeblock}

static ::std::locale::id id;

\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 \tcode{Facet} template parameter.

\pnum

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

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.

\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 implicit 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}}

\indexlibrarymember{locale}{id}%

\begin{codeblock}

namespace std {

class locale::id {

public:

id();

void operator=(const id&) = delete;

id(const id&) = delete;

};

}

\end{codeblock}

\pnum

The class \tcode{locale::id} provides

identification of a locale facet interface,

used as an index for lookup and to encapsulate initialization.

\pnum

\begin{note}

Because facets are used by iostreams,

potentially while static constructors are running,

their initialization cannot depend on programmed static initialization.

One initialization strategy is for \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\iref{basic.start.static}.

\end{note}

\rSec3[locale.cons]{Constructors and destructor}

\indexlibraryctor{locale}%

\begin{itemdecl}

locale() noexcept;

\end{itemdecl}

\begin{itemdescr}

\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()}.

\begin{note}

This constructor yields a copy of the current global locale.

It is commonly used as a default argument for

function parameters of type \tcode{const locale\&}.

\end{note}

\end{itemdescr}

\indexlibraryctor{locale}%

\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

\remarks

The set of valid string argument values is

\tcode{"C"}, \tcode{""}, and any \impldef{locale names} values.

\end{itemdescr}

\indexlibraryctor{locale}%

\begin{itemdecl}

explicit locale(const string& std_name);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to \tcode{locale(std_name.c_str())}.

\end{itemdescr}

\indexlibraryctor{locale}%

\begin{itemdecl}

locale(const locale& other, const char* std_name, category cats);

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{cats} is a valid \tcode{category} value\iref{locale.category}.

\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 second argument is not valid, or is null.

\pnum

\remarks

The locale has a name if and only if \tcode{other} has a name.

\end{itemdescr}

\indexlibraryctor{locale}%

\begin{itemdecl}

locale(const locale& other, const string& std_name, category cats);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to \tcode{locale(other, std_name.c_str(), cats)}.

\end{itemdescr}

\indexlibraryctor{locale}%

\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

\remarks

If \tcode{f} is null,

the resulting locale has the same name as \tcode{other}.

Otherwise, the resulting locale has no name.

\end{itemdescr}

\indexlibraryctor{locale}%

\begin{itemdecl}

locale(const locale& other, const locale& one, category cats);

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{cats} is a valid \tcode{category} value.

\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

\remarks

If \tcode{cats} is equal to \tcode{locale::none},

the resulting locale has a name if and only if the first argument has a name.

Otherwise, the resulting locale has a name if and only if

the first two arguments both have names.

\end{itemdescr}

\indexlibrarymember{operator=}{locale}%

\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}

\rSec3[locale.members]{Members}

\indexlibrarymember{locale}{combine}%

\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 \tcode{false}.

\pnum

\remarks

The resulting locale has no name.

\end{itemdescr}

\indexlibrarymember{locale}{name}%

\begin{itemdecl}

string name() const;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

The name of \tcode{*this}, if it has one;

otherwise, the string \tcode{"*"}.

\end{itemdescr}

\indexlibrarymember{locale}{encoding}%

\begin{itemdecl}

text_encoding encoding() const;

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

\tcode{CHAR_BIT == 8} is \tcode{true}.

\pnum

\returns

A \tcode{text_encoding} object representing

the implementation-defined encoding scheme

associated with the locale \tcode{*this}.

\end{itemdescr}

\rSec3[locale.operators]{Operators}

\indexlibrarymember{locale}{operator==}%

\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}

\indexlibrarymember{locale}{operator()}%

\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

\returns

\begin{codeblock}

use_facet<collate<charT>>(*this).compare(s1.data(), s1.data() + s1.size(),

s2.data(), s2.data() + s2.size()) < 0

\end{codeblock}

\pnum

\remarks

This member operator template (and therefore \tcode{locale} itself)

meets the requirements for

a comparator predicate template argument\iref{algorithms} applied to strings.

\pnum

\begin{example}

A vector of strings \tcode{v}

can be collated according to collation rules in locale \tcode{loc}

simply by\iref{alg.sort,vector}:

\begin{codeblock}

std::sort(v.begin(), v.end(), loc);

\end{codeblock}

\end{example}

\end{itemdescr}

\rSec3[locale.statics]{Static members}

\indexlibrarymember{locale}{global}%

\begin{itemdecl}

static locale global(const locale& loc);

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Sets the global locale to its argument.

Causes future calls to the constructor \tcode{locale()}

to return a copy of the argument.

If the argument has a name, does

\begin{codeblock}

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}}.

\pnum

\returns

The previous value of \tcode{locale()}.

\pnum

\remarks

No library function other than \tcode{locale::global()}

affects the value returned by \tcode{locale()}.

\begin{note}

See~\ref{c.locales} for data race considerations

when \tcode{setlocale} is invoked.

\end{note}

\end{itemdescr}

\indexlibrarymember{locale}{classic}%

\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

\remarks

This locale, its facets, and their member functions, do not change with time.

\end{itemdescr}

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

\indexlibrarymember{locale}{use_facet}%

\begin{itemdecl}

template<class Facet> const Facet& use_facet(const locale& loc);

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

\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

\remarks

The reference returned remains valid

at least as long as any copy of \tcode{loc} exists.

\end{itemdescr}

\indexlibrarymember{locale}{has_facet}%

\begin{itemdecl}

template<class Facet> bool has_facet(const locale& loc) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{true} if the facet requested is present in \tcode{loc};

otherwise \tcode{false}.

\end{itemdescr}

\rSec2[locale.convenience]{Convenience interfaces}

\rSec3[classification]{Character classification}

\indexlibraryglobal{isspace}%

\indexlibraryglobal{isprint}%

\indexlibraryglobal{iscntrl}%

\indexlibraryglobal{isupper}%

\indexlibraryglobal{islower}%

\indexlibraryglobal{isalpha}%

\indexlibraryglobal{isdigit}%

\indexlibraryglobal{ispunct}%

\indexlibraryglobal{isxdigit}%

\indexlibraryglobal{isalnum}%

\indexlibraryglobal{isgraph}%

\indexlibraryglobal{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\placeholder{F}}

returns the result of the expression:

\begin{codeblock}

use_facet<ctype<charT>>(loc).is(ctype_base::@\placeholder{F}@, c)

\end{codeblock}

where \tcode{\placeholder{F}} is the \tcode{ctype_base::mask} value

corresponding to that function\iref{category.ctype}.

\begin{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}.

\end{footnote}

\rSec3[conversions.character]{Character conversions}

\indexlibraryglobal{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}

\indexlibraryglobal{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}

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

\rSec2[locale.categories.general]{General}

\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{<<} and \tcode{>>},

as members \tcode{put()} and \tcode{get()}, respectively.

Each such member function takes an

\indexlibrarymember{flags}{ios_base}%

\tcode{ios_base\&} argument whose members

\indexlibrarymember{flags}{ios_base}%

\tcode{flags()},

\indexlibrarymember{precision}{ios_base}%

\tcode{precision()},

and

\indexlibrarymember{width}{ios_base}%

\tcode{width()},

specify the format of the corresponding datum\iref{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 can 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 subclause \ref{locale.categories} it is unspecified whether

one virtual function calls another virtual function.

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

\rSec3[category.ctype.general]{General}

\indexlibraryglobal{ctype_base}%

\begin{codeblock}

namespace std {

class ctype_base {

public:

using mask = @\seebelow@;

// 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\iref{bitmask.types}.

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