\rSec0[text]{Text processing library}

\rSec1[text.general]{General}

This Clause describes components for dealing with text.

These components are summarized in \tref{text.summary}.

\begin{libsumtab}{Text library summary}{text.summary}

\ref{charconv} & Primitive numeric conversions & \tcode{<charconv>} \\ \rowsep

\ref{localization} & Localization library & \tcode{<locale>}, \tcode{<clocale>} \\ \rowsep

\ref{format} & Formatting & \tcode{<format>} \\ \rowsep

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

\ref{re} & Regular expressions library & \tcode{<regex>} \\ \rowsep

\ref{text.c.strings} & Null-terminated sequence utilities &

\tcode{<cctype>}, \tcode{<cstdlib>}, \tcode{<cuchar>}, \tcode{<cwchar>}, \tcode{<cwctype>} \\

\end{libsumtab}

\rSec1[charconv]{Primitive numeric conversions}

\rSec2[charconv.syn]{Header \tcode{<charconv>} synopsis}

When a function is specified

with a type placeholder of \tcode{\placeholder{integer-type}},

the implementation provides overloads

for \tcode{char} and all cv-unqualified signed and unsigned integer types

in lieu of \tcode{\placeholder{integer-type}}.

When a function is specified

with a type placeholder of \tcode{\placeholder{floating-point-type}},

the implementation provides overloads

for all cv-unqualified floating-point types\iref{basic.fundamental}

in lieu of \tcode{\placeholder{floating-point-type}}.

\indexheader{charconv}%

\begin{codeblock}

namespace std {

// floating-point format for primitive numerical conversion

enum class @\libglobal{chars_format}@ {

@\libmember{scientific}{chars_format}@ = @\unspec@,

@\libmember{fixed}{chars_format}@ = @\unspec@,

@\libmember{hex}{chars_format}@ = @\unspec@,

@\libmember{general}{chars_format}@ = fixed | scientific

};

// \ref{charconv.to.chars}, primitive numerical output conversion

struct @\libglobal{to_chars_result}@ { // freestanding

char* @\libmember{ptr}{to_chars_result}@;

errc @\libmember{ec}{to_chars_result}@;

friend bool operator==(const to_chars_result&, const to_chars_result&) = default;

constexpr explicit operator bool() const noexcept { return ec == errc{}; }

};

constexpr to_chars_result to_chars(char* first, char* last, // freestanding

@\placeholder{integer-type}@ value, int base = 10);

to_chars_result to_chars(char* first, char* last, // freestanding

bool value, int base = 10) = delete;

to_chars_result to_chars(char* first, char* last, // freestanding-deleted

@\placeholder{floating-point-type}@ value);

to_chars_result to_chars(char* first, char* last, // freestanding-deleted

@\placeholder{floating-point-type}@ value, chars_format fmt);

to_chars_result to_chars(char* first, char* last, // freestanding-deleted

@\placeholder{floating-point-type}@ value, chars_format fmt, int precision);

// \ref{charconv.from.chars}, primitive numerical input conversion

struct @\libglobal{from_chars_result}@ { // freestanding

const char* @\libmember{ptr}{from_chars_result}@;

errc @\libmember{ec}{from_chars_result}@;

friend bool operator==(const from_chars_result&, const from_chars_result&) = default;

constexpr explicit operator bool() const noexcept { return ec == errc{}; }

};

constexpr from_chars_result from_chars(const char* first, const char* last, // freestanding

@\placeholder{integer-type}@& value, int base = 10);

from_chars_result from_chars(const char* first, const char* last, // freestanding-deleted

@\placeholder{floating-point-type}@& value,

chars_format fmt = chars_format::general);

}

\end{codeblock}

The type \tcode{chars_format} is a bitmask type\iref{bitmask.types}

with elements \tcode{scientific}, \tcode{fixed}, and \tcode{hex}.

The types \tcode{to_chars_result} and \tcode{from_chars_result}

have the data members and special members specified above.

They have no base classes or members other than those specified.

\rSec2[charconv.to.chars]{Primitive numeric output conversion}

All functions named \tcode{to_chars}

convert \tcode{value} into a character string

by successively filling the range

\range{first}{last},

where \range{first}{last} is required to be a valid range.

If the member \tcode{ec}

