--- name: "std::locale" section: "3" platform: "linux" package: "gcc" version: "16.2.1+r23+gd564253eb6c8-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/std::locale" --- # std::locale(3) Container class for localization functionality. ## NAME std::locale - Container class for localization functionality. ## SYNOPSIS \#include \ ### Classes class **facet**\ Localization functionality base class. class **id**\ Facet ID class. ### Public Types typedef int **category**\ Definition of locale::category. ### Public Member Functions **locale** () throw ()\ Default constructor. **locale** (const char \*\_\_s)\ Named locale constructor. **locale** (const locale &\_\_base, const char \*\_\_s, **category** \_\_cat)\ Construct locale with facets from another locale. **locale** (const locale &\_\_base, const locale &\_\_add, **category** \_\_cat)\ Construct locale with facets from another locale. **locale** (const locale &\_\_base, const **std::string** &\_\_s, **category** \_\_cat)\ Construct locale with facets from another locale. **locale** (const locale &\_\_other) throw ()\ Copy constructor. template\ **locale** (const locale &\_\_other, \_Facet \*\_\_f)\ Construct locale with another facet. **locale** (const **std::string** &\_\_s)\ Named locale constructor. **~locale** () throw ()\ Locale destructor. template\ **locale** **combine** (const **locale** &\_\_other) const\ Construct locale with another facet. **string** **name** () const\ Return locale name. template\ bool **operator()** (const **basic\_string**\< \_Char, \_Traits, \_Alloc \> &\_\_s1, const **basic\_string**\< \_Char, \_Traits, \_Alloc \> &\_\_s2) const\ Compare two strings according to collate. template\ bool **operator()** (const **basic\_string**\< \_CharT, \_Traits, \_Alloc \> &\_\_s1, const **basic\_string**\< \_CharT, \_Traits, \_Alloc \> &\_\_s2) const\ const **locale** & **operator=** (const **locale** &\_\_other) throw ()\ Assignment operator. bool **operator==** (const **locale** &\_\_other) const throw ()\ Locale equality. ### Static Public Member Functions static const **locale** & **classic** ()\ Return reference to the C locale. static **locale** **global** (const **locale** &\_\_loc)\ Set global locale. ### Static Public Attributes static const **category** **none**\ Category values. static const **category** **ctype**\ Category values. static const **category** **numeric**\ Category values. static const **category** **collate**\ Category values. static const **category** **time**\ Category values. static const **category** **monetary**\ Category values. static const **category** **messages**\ Category values. static const **category** **all**\ Category values. ### Friends template\ const \_Facet \* **\_\_try\_use\_facet** (const **locale** &\_\_loc)\ template\ struct **\_\_use\_cache**\ class **\_Impl**\ class **facet**\ template\ bool **has\_facet** (const **locale** &\_\_loc) throw ()\ Test for the presence of a facet. template\ const \_Facet & **use\_facet** (const **locale** &\_\_loc)\ Return a facet. ## Detailed Description Container class for localization functionality. The locale class is first a class wrapper for C library locales. It is also an extensible container for user-defined localization. A locale is a collection of facets that implement various localization features such as money, time, and number printing. Constructing C++ locales does not change the C library locale. This library supports efficient construction and copying of locales through a reference counting implementation of the locale class. ## Member Typedef Documentation ### typedef int std::locale::category Definition of locale::category. ## Constructor & Destructor Documentation ### std::locale::locale () Default constructor. Constructs a copy of the global locale. If no locale has been explicitly set, this is the C locale. Referenced by **locale()**, **locale()**, **locale()**, **locale()**, **locale()**, **locale()**, **locale()**, **~locale()**, **combine()**, **global()**, **has\_facet**, **operator()()**, **operator=()**, **operator==()**, and **use\_facet**. ### std::locale::locale (const locale & \_\_other) Copy constructor. Constructs a copy of *other*. **Parameters** *\_\_other* The locale to copy. References **locale()**. ### std::locale::locale (const char \* \_\_s) \[explicit\] Named locale constructor. Constructs a copy of the named C library locale. **Parameters** *\_\_s* Name of the locale to construct. **Exceptions** **std::runtime\_error if \_\_s is null or an undefined locale.** **References locale().** ### std::locale::locale (const locale & \_\_base, const char \* \_\_s, category \_\_cat) **Construct locale with facets from another locale. Constructs a copy of the locale** *base***. The facets specified by** *cat* **are replaced with those from the locale named by** *s***. If base is named, this locale instance will also be named.** **Parameters** *\_\_base* **The locale to copy.** \ *\_\_s* **Name of the locale to use facets from.** \ *\_\_cat* **Set of categories defining the facets to use from \_\_s.** **Exceptions** **std::runtime\_error if \_\_s is null or an undefined locale.** **References locale().** ### std::locale::locale (const std::string & \_\_s) \[inline\], \[explicit\] **Named locale constructor. Constructs a copy of the named C library locale.** **Parameters** *\_\_s* **Name of the locale to construct.** **Exceptions** **std::runtime\_error if \_\_s is an undefined locale.** **References locale().** ### std::locale::locale (const locale & \_\_base, const std::string & \_\_s, category \_\_cat) \[inline\] **Construct locale with facets from another locale. Constructs a copy of the locale** *base***. The facets specified by** *cat* **are replaced with those from the locale named by** *s***. If base is named, this locale instance will also be named.** **Parameters** *\_\_base* **The locale to copy.** \ *\_\_s* **Name of the locale to use facets from.** \ *\_\_cat* **Set of categories defining the facets to use from \_\_s.** **Exceptions** **std::runtime\_error if \_\_s is an undefined locale.** **References locale().** ### std::locale::locale (const locale & \_\_base, const locale & \_\_add, category \_\_cat) **Construct locale with facets from another locale. Constructs a copy of the locale** *base***. The facets specified by** *cat* **are replaced with those from the locale** *add***. If** *base* **and** *add* **are named, this locale instance will also be named.** **Parameters** *\_\_base* **The locale to copy.** \ *\_\_add* **The locale to use facets from.** \ *\_\_cat* **Set of categories defining the facets to use from add.** **References locale().** ### template\ std::locale::locale (const locale & \_\_other, \_Facet \* \_\_f) **Construct locale with another facet. Constructs a copy of the locale** *\_\_other***. The facet** *\_\_f* **is added to** *\_\_other***, replacing an existing facet of type Facet if there is one. If** *\_\_f* **is null, this locale is a copy of** *\_\_other***.** **Parameters** *\_\_other* **The locale to copy.** \ *\_\_f* **The facet to add in.** **References locale().** ### std::locale::~locale () **Locale destructor.** **References locale().** ## Member Function Documentation ### const locale & std::locale::classic () \[static\], \[nodiscard\] **Return reference to the C locale.** ### template\ locale std::locale::combine (const locale & \_\_other) const \[nodiscard\] **Construct locale with another facet. Constructs and returns a new copy of this locale. Adds or replaces an existing facet of type Facet from the locale** *other* **into the new locale.** **Template Parameters** *\_Facet* **The facet type to copy from other** **Parameters** *\_\_other* **The locale to copy from.** **Returns** **Newly constructed locale.** **Exceptions** **std::runtime\_error if \_\_other has no facet of type \_Facet.** **References locale().** **Referenced by operator=().** ### locale std::locale::global (const locale & \_\_loc) \[static\] **Set global locale. This function sets the global locale to the argument and returns a copy of the previous global locale. If the argument has a name, it will also call std::setlocale(LC\_ALL, loc.name()).** **Parameters** *\_\_loc* **The new locale to make global.** **Returns** **Copy of the old global locale.** **References locale().** ### string std::locale::name () const \[nodiscard\] **Return locale name.** **Returns** **Locale name or "\*" if unnamed.** **References name().** **Referenced by name().** ### template\ bool std::locale::operator() (const basic\_string\< \_Char, \_Traits, \_Alloc \> & \_\_s1, const basic\_string\< \_Char, \_Traits, \_Alloc \> & \_\_s2) const \[nodiscard\] **Compare two strings according to collate. Template operator to compare two strings using the compare function of the collate facet in this locale. One use is to provide the locale to the sort function. For example, a vector v of strings could be sorted according to locale loc by doing:** ``` std::sort(v.begin(), v.end(), loc); ``` **Parameters** *\_\_s1* **First string to compare.** \ *\_\_s2* **Second string to compare.** **Returns** **True if collate\<\_Char\> facet compares \_\_s1 \< \_\_s2, else false.** **References locale().** ### const locale & std::locale::operator= (const locale & \_\_other) **Assignment operator. Set this locale to be a copy of** *other***.** **Parameters** *\_\_other* **The locale to copy.** **Returns** **A reference to this locale.** **References locale(), and combine().** ### bool std::locale::operator== (const locale & \_\_other) const \[nodiscard\] **Locale equality.** **Parameters** *\_\_other* **The locale to compare against.** **Returns** **True if other and this refer to the same locale instance, are copies, or have the same name. False otherwise.** **References locale(), and operator==().** **Referenced by operator==().** ## Friends And Related Symbol Documentation ### template\ bool has\_facet (const locale & \_\_loc) \[friend\] **Test for the presence of a facet. has\_facet tests the locale argument for the presence of the facet type provided as the template parameter. Facets derived from the facet parameter will also return true.** **Template Parameters** *\_Facet* **The facet type to test the presence of.** **Parameters** *\_\_loc* **The locale to test.** **Returns** **true if** \_\_loc **contains a facet of type \_Facet, else false.** **References locale().** ### template\ const \_Facet & use\_facet (const locale & \_\_loc) \[friend\] **Return a facet. use\_facet looks for and returns a reference to a facet of type Facet where Facet is the template parameter. If has\_facet(locale) is true, there is a suitable facet to return. It throws std::bad\_cast if the locale doesn't contain a facet of type Facet.** **Template Parameters** *\_Facet* **The facet type to access.** **Parameters** *\_\_loc* **The locale to use.** **Returns** **Reference to facet of type Facet.** **Exceptions** **std::bad\_cast if** \_\_loc **doesn't contain a facet of type \_Facet.** **References locale().** ## Member Data Documentation ### const category std::locale::all \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::collate \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::ctype \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::messages \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::monetary \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::none \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::numeric \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ### const category std::locale::time \[static\] **Category values. The standard category values are none, ctype, numeric, collate, time, monetary, and messages. They form a bitmask that supports union and intersection. The category all is the union of these values.** **NB: Order must match \_S\_facet\_categories definition in locale.cc** ## Author **Generated automatically by Doxygen for libstdc++ from the source code.**