std::locale(3)

💖 std::locale — bestie's guide to the locale class 💖

okay so. this is the Library Functions Manual page for std::locale, and honestly? it's a banger. grab a boba, we're doing this. 🧋

---

✨ NAME ✨

std::locale — Container class for localization functionality.

---

🌸 SYNOPSIS 🌸

#include <locale>

🎀 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<typename _Facet> locale (const locale &__other, _Facet *__f) — Construct locale with another facet.
• locale (const std::string &__s) — Named locale constructor.
• ~locale () throw () — Locale destructor.
• template<typename _Facet> locale combine (const locale &__other) const — Construct locale with another facet.
• string name () const — Return locale name.
• template<typename _Char, typename _Traits, typename _Alloc> bool operator() (const basic_string< _Char, _Traits, _Alloc > &__s1, const basic_string< _Char, _Traits, _Alloc > &__s2) const — Compare two strings according to collate.
• template<typename _CharT, typename _Traits, typename _Alloc> 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<typename _Facet> const _Facet * __try_use_facet (const locale &__loc)
• template<typename _Cache> struct __use_cache
• class _Impl
• class facet
• template<typename _Facet> bool has_facet (const locale &__loc) throw () — Test for the presence of a facet.
• template<typename _Facet> 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.

🫶 lowkey important: constructing C++ locales does NOT change the C library locale. they're separate girlies. no cap.

This library supports efficient construction and copying of locales through a reference counting implementation of the locale class. it's giving slay, honestly. ✨

---

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

😭 the way this one is referenced by literally everything… it's the main character, fr fr.

💜 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().

🙈 yes it's [explicit], so no sneaky implicit conversions, bestie. behave.

💜 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().

💀 note: this one throws if __s is an undefined locale — no "null" clause here, unlike the const char * twin. details matter, periodt.

💜 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<typename _Facet> 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().

✨ cute detail: if __f is null you just get a straight copy of __other. no drama, no fuss.

💜 std::locale::~locale ()

Locale destructor.

References locale().

---

🧚 MEMBER FUNCTION DOCUMENTATION 🧚

🌸 const locale & std::locale::classic () [static], [nodiscard]

Return reference to the C locale.

🌸 template<typename _Facet> 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().

👑 the way it hands you back the old global locale so you can put it back later… iconic behaviour, honestly.

🌸 string std::locale::name () const [nodiscard]

Return locale name.

Returns

• Locale name or "*" if unnamed.

References name().

Referenced by name().

💀 not name() referencing name() which is referenced by name(). she's her own bestie. we love a self-referential queen.

🌸 template<typename _Char, typename _Traits, typename _Alloc> 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==().

🫶 so two locales can be "equal" without being the literal same object — same instance, a copy, or just the same name all count. slay.

---

🌈 FRIENDS AND RELATED SYMBOL DOCUMENTATION 🌈

⭐ template<typename _Facet> 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().

🦋 lowkey a vibe check for facets. derived facets count too, so inheritance girlies get in.

⭐ template<typename _Facet> 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().

🔥 so like, check with has_facet first or you're getting a std::bad_cast to the face. we do not play like that.

---

okay so that's part 1 bestie… and there's literally more. don't go anywhere. 💖

💾 MEMBER DATA DOCUMENTATION 💾

okay bestie, gather round, because this is the part where we meet the actual constants you'll be passing around like little friendship bracelets. these are the standard category values, and they are the whole entire point of the category system, no cap.

so here's the tea: the standard category values are none, ctype, numeric, collate, time, monetary, and messages. they form a bitmask that supports union and intersection, and the category all is the union of these values. so yes, you can OR them together, AND them together, do the little bitmask dance, all of it. 💅

and one lil note that shows up for every single one of them, because the devs are not playing around:

NB: Order must match _S_facet_categories definition in locale.cc

like, the order is load-bearing. do not shuffle them. periodt.

---

🌈 const category std::locale::all [static]

the ✨union✨ of everybody. all is literally the union of none, ctype, numeric, collate, time, monetary, and messages — all seven of the standard category values, rolled into one bitmask. and yeah, this whole family forms a bitmask that supports union and intersection.

NB: Order must match _S_facet_categories definition in locale.cc

🎀 const category std::locale::collate [static]

one of the standard category values, alongside none, ctype, numeric, time, monetary, and messages. they're all a bitmask that supports union and intersection, and all is the union of the bunch.

NB: Order must match _S_facet_categories definition in locale.cc

🦋 const category std::locale::ctype [static]

your classic character-type category, sitting right there in the standard lineup with none, numeric, collate, time, monetary, and messages. bitmask, union, intersection, all is the union — you know the drill by now, bestie.

NB: Order must match _S_facet_categories definition in locale.cc

💌 const category std::locale::messages [static]

the messages category! still a standard category value, still chillin' with none, ctype, numeric, collate, time, and monetary. bitmask that supports union and intersection, all is the union of all of them.

NB: Order must match _S_facet_categories definition in locale.cc

💰 const category std::locale::monetary [static]

money money money 💸 — the monetary category, one of the standard values none, ctype, numeric, collate, time, and messages. they form a bitmask supporting union and intersection, and all is the union of these values.

NB: Order must match _S_facet_categories definition in locale.cc

🕳️ const category std::locale::none [static]

the empty one, the void, the "no categories here" queen 👑. none is a standard category value just like ctype, numeric, collate, time, monetary, and messages. bitmask, union, intersection, all = the union of them all.

NB: Order must match _S_facet_categories definition in locale.cc

🔢 const category std::locale::numeric [static]

numbers!! the numeric category, hanging out in the standard set with none, ctype, collate, time, monetary, and messages. they're a bitmask that supports union and intersection, and all is the union of all these values.

NB: Order must match _S_facet_categories definition in locale.cc

⏰ const category std::locale::time [static]

time is a construct and also a standard category value, bestie. it lives with none, ctype, numeric, collate, monetary, and messages, they're all a bitmask supporting union and intersection, and 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.

---

and that's a wrap on std::locale 🫶 this page came to you courtesy of libstdc++, page std::locale(3), and it was auto-generated by Doxygen straight from the source code — so if anything here is giving mysterious, blame the generator bestie, not me 💀 ✨🎀🌸