libstdc++: std::locale Class Reference

libstdc++

std::locale Class Reference
Locales

`#include <locale_classes.h>`

## Classes
class | facet
class | id

## Public Types
typedef int | category

## Public Member Functions
| locale () throw ()
| locale (const char *__s)
| locale (const locale &__base, const char *__s, category __cat)
| locale (const locale &__base, const locale &__add, category __cat)
| locale (const locale &__base, const std::string &__s, category __cat)
| locale (const locale &__other) throw ()
template<typename _Facet>
| locale (const locale &__other, _Facet *__f)
| locale (const std::string &__s)
| ~locale () throw ()
template<typename _Facet>
locale | combine (const locale &__other) const
string | name () const
template<typename _Char, typename _Traits, typename _Alloc>
bool | operator() (const basic_string< _Char, _Traits, _Alloc > &__s1, const basic_string< _Char, _Traits, _Alloc > &__s2) const
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 ()
bool | operator== (const locale &__other) const throw ()

## Static Public Member Functions
static const locale & | classic ()
static locale | global (const locale &__loc)

## Static Public Attributes
static const category | none
static const category | ctype
static const category | numeric
static const category | collate
static const category | time
static const category | monetary
static const category | messages
static const category | all

## 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 ()
template<typename _Facet>
const _Facet & | use_facet (const locale &__loc)

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

Definition at line 69 of file locale_classes.h.

## Member Typedef Documentation

## ◆ category

typedef int std::locale::category

Definition of locale::category.

Definition at line 74 of file locale_classes.h.

## Constructor & Destructor Documentation

## ◆ locale() [1/8]

std::locale::locale | ( |  | ) |
throw | ( | ) |  |  |

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.

## ◆ locale() [2/8]

std::locale::locale | ( | const locale & | __other | ) |
throw | ( | ) |  |  |

Copy constructor.

Constructs a copy of other.

Parameters

  __other | The locale to copy.

References locale().

## ◆ locale() [3/8]

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

## ◆ locale() [4/8]

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

## ◆ locale() [5/8]

std::locale::locale | ( | const std::string & | __s | ) |
| inlineexplicit

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.

Definition at line 174 of file locale_classes.h.

References locale().

## ◆ locale() [6/8]

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.

Definition at line 188 of file locale_classes.h.

References locale().

## ◆ locale() [7/8]

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

## ◆ locale() [8/8]

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.

Definition at line 52 of file locale_classes.tcc.

References locale().

## ◆ ~locale()

std::locale::~locale | ( |  | ) |
throw | ( | ) |  |  |

Locale destructor.

References locale().

## Member Function Documentation

## ◆ classic()

const locale & std::locale::classic | ( |  | ) |
| staticnodiscard

Return reference to the C locale.

## ◆ combine()

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.

Definition at line 79 of file locale_classes.tcc.

References locale().

Referenced by operator=().

## ◆ global()

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

## ◆ name()

string std::locale::name | ( |  | ) | const
| nodiscard

Return locale name.

Returns
  Locale name or "*" if unnamed.

References name().

Referenced by name().

## ◆ operator()() [1/2]

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

## ◆ operator()() [2/2]

template<typename _CharT, typename _Traits, typename _Alloc>

bool std::locale::operator() | ( | const basic_string< _CharT, _Traits, _Alloc > & | __s1,
|  | const basic_string< _CharT, _Traits, _Alloc > & | __s2 ) const

Definition at line 103 of file locale_classes.tcc.

## ◆ operator=()

const locale & std::locale::operator= | ( | const locale & | __other | ) |
throw | ( | ) |  |  |

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

## ◆ operator==()

bool std::locale::operator== | ( | const locale & | __other | ) | const
throw | ( | ) |  |  |
| 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

## ◆ __try_use_facet

template<typename _Facet>

const _Facet * __try_use_facet | ( | const locale & | __loc | ) |
| friend

Definition at line 117 of file locale_classes.tcc.

## ◆ __use_cache

template<typename _Cache>

friend struct __use_cache
| friend

Definition at line 97 of file locale_classes.h.

## ◆ _Impl

friend class _Impl
| friend

Definition at line 82 of file locale_classes.h.

## ◆ facet

friend class facet
| friend

Definition at line 81 of file locale_classes.h.

## ◆ has_facet

template<typename _Facet>

bool has_facet | ( | const locale & | __loc | ) |
throw | ( | ) |  |  |
| 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.

Definition at line 190 of file locale_classes.tcc.

References locale().

## ◆ use_facet

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.

Definition at line 220 of file locale_classes.tcc.

References locale().

## Member Data Documentation

## ◆ all

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

Definition at line 116 of file locale_classes.h.

## ◆ collate

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

Definition at line 112 of file locale_classes.h.

## ◆ ctype

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

Definition at line 110 of file locale_classes.h.

## ◆ messages

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

Definition at line 115 of file locale_classes.h.

## ◆ monetary

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

Definition at line 114 of file locale_classes.h.

## ◆ none

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

Definition at line 109 of file locale_classes.h.

## ◆ numeric

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

Definition at line 111 of file locale_classes.h.

## ◆ time

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

Definition at line 113 of file locale_classes.h.

The documentation for this class was generated from the following files:

- locale_classes.h
- locale_classes.tcc