std::locale

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Localizations library

Locales and facets
locale
use_facet	has_facet
Character classification
isspace isblank (C++11) iscntrl isupper islower isalpha	isdigit ispunct isxdigit isalnum isprint isgraph
Conversions
toupper tolower	wstring_convert (C++11) wbuffer_convert (C++11)
Facet category base classes
ctype_base codecvt_base messages_base	time_base money_base
Facet categories
ctype ctype<char> codecvt collate messages time_get time_put	num_get num_put numpunct money_get money_put moneypunct
Locale-specific facets
ctype_byname codecvt_byname messages_byname collate_byname	time_get_byname time_put_byname numpunct_byname moneypunct_byname
Code conversion facets
codecvt_utf8 (C++11) codecvt_utf16 (C++11)	codecvt_utf8_utf16 (C++11) codecvt_mode (C++11)
C locale
setlocale localeconv lconv	LC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME

 

std::locale

Member types

locale::id

locale::facet

Member functions

locale::locale

locale::~locale

locale::operator=

locale::combine

locale::name

locale::operator==locale::operator!= (until C++20)

locale::operator()

Static member functions

locale::global

locale::classic

 

Defined in header <locale>
class locale;

An object of class std::locale is an immutable indexed set of immutable facets. Each stream object of the C++ input/output library is associated with an std::locale object and uses its facets for parsing and formatting of all data. In addition, a locale object is associated with each std::basic_regex object. Locale objects can also be used as predicates that perform string collation with the standard containers and algorithms and can be accessed directly to obtain or modify the facets they hold.

Each locale constructed in a C++ program holds at least the following standard facets, but a program may define additional specializations or completely new facets and add them to any existing locale object.

Supported facets
std::collate<char>	std::collate<wchar_t>
std::ctype<char>	std::ctype<wchar_t>
std::codecvt<char,char,mbstate_t> std::codecvt<char16_t,char,mbstate_t>	std::codecvt<char32_t,char,mbstate_t> std::codecvt<wchar_t,char,mbstate_t>
std::moneypunct<char> std::moneypunct<char,true>	std::moneypunct<wchar_t> std::moneypunct<wchar_t,true>
std::money_get<char>	std::money_get<wchar_t>
std::money_put<char>	std::money_put<wchar_t>
std::numpunct<char>	std::numpunct<wchar_t>
std::num_get<char>	std::num_get<wchar_t>
std::num_put<char>	std::num_put<wchar_t>
std::time_get<char>	std::time_get<wchar_t>
std::time_put<char>	std::time_put<wchar_t>
std::messages<char>	std::messages<wchar_t>

Internally, a locale object is implemented as-if it is a reference-counted pointer to an array (indexed by std::locale::id) of reference-counted pointers to facets: copying a locale only copies one pointer and increments several reference counts. To maintain the standard C++ library thread safety guarantees (operations on different objects are always thread-safe), both the locale reference count and each facet reference count are updated in thread-safe manner, similar to std::shared_ptr.

Member types

id	the facet index type: each facet class must declare or inherit a public static member of this type (class)
facet	the base class for all facet categories: each facet of any category is derived from this type (class)
category	int (typedef)

Member objects

none [static]	a zero value of type category indicating no facet category (public static member constant)
collate [static]	a bitmask value of type category indicating the collate facet category (public static member constant)
ctype [static]	a bitmask value of type category indicating the ctype facet category (public static member constant)
monetary [static]	a bitmask value of type category indicating the monetary facet category (public static member constant)
numeric [static]	a bitmask value of type category indicating the numeric facet category (public static member constant)
time [static]	a bitmask value of type category indicating the time facet category (public static member constant)
messages [static]	a bitmask value of type category indicating the messages facet category (public static member constant)
all [static]	collate | ctype | monetary | numeric | time | messages (public static member constant)

Member functions

(constructor)	constructs a new locale (public member function)
(destructor)	destructs the locale and the facets whose reference count becomes zero (public member function)
operator=	replaces a locale (public member function)
combine	constructs a locale with compile-time identified facet copied from another locale (public member function)
name	returns the name of the locale or "*" if unnamed (public member function)
operator==operator!= (removed in C++20)	equality comparison between locale objects (public member function)
operator()	lexicographically compares two strings using this locale's collate facet (public member function)
global [static]	changes the global locale (public static member function)
classic [static]	obtains a reference to the "C" locale (public static member function)

Example

Demonstrates the typical prologue of a locale-sensitive program (cross-platform)

Run this code

#include <iostream>
#include <locale>
 
int main()
{
    std::wcout << "User-preferred locale setting is " << std::locale("").name().c_str() << '\n';
    // on startup, the global locale is the "C" locale
    std::wcout << 1000.01 << '\n';
    // replace the C++ global locale as well as the C locale with the user-preferred locale
    std::locale::global(std::locale(""));
    // use the new global locale for future wide character output
    std::wcout.imbue(std::locale());
    // output the same number again
    std::wcout << 1000.01 << '\n';
}

Possible output:

User-preferred locale setting is en_US.UTF8
1000.01
1,000.01

See also

use_facet	obtains a facet from a locale (function template)
has_facet	checks if a locale implements a specific facet (function template)
imbue	sets locale (public member function of std::ios_base)
getloc	returns current locale (public member function of std::ios_base)