std::locale

Section: C Library Functions (3)
Updated: Wed Apr 17 2019
Page Index

NAME

std::locale - 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.

SYNOPSIS

Classes

class facet
Localization functionality base class.

The facet class is the base class for a localization feature, such as money, time, and number printing. It provides common support for facets and reference management. "
class id
Facet ID class.

The ID class provides facets with an index used to identify them. Every facet class must define a public static member locale::id, or be derived from a facet that provides this member, otherwise the facet cannot be used in a locale. The locale::id ensures that each class type gets a unique identifier. "

Public Types

typedef int category
Definition of locale::category.

Public Member Functions

locale () throw ()
Default constructor.
locale (const locale &__other) throw ()
Copy 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 std::string &__s)
Named locale constructor.
locale (const locale &__base, const std::string &__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.
template<typename _Facet > locale (const locale &__other, _Facet *__f)
Construct locale with another facet.
~locale () throw ()
Locale destructor.
template<typename _Facet > locale combine (const locale &__other) const
Construct locale with another facet.
_GLIBCXX_DEFAULT_ABI_TAG string name () const
Return locale name.
bool operator!= (const locale &__other) const throw ()
Locale inequality.
template<typename _CharT , typename _Traits , typename _Alloc > bool operator() (const basic_string< _CharT, _Traits, _Alloc > &__s1, const basic_string< _CharT, _Traits, _Alloc > &__s2) 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
Compare two strings according to collate.
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 _Cache > struct __use_cache

class _Impl

class facet

template<typename _Facet > bool has_facet (const locale &) throw ()
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<typename _Facet > const _Facet & use_facet (const locale &)
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. "

Detailed Description

Container class for localization functionality.

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 62 of file locale_classes.h.

Member Typedef Documentation

typedef int std::locale::category

Definition of locale::category.

Definition at line 67 of file locale_classes.h.

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.

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

Copy constructor. Constructs a copy of other.

Parameters:

: __other The locale to copy.

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.

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.

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.

Definition at line 163 of file locale_classes.h.

std::locale::locale (const locale & base, const std::string & s, category __cat) [inline]

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 177 of file locale_classes.h.

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.

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 45 of file locale_classes.tcc.

std::locale::~locale ()

Locale destructor.

Member Function Documentation

static const locale& std::locale::classic () [static]

Return reference to the C locale.

template<typename _Facet > locale std::locale::combine (const locale & __other) const

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 63 of file locale_classes.tcc.

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

_GLIBCXX_DEFAULT_ABI_TAG string std::locale::name () const

Return locale name.

Returns:

: Locale name or '*' if unnamed.

bool std::locale::operator!= (const locale & __other) const [inline]

Locale inequality.

Parameters:

: __other The locale to compare against.

Returns:

: ! (*this == __other)

Definition at line 264 of file locale_classes.h.

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

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.

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.

bool std::locale::operator== (const locale & __other) const

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.

Friends And Related Function Documentation

template<typename _Facet > bool has_facet (const locale &) [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 104 of file locale_classes.tcc.

template<typename _Facet > const _Facet& use_facet (const locale &) [friend]

Return a 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 132 of file locale_classes.tcc.

Member Data Documentation

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.