[locale] (original) (raw)

28 Localization library [localization]

28.3 Locales [locales]

28.3.1 Class locale [locale]

namespace std { class locale { public:

class facet;
class id;
using category = int;
static const category   
  none     = 0,
  collate  = 0x010, ctype    = 0x020,
  monetary = 0x040, numeric  = 0x080,
  time     = 0x100, messages = 0x200,
  all = collate | ctype | monetary | numeric | time  | messages;


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();                  
const locale& operator=(const locale& other) noexcept;
template<class Facet> locale combine(const locale& other) const;


string name() 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;


static       locale  global(const locale&);
static const locale& classic();

}; }

Classlocaleimplements a type-safe polymorphic set of facets, indexed by facettype.

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 alocaleis via two function templates,use_­facet<>andhas_­facet<>.

[ Example

:

An iostream operator<< might be implemented as:257

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);
} return s; }

— end example

]

In the call touse_­facet<Facet>(loc), the type argument chooses a facet, making available all members of the named type.

IfFacetis not present in a locale, it throws the standard exceptionbad_­cast.

A C++ program can check if a locale implements a particular facet with the function templatehas_­facet<Facet>().

User-defined facets may be installed in a locale, and used identically as may standard facets.

[ Note

:

All locale semantics are accessed viause_­facet<>andhas_­facet<>, except that:

• A member operator templateoperator()(const basic_­string<C, T, A>&, const basic_­string<​C, T, A>&)is provided so that a locale may be used as a predicate argument to the standard collections, to collate strings.
• Convenient global interfaces are provided for traditionalctypefunctions such asisdigit()andisspace(), so that given a locale object loc a C++ program can callisspace(c, loc).

— end note

]

Once a facet reference is obtained from a locale object by callinguse_­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.