of the return value

is such that the value

is equal to the value of a value-initialized \tcode{errc},

the conversion was successful

and the member \tcode{ptr}

is the one-past-the-end pointer of the characters written.

Otherwise,

the member \tcode{ec} has the value \tcode{errc::value_too_large},

the member \tcode{ptr} has the value \tcode{last},

and the contents of the range \range{first}{last} are unspecified.

The functions that take a floating-point \tcode{value}

but not a \tcode{precision} parameter

ensure that the string representation

consists of the smallest number of characters

such that

there is at least one digit before the radix point (if present) and

parsing the representation using the corresponding \tcode{from_chars} function

recovers \tcode{value} exactly.

\begin{note}

This guarantee applies only if

\tcode{to_chars} and \tcode{from_chars}

are executed on the same implementation.

\end{note}

If there are several such representations,

the representation with the smallest difference from

the floating-point argument value is chosen,

resolving any remaining ties using rounding according to

\tcode{round_to_nearest}\iref{round.style}.

The functions taking a \tcode{chars_format} parameter

determine the conversion specifier for \tcode{printf} as follows:

The conversion specifier is

\tcode{f} if \tcode{fmt} is \tcode{chars_format::fixed},

\tcode{e} if \tcode{fmt} is \tcode{chars_format::scientific},

\tcode{a} (without leading \tcode{"0x"} in the result)

if \tcode{fmt} is \tcode{chars_format::hex},

and

\tcode{g} if \tcode{fmt} is \tcode{chars_format::general}.

\indexlibraryglobal{to_chars}%

\begin{itemdecl}

constexpr to_chars_result to_chars(char* first, char* last, @\placeholder{integer-type}@ value, int base = 10);

\end{itemdecl}

\begin{itemdescr}

\tcode{base} has a value between 2 and 36 (inclusive).

The value of \tcode{value} is converted

to a string of digits in the given base

(with no redundant leading zeroes).

Digits in the range 10..35 (inclusive)

are represented as lowercase characters \tcode{a}..\tcode{z}.

If \tcode{value} is less than zero,

the representation starts with \tcode{'-'}.

Nothing.

\end{itemdescr}

\indexlibraryglobal{to_chars}%

\begin{itemdecl}

to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value);

\end{itemdecl}

\begin{itemdescr}

\tcode{value} is converted to a string

in the style of \tcode{printf}

in the \tcode{"C"} locale.

The conversion specifier is \tcode{f} or \tcode{e},

chosen according to the requirement for a shortest representation

(see above);

a tie is resolved in favor of \tcode{f}.

Nothing.

\end{itemdescr}

\indexlibraryglobal{to_chars}%

\begin{itemdecl}

to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value, chars_format fmt);

\end{itemdecl}

\begin{itemdescr}

\tcode{fmt} has the value of

one of the enumerators of \tcode{chars_format}.

\tcode{value} is converted to a string

in the style of \tcode{printf}

in the \tcode{"C"} locale.

Nothing.

\end{itemdescr}

\indexlibraryglobal{to_chars}%

\begin{itemdecl}

to_chars_result to_chars(char* first, char* last, @\placeholder{floating-point-type}@ value,

chars_format fmt, int precision);

\end{itemdecl}

\begin{itemdescr}

\tcode{fmt} has the value of

one of the enumerators of \tcode{chars_format}.

\tcode{value} is converted to a string

in the style of \tcode{printf}

in the \tcode{"C"} locale

with the given precision.

Nothing.

\end{itemdescr}

\xrefc{7.23.6.2}

\rSec2[charconv.from.chars]{Primitive numeric input conversion}

All functions named \tcode{from_chars}

analyze the string \range{first}{last}

for a pattern,

where \range{first}{last} is required to be a valid range.

If no characters match the pattern,

\tcode{value} is unmodified,

the member \tcode{ptr} of the return value is \tcode{first} and

the member \tcode{ec} is equal to \tcode{errc::invalid_argument}.

\begin{note}

If the pattern allows for an optional sign,

but the string has no digit characters following the sign,

no characters match the pattern.

\end{note}

Otherwise,

the characters matching the pattern

are interpreted as a representation

of a value of the type of \tcode{value}.

The member \tcode{ptr}

of the return value

points to the first character

