C++ Reference ยท Strings and I/O
C++ std::locale class
Reference for std::locale: the classic C locale, imbuing streams, facets like numpunct and ctype, custom number grouping, and why system locales are fragile.
A std::locale (header <locale>) is a bundle of facets, small objects that decide cultural details: how numbers are grouped and which character is the decimal point (std::numpunct), how characters are classified and converted (std::ctype), how dates, money and text are formatted and collated. Every stream carries a locale, and its formatted input and output consult the facets in it.
The default is the classic locale, equivalent to the C locale: plain ASCII rules, . as the decimal point, no digit grouping. Because a locale name such as "de_DE.UTF-8" only works when the operating system has installed it, code that depends on system locales behaves differently from machine to machine. This page shows locales you can build yourself, which behave the same everywhere.
std::locale loc = std::locale::classic(); std::cout.imbue(loc); // set the locale used by cout
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
For reference only, because it depends on what the machine has installed (it is not run in our editor):
try { std::locale::global(std::locale("de_DE.UTF-8")); std::cout.imbue(std::locale()); std::cout << 1234567.5 << "\n"; // 1.234.567,5 on a system that has the locale } catch (const std::runtime_error&) { std::cout << "locale not installed\n"; }
Syntax
std::locale(); // copy of the global locale explicit std::locale(const char* name); // named locale; throws if unknown std::locale(const std::locale& base, Facet* f); // base plus one replaced facet static const std::locale& std::locale::classic(); static std::locale std::locale::global(const std::locale& loc); std::locale std::ios_base::imbue(const std::locale& loc); std::locale std::ios_base::getloc() const; template<class Facet> const Facet& std::use_facet(const std::locale&); template<class Facet> bool std::has_facet(const std::locale&) noexcept;
| Name | Description |
|---|---|
name |
A system locale name ("" means the user's environment). "C" is always available. |
base, f |
Build a new locale from base with the facet of type Facet replaced by *f. Ownership of f passes to the locale. |
imbue(loc) |
Replaces a stream's locale and returns the previous one. |
Errors: std::locale(const char*) throws std::runtime_error if the name is not valid on the system. use_facet throws std::bad_cast if the facet is missing.
Usage notes
- Streams start with the global locale at construction time. The initial global locale is the classic one.
std::locale::global(loc)changes it for streams created afterwards, and also calls the Csetlocaleif the locale has a name, which affectsprintf,strtodand the<cctype>functions. std::coutis already constructed. Changing the global locale does not change it; callstd::cout.imbue(...)too.- Facets are shared and immutable. A locale is cheap to copy (reference counted). Create the facet with
newand pass it to astd::localeconstructor, neverdeleteit yourself or place it on the stack. - Common facets:
numpunct(separators,truename),ctype(classification, case, narrowing),num_put/num_get,moneypunct,money_put,time_put,collate(string comparison and sorting),codecvt(character encoding conversion). - Locale names are not portable.
"en_US.UTF-8"exists on Linux and macOS,"English_United States.1252"on Windows, and minimal containers often have only"C"and"POSIX". Always handle the exception. std::formatignores locales by default. Use theLoption in the format spec ({:L}) to opt in. See Format specifications.- Do not use locales for correct Unicode text handling.
std::ctype<char>works per byte and cannot judge UTF-8 characters. For real internationalization use a library such as ICU. - Thread safety. Reading from locale objects is safe; changing the global locale while other threads do I/O is not.