Alocaleconstructed from a name string (such as "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,locale​::​name()returns the string"*".

Whether there is one global locale object for the entire program or one global locale object per thread is implementation-defined.

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.

28.3.1.1 Types [locale.types]

28.3.1.1.1 Type locale​::​category [locale.category]

Valid categoryvalues include thelocalemember bitmask elementscollate,ctype,monetary,numeric,time, andmessages, each of which represents a single locale category.

In addition,localemember bitmask constantnoneis defined as zero and represents no category.

Andlocalemember bitmask constantallis defined such that the expression

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

istrue, and represents the union of all categories.

Further, the expression(X | Y), whereXandYeach represent a single category, represents the union of the two categories.

localemember functions expecting acategoryargument require one of thecategoryvalues defined above, or the union of two or more such values.

Such acategoryvalue identifies a set of locale categories.

Each locale category, in turn, identifies a set of locale facets, including at least those shown in Table 102.

Table 102: Locale category facets [tab:locale.category.facets]

For any locale loceither constructed, or returned bylocale​::​classic(), and any facet Facetshown in Table 102,has_­facet<Facet>(loc)is true.

Eachlocalemember function which takes alocale​::​categoryargument operates on the corresponding set of facets.

An implementation is required to provide those specializations for facet templates identified as members of a category, and for those shown in Table 103.

Table 103: Required specializations [tab:locale.spec]

The provided implementation of members of facetsnum_­get<charT>andnum_­put<charT>callsuse_­facet<F>(l)only for facetFof typesnumpunct<charT>andctype<charT>, and for localelthe value obtained by calling membergetloc()on theios_­base&argument to these functions.

In declarations of facets, a template parameter with nameInputIteratororOutputIteratorindicates the set of all possible specializations on parameters that meet theCpp17InputIterator requirements or Cpp17OutputIteratorrequirements, respectively ([iterator.requirements]).

A template parameter with nameCrepresents the set of types containing char, wchar_­t, and any otherimplementation-defined character types that meet the requirements for a character on which any of the iostream components can be instantiated.

A template parameter with nameInternationalrepresents the set of all possible specializations on a bool parameter.

28.3.1.1.2 Class locale​::​facet [locale.facet]

namespace std { class locale::facet { protected: explicit facet(size_t refs = 0); virtual ~facet(); facet(const facet&) = delete; void operator=(const facet&) = delete; }; }

Class facet is the base class for locale feature sets.

A class is a facetif it is publicly derived from another facet, or if it is a class derived from locale​::​facet and contains a publicly accessible declaration as follows:258

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

Template parameters in this Clause which are required to be facets are those namedFacetin declarations.

A program that passes a type that isnota 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 aFacet template parameter.

The refsargument to the constructor is used for lifetime management.

Forrefs == 0, the implementation performsdelete static_­cast<locale​::​facet*>(f)(wherefis a pointer to the facet) when the lastlocaleobject containing the facet is destroyed; forrefs == 1, the implementation never destroys the facet.

Constructors of all facets defined in this Clause take such an argument and pass it along to theirfacetbase class constructor.

All one-argument constructors defined in this Clause areexplicit, preventing their participation in automatic conversions.

For some standard facets a standard “…_­byname” class, derived from it, implements the virtual function semantics equivalent to that facet of the locale constructed bylocale(const char*)with the same name.

Each such facet provides a constructor that takes aconst char*argument, which names the locale, and a refsargument, which is passed to the base class constructor.

Each such facet also provides a constructor that takes astring argument str and a refsargument, which has the same effect as calling the first constructor with the two arguments str.c_­str() and refs.

If there is no “…_­byname” version of a facet, the base class implements named locale semantics itself by reference to other facets.

28.3.1.1.3 Class locale​::​id [locale.id]

namespace std { class locale::id { public: id(); void operator=(const id&) = delete; id(const id&) = delete; }; }

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

[ Note

:

Because facets are used by iostreams, potentially while static constructors are running, their initialization cannot depend on programmed static initialization.

One initialization strategy is forlocaleto initialize each facet'sidmember the first time an instance of the facet is installed into a locale.

This depends only on static storage being zero before constructors run ([basic.start.static]).

— end note

]

28.3.1.2 Constructors and destructor [locale.cons]

Effects:Constructs a copy of the argument last passed tolocale​::​global(locale&), if it has been called; else, the resulting facets have virtual function semantics identical to those oflocale​::​classic().

[ Note

:

This constructor yields a copy of the current global locale.

It is commonly used as a default argument for function parameters of type const locale&.

— end note

]

explicit locale(const char* std_name);

Effects:Constructs a locale using standard C locale names, e.g., "POSIX".

The resulting locale implements semantics defined to be associated with that name.

Throws: runtime_­errorif the argument is not valid, or is null.

Remarks:The set of valid string argument values is "C", "", and any implementation-defined values.

explicit locale(const string& std_name);

Effects:The same as locale(std_­name.c_­str()).

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

Effects:Constructs a locale as a copy ofotherexcept for the facets identified by thecategoryargument, which instead implement the same semantics aslocale(std_­name).

Throws: runtime_­errorif the argument is not valid, or is null.

Remarks:The locale has a name if and only ifotherhas a name.

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

Effects:The same as locale(other, std_­name.c_­str(), cat).

template<class Facet> locale(const locale& other, Facet* f);

Effects:Constructs a locale incorporating all facets from the first argument except that of typeFacet, and installs the second argument as the remaining facet.

If fis null, the resulting object is a copy of other.

Remarks:The resulting locale has no name.

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

Effects:Constructs a locale incorporating all facets from the first argument except those that implementcats, which are instead incorporated from the second argument.

Remarks:The resulting locale has a name if and only if the first two arguments have names.

const locale& operator=(const locale& other) noexcept;

Effects:Creates a copy of other, replacing the current value.

28.3.1.3 Members [locale.members]

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

Effects:Constructs a locale incorporating all facets from*thisexcept for that one facet ofotherthat is identified byFacet.

Returns:The newly created locale.

Throws: runtime_­errorifhas_­facet<Facet>(other)is false.

Remarks:The resulting locale has no name.

Returns:The name of*this, if it has one; otherwise, the string "*".

28.3.1.4 Operators [locale.operators]

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

Returns: trueif both arguments are the same locale, or one is a copy of the other, or each has a name and the names are identical;falseotherwise.

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

Effects:Compares two strings according to thecollate<charT>facet.

Remarks:This member operator template (and thereforelocaleitself) meets the requirements for a comparator predicate template argument ([algorithms]) applied to strings.

Returns:

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

[ Example

:

A vector of stringsvcan be collated according to collation rules in localelocsimply by ([alg.sort], [vector]):

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

— end example

]

28.3.1.5 Static members [locale.statics]

static locale global(const locale& loc);

Effects:Sets the global locale to its argument.

Causes future calls to the constructorlocale()to return a copy of the argument.

If the argument has a name, does

setlocale(LC_ALL, loc.name().c_str());

otherwise, the effect on the C locale, if any, is implementation-defined.

Remarks:No library function other thanlocale​::​global()affects the value returned bylocale().

[ Note

:

See [c.locales] for data race considerations whensetlocale is invoked.

— end note

]

Returns:The previous value oflocale().

static const locale& classic();

Returns:A locale that implements the classic "C" locale semantics, equivalent to the value locale("C").

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