Skip to content
Tutorials Center
My learning

Topics

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.

C++
std::locale loc = std::locale::classic();
std::cout.imbue(loc);   // set the locale used by cout

Try it

C++ Imbuing a stream with a custom numpunct facet

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.

C++ Facets, the classic locale and unknown names

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):

C++
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

C++
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 C setlocale if the locale has a name, which affects printf, strtod and the <cctype> functions.
  • std::cout is already constructed. Changing the global locale does not change it; call std::cout.imbue(...) too.
  • Facets are shared and immutable. A locale is cheap to copy (reference counted). Create the facet with new and pass it to a std::locale constructor, never delete it 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::format ignores locales by default. Use the L option 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.