not matching the pattern,

or has the value \tcode{last}

if all characters match.

If the parsed value

is not in the range

representable by the type of \tcode{value},

\tcode{value} is unmodified and

the member \tcode{ec} of the return value

is equal to \tcode{errc::result_out_of_range}.

Otherwise,

\tcode{value} is set to the parsed value,

after rounding according to \tcode{round_to_nearest}\iref{round.style}, and

the member \tcode{ec} is value-initialized.

\indexlibraryglobal{from_chars}%

\begin{itemdecl}

constexpr from_chars_result from_chars(const char* first, const char* last,

@\placeholder{integer-type}@&@\itcorr[-1]@ value, int base = 10);

\end{itemdecl}

\begin{itemdescr}

\tcode{base} has a value between 2 and 36 (inclusive).

The pattern is the expected form of the subject sequence

in the \tcode{"C"} locale

for the given nonzero base,

as described for \tcode{strtol},

except that no \tcode{"0x"} or \tcode{"0X"} prefix shall appear

if the value of \tcode{base} is 16,

and except that \tcode{'-'}

is the only sign that may appear,

and only if \tcode{value} has a signed type.

Nothing.

\end{itemdescr}

\indexlibraryglobal{from_chars}%

\begin{itemdecl}

from_chars_result from_chars(const char* first, const char* last, @\placeholder{floating-point-type}@& value,

chars_format fmt = chars_format::general);

\end{itemdecl}

\begin{itemdescr}

\tcode{fmt} has the value of

one of the enumerators of \tcode{chars_format}.

The pattern is the expected form of the subject sequence

in the \tcode{"C"} locale,

as described for \tcode{strtod},

except that

\begin{itemize}

the sign \tcode{'+'} may only appear in the exponent part;

if \tcode{fmt} has \tcode{chars_format::scientific} set

but not \tcode{chars_format::fixed},

the otherwise optional exponent part shall appear;

if \tcode{fmt} has \tcode{chars_format::fixed} set

but not \tcode{chars_format::scientific},

the optional exponent part shall not appear; and

if \tcode{fmt} is \tcode{chars_format::hex},

the prefix \tcode{"0x"} or \tcode{"0X"} is assumed.

\begin{example}

The string \tcode{0x123}

is parsed to have the value

\tcode{0}

with remaining characters \tcode{x123}.

\end{example}

\end{itemize}

In any case, the resulting \tcode{value} is one of

at most two floating-point values

closest to the value of the string matching the pattern.

Nothing.

\end{itemdescr}

\xrefc{7.24.2.6, 7.24.2.8}

\rSec1[localization]{Localization library}

\rSec2[localization.general]{General}

Subclause \ref{localization} 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.

The following subclauses describe components for

locales themselves,

the standard facets, and

facilities from the 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

\end{libsumtab}

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

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}

\rSec2[locales]{Locales}

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

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

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.

Access to the facets of a \tcode{locale} is via two function templates,

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

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

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.

\begin{note}

All locale semantics are accessed via

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

except that:

\begin{itemize}

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.

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}

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.

In successive calls to a locale facet member function

on a facet object installed in the same locale,

the returned result shall be identical.

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{"*"}.

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

\rSec4[locale.types]{Types}

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

\indexlibrarymember{locale}{category}%

\begin{itemdecl}

using category = int;

\end{itemdecl}

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

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

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

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.

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}

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

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.

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 container types

that iostreams templates can be instantiated for}

character container types\iref{defns.character.container}

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.

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

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}

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.

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.

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 explicit,

preventing their participation in implicit conversions.

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.

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

The class \tcode{locale::id} provides

identification of a locale facet interface,

used as an index for lookup and to encapsulate initialization.

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

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

\indexlibraryctor{locale}%

\begin{itemdecl}

locale() noexcept;

\end{itemdecl}

\begin{itemdescr}

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}

Constructs a locale using standard C locale names, e.g., \tcode{"POSIX"}.

The resulting locale implements semantics defined to be associated

with that name.

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

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}

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}

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

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

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

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}

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}

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

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}

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

Constructs a locale incorporating all facets from the first argument

except those that implement \tcode{cats},

which are instead incorporated from the second argument.

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}

Creates a copy of \tcode{other}, replacing the current value.