Apache C++ Standard Library Reference Guide

## locale

Library: Localization

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Constructors
- Destructors
- Public Member Operators
- Public Member Functions
- Static Public Member Functions
- Included Locales
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

category classic() facet | global() id locale() | name() operator!=() operator()() | operator=() operator==() ~locale()

### Summary

A class that serves as a container for a set of polymorphic objects called facets that facilitate internationalization and localization.

### Synopsis

    #include <locale>

    namespace std {
      class locale;
    }

### Description

Class locale provides facilities for the creation and management of a set of objects called facets, indexed by their type, each of which addresses one particular area of internationalization and localization. The default locale object is based on the semantics of the classic C locale. Locale objects can be constructed with semantics of named locales, from parts of two other locale objects, or to include facet objects of user defined types.

Objects of class locale have the following important characteristics:

- Locale objects are immutable. The lifetime of a reference to a facet object obtained from a locale object extends to the point of the call to the assignment operator on the object, if no such call is made, the lifetime of the reference to the facet equals the lifetime of the locale object.

- In the instance that a facet is constructed with `refs > 0`, the lifetime of the facet is not determined by the locale object.

- Successive calls to the same member function of a locale object, or any other objects it contains, with the same arguments, including the implicit `this` argument, always return the same result. This allows a calling program to cache the results of a call for greater efficiency.

- Only a locale object constructed from a name string, or from parts of two named locale objects, has a name. All other locale objects are unnamed. An unnamed locale object is equal only to itself.

In this implementation, a locale object will have a name if it contains no facet objects constructed by user code, and if for each of the six standard categories of facets described below, all facet objects within each category logically belong to the same locale.

A program can determine whether a facet of a particular type is contained in a locale object by using the `has_facet()` function template, and the program can obtain a reference to that facet object with the `use_facet()` function template. These are not member functions, but instead take a locale object as an argument and a type of facet as a template parameter.

### Interface

    namespace std {

      class locale
      {
      public:

        class facet;
        class id;

        typedef int category;

        static const category none;
        static const category collate;
        static const category ctype;
        static const category monetary;
        static const category numeric;
        static const category time;
        static const category messages;
        static const category all = collate | ctype | monetary |
                                      numeric | time | messages;

        locale() throw();
        locale(const locale&) throw();
        explicit locale(const char*);
        locale(const locale&, const char*, category);
        template <class Facet>
        locale(const locale&, Facet*);
        locale(const locale&, const locale&, category);
        ~locale() throw();
        const locale& operator=(const locale&) throw();
        template <class Facet>
        locale combine(const locale&) const;

        string name() const;
        bool operator==(const locale&) const;
        bool operator!=(const locale&) const;
        template <class charT, class Traits, class Allocator>
        bool operator()(const basic_string<charT,Traits,
                                           Allocator>&,
                        const basic_string<charT,Traits,
                                           Allocator>&) const;

        static locale global(const locale&);
        static const locale& classic();
        };

        class locale::facet {
          protected:
            explicit facet(size_t refs = 0);
            virtual ~facet();

          private:
            facet(const facet&);          // not defined
            void operator=(const facet&); // not defined
        };

        class locale::id {
          public:
            id();
          private:
            void operator=(const id&); // not defined
            id(const id&);             // not defined
        };
    }

### Member Types

    category

Each standard facet falls into one of six categories. These are: `collate`,`ctype`, `monetary`, `numeric`, `time`, and `messages`. In addition, the category `all` represents a set that includes all of the six categories. The `none` category represents the empty set of categories. Bitwise operations may be applied to combine or screen these categories. For instance, `all` is defined as:

`(collate | ctype | monetary | numeric | time | messages)`

Table 20 lists the standard facet types belonging to each category.

#### Table 20: Standard facet types

Category | Constant | Standard Facet Type
`collate` | `LC_COLLATE` | `collate<charT>, collate_byname<charT>`
`ctype` | `LC_CTYPE` | `codecvt<IntT, ExtT, stateT>, codecvt_byname<IntT, ExtT, stateT>, ctype<charT>, ctype_byname<charT>`
`monetary` | `LC_MONETARY` | `moneypunct<charT, bool>, moneypunct_byname<charT, bool>, money_get<C, InputIterator>, money_put<C, OutputIterator>`
`numeric` | `LC_NUMERIC` | `numpunct<charT>, numpunct_byname<charT>, num_get<C, InputIterator>, num_put<C, OutputIterator>`
`time` | `LC_TIME` | `time_get<charT, InputIterator>, time_put<charT, OutputIterator>, time_get_byname<charT, InputIterator>, time_put_byname<charT, OutputIterator>`
`messages` | `LC_MESSAGES` | `messages<charT>, messages_byname<charT>`

locale member functions that take a category argument accept the eight constants above, values obtained by OR-ing two or more of the constants above, or one of the `LC_XXX` constants defined in `<clocale>` (for example, `LC_CTYPE`).

    facet

Base class for all facets. This class exists primarily to allow for reference counting services to derived classes. All facet types, whether standard or user-defined, must derive from it, either directly or indirectly by deriving from another facet type that derives from it.

Specializations of the standard facet types listed in the table below are provided as follows:

- Where the template parameter `charT` or `IntT` appears in a type, specializations on `char` and `wchar_t` are provided.

- Where the template parameter `ExtT` appears in a type, the specialization on `char` is provided.

- Where the template parameter `stateT` appears in a type, the specialization on `mbstate_t` is provided.

- Where the template parameter `bool` appears in a type, specializations on `false` and `true` are provided.

- Where the template parameter `InputIterator` or `OutputIterator` appears in a type, specializations on any type that satisfies the requirements of `InputIterator` or `OutputIterator`, respectively, are provided.

- Where the template parameter `C` appears in a type, specializations on any type on which iostream templates may be instantiated are provided.

The protected constructor

`explicit facet(size_t refs = 0);`

constructs a `facet` sub-object.

The `refs` argument is set to the initial value of the object's reference count.

An object `f` of a class derived from `facet` constructed with `(refs == 0)` that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling `delete static_cast<locale::facet*>(&f)`.

A facet object constructed with `(refs != 0)` will not be destroyed by any locale objects in which it may have been installed.

Copy construction and assignment of this class are not allowed.

    id

Type used to index facets in the locale container. Every facet type must contain an accessible static member of this type. The member uniquely identifies the type of facet to the locale object in which it may be installed.

Copy construction and assignment of this type are not allowed.

### Constructors

    locale() throw();

Constructs a default locale object as a snapshot of the global locale object. This object is a copy of the last argument passed to`locale::global()`, or, if that function has not been called, a copy of the object representing the classic C locale returned from `locale::classic()`.

    locale(const locale& other) throw();

Constructs a copy of the locale argument `other`. Constructing a copy of a locale object is an inexpensive operation involving only incrementing a reference count of the source object.

    explicit locale(const char* name);

Constructs a locale object using the locale name given by `name.` Throws a runtime_error exception if `name` is not a valid locale name or if it is `0`. Valid locale names are "`C`", "`POSIX`", "", and a set of values accepted by the C library function `setlocale()` declared in `<clocale>`, including combined locale names. Additionally, the name can be a simple canonical name referring to a locale file created by the `localedef` utility and found in the directory specified by the environment variable `${RWSTD_LOCALE_ROOT}`. Finally, the name can refer to a locale object constructed by combining facet categories from two or more distinct locale objects.

The format of a simple canonical locale name is as follows:

`language[_territory][.codeset][@modifiers]`

`language` - 2 letter code specified by ISO 639-2
`territory` - 2 or 3 letter code specified by ISO 3166
`codeset` - name of the character set assigned by IANA
`modifiers` - a set of optional codes

The format of a combined locale name is as follows:

`LC_COLLATE=a[;LC_CTYPE=b[;LC_MONETARY=c[;LC_NUMERIC=d[;LC_TIME=e[;LC_MESSAGES=f]]]]]`

The letters `a`, `b`, `c`, `d`, `e`, and `f` above stand for arbitrary simple locale names. The `LC_XXX=` part in the name above is optional; if missing, the simple locale names are assumed to be in the order given above. If the `LC_XXX=` part is provided, the components separated by semicolons may appear in any order. When fewer than six components of the name are specified, the remaining components are taken as if `LC_XXX=C`, in other words, the classic C locale, were specified for the missing categories.

The names "`C`" and "`POSIX`" both refer to the classic C locale. The resulting locale object is equal to `locale(setlocale(LC_ALL, "C"))`.

When `name` is the empty string `("")`, the resulting locale object is equal to `locale(setlocale(LC_ALL, ""))`, which means that the resulting locale is determined by the values of the `LANG` and `LC_XXX` environment variables.

    locale(const locale& other, const char* name,
           category cat);

Constructs a locale object that is a copy of `other`, except for the facets that are in the category specified by `cat`, which are obtained from the named locale identified by `name`. The format of `name` is described above. Throws a runtime_error exception if `name` is not a valid locale name or if it is `0`.

The resulting locale object has a name only if `other` has a name, or if `(cat == locale::all)` is `true`.

    template <class Facet>
    locale(const locale& other, Facet* f);

Constructs a locale object that is a copy of `other`, except for the facet object of type `Facet`. If `(f != 0)`, `f` is used to supply the missing facet. Otherwise, the resulting object is a copy of `other`.

Except when `(f == 0)`, the resulting locale object does not have a name.

    locale(const locale& other, const locale& one,
           category cat);

Constructs a locale object that is a copy of `other`, except for facet objects that belong to the category specified by `cat`. These remaining facets are obtained from the locale argument `one`.

If `(cat == locale::all)`, the resulting object is a copy of `one`. If `(cat == locale::none)`, the resulting object is a copy of `other`. Otherwise, the resulting locale has a name only if both `other` and `one` have names.

### Destructors

    ~locale();

Destroys the locale object including any facet objects installed in it whose decremented reference count is `0`.

### Public Member Operators

    const locale&
    operator=(const locale& other) throw();

Replaces `*this` with a copy of `other`. Returns `*this`.

    bool
    operator==(const locale& other) const;

Returns `true` if both `other` and `*this` are the same object, if one is a copy of another, or if both have the same name. Otherwise, returns `false`.

    bool
    operator!=(const locale& other) const;

Returns `!(*this == other)`.

    template <class charT, class Traits, class Allocator>
    bool
    operator()(const basic_string<charT, Traits, Allocator>& s1,
               const basic_string<charT, Traits, Allocator>& s2)
               const;

This operator allows a locale object to be used as a comparison function object for comparing two strings. Returns the result of comparing the two strings using the `compare()` member function of the collate<charT> facet contained in `*this`. Specifically, this function returns the following:

         use_facet< collate<charT> >(*this).compare(s1.data(),
         s1.data()+s1.size(), s2.data(),
         s2.data()+s2.size()) < 0;

This allows a locale object to be used with standard algorithms, such as `sort()`, for localized comparison of strings.

### Public Member Functions

    template <class Facet>
    locale combine(const locale& other) const;

Returns a locale object that is a copy of `*this`, except for the facet of type `Facet`, which is taken from `other`. If `has_facet<Facet>`

`(other)` is `false`, throws runtime_error.

Except when `(*this == other)`, the returned locale does not have a name.

    string
    name() const;

Returns the name of this locale, if it has one; otherwise returns the string `"*"`. Locale names referring to named combined locale objects have a format suitable for the second argument to the C `setlocale()` function declared in `<clocale>`. In particular, `(locale(s) == locale(setlocale(LC_ALL, locale(s).name().c_str())))` is guaranteed to hold for any value of `s` for which `(setlocale(LC_ALL, s) != 0)` holds.

### Static Public Member Functions

    static const locale&
    classic();

Returns a reference to a locale object with the semantics of the classic C locale. The lifetime of the returned reference exceeds that of any other object in a program.

    static locale
    global(const locale& loc);

Assigns `loc` to the global locale object. This causes future uses of the default constructor for locale to return a copy of `loc`. If `loc` has a name, this function has the further effect of calling:

`setlocale(LC_ALL,loc.name().c_str());`

Returns the previous value of `locale()`.

### Included Locales

Table 21 lists the locale definition files that correspond with the the locales of the Apache C++ Standard Library. The names conform to ISO 639:1998, the Code for the Representation of Names of Languages, and ISO 3166, the Country Names and Codes. The Default Codeset gives the name of the codeset or the encoding the locales are designed to be encoded in. The names follow those outlined by IANA in its Assigned Character Set Names. In addition to the listed codeset, each locale can be encoded in UTF-8, and may be able to use other encodings as well.

#### Table 21: Locale definition files

Locale Name | Language | Country | Default Codeset
`af_ZA` | Afrikaans | South Africa | ISO-8859-1
`ar_AE` | Arabic | United Arab Emirates | ISO-8859-6
`ar_BH` | Arabic | Bahrain | ISO-8859-6
`ar_DZ` | Arabic | Algeria | ISO-8859-6
`ar_EG` | Arabic | Egypt | ISO-8859-6
`ar_IN` | Arabic | India | UTF-8
`ar_IQ` | Arabic | Iraq | ISO-8859-6
`ar_JO` | Arabic | Jordan | ISO-8859-6
`ar_KW` | Arabic | Kuwait | ISO-8859-6
`ar_LB` | Arabic | Lebanon | ISO-8859-6
`ar_LY` | Arabic | Libya | ISO-8859-6
`ar_MA` | Arabic | Morocco | ISO-8859-6
`ar_OM` | Arabic | Oman | ISO-8859-6
`ar_QA` | Arabic | Qatar | ISO-8859-6
`ar_SA` | Arabic | Saudi Arabia | ISO-8859-6
`ar_SY` | Arabic | Syria | ISO-8859-6
`ar_SD` | Arabic | Sudan | ISO-8859-6
`ar_TN` | Arabic | Tunisia | ISO-8859-6
`ar_YE` | Arabic | Yemen | ISO-8859-6
`be_BY` | Byelorussian | Byelorussia | CP1251
`bg_BG` | Bulgarian | Bulgaria | CP1251
`br_FR` | Breton | France | ISO-8859-1
`bs_BA` | Bosnian | Bosnia | ISO-8859-2
`ca_ES` | Catalan | Spain | ISO-8859-1
`ca_ES@euro` | Catalan | Spain | ISO-8859-15
`cs_CZ` | Czech | Czech Republic | ISO-8859-2
`cy_GB` | Welsh | Great Britain | ISO-8859-14
`da_DK` | Danish | Denmark | ISO-8859-1
`de_AT` | German | Austria | ISO-8859-1
`de_AT@euro` | German | Austria | ISO-8859-15
`de_BE` | German | Belgium | ISO-8859-1
`de_BE@euro` | German | Belgium | ISO-8859-15
`de_CH` | German | Switzerland | ISO-8859-1
`de_DE` | German | Germany | ISO-8859-1
`de_DE@euro` | German | Germany | ISO-8859-15
`de_LU` | German | Luxembourg | ISO-8859-1
`de_LU@euro` | German | Luxembourg | ISO-8859-15
`el_GR` | Greek | Greece | ISO-8859-7
`en_AU` | English | Australia | ISO-8859-1
`en_BW` | English | Botswana | ISO-8859-1
`en_CA` | English | Canada | ISO-8859-1
`en_DK` | English | Denmark | ISO-8859-1
`en_GB` | English | Great Britain | ISO-8859-1
`en_HK` | English | Hong Kong | ISO-8859-1
`en_IE` | English | Ireland | ISO-8859-1
`en_IE@euro` | English | Ireland | ISO-8859-15
`en_IN` | English | India | UTF-8
`en_NZ` | English | New Zealand | ISO-8859-1
`en_PH` | English | Philippines | ISO-8859-1
`en_SG` | English | Singapore | ISO-8859-1
`en_US` | English | USA | ISO-8859-1
`en_ZA` | English | South Africa | ISO-8859-1
`en_ZW` | English | Zimbabwe | ISO-8859-1
`es_AR` | Spanish | Argentina | ISO-8859-1
`es_BO` | Spanish | Bolivia | ISO-8859-1
`es_CL` | Spanish | Chile | ISO-8859-1
`es_CO` | Spanish | Colombia | ISO-8859-1
`es_CR` | Spanish | Costa Rica | ISO-8859-1
`es_DO` | Spanish | Dominican Republic | ISO-8859-1
`es_EC` | Spanish | Ecuador | ISO-8859-1
`es_ES` | Spanish | Spain | ISO-8859-1
`es_ES@euro` | Spanish | Spain | ISO-8859-15
`es_GT` | Spanish | Guatemala | ISO-8859-1
`es_HN` | Spanish | Honduras | ISO-8859-1
`es_MX` | Spanish | Mexico | ISO-8859-1
`es_NI` | Spanish | Nicaragua | ISO-8859-1
`es_PA` | Spanish | Panama | ISO-8859-1
`es_PE` | Spanish | Peru | ISO-8859-1
`es_PR` | Spanish | Puerto Rico | ISO-8859-1
`es_PY` | Spanish | Paraguay | ISO-8859-1
`es_SV` | Spanish | El Salvador | ISO-8859-1
`es_US` | Spanish | USA | ISO-8859-1
`es_UY` | Spanish | Uruguay | ISO-8859-1
`es_VE` | Spanish | Venezuela | ISO-8859-1
`et_EE` | Estonian | Estonia | ISO-8859-1
`eu_ES` | Basque | Spain | ISO-8859-1
`eu_ES@euro` | Basque | Spain | ISO-8859-15
`fa_IR` | Farsi | Iran | UTF-8
`fi_FI` | Finnish | Finland | ISO-8859-1
`fi_FI@euro` | Finnish | Finland | ISO-8859-15
`fo_FO` | Faroese | Faroe | ISO-8859-1
`fr_BE` | French | Belgium | ISO-8859-1
`fr_BE@euro` | French | Belgium | ISO-8859-15
`fr_CA` | French | Canada | ISO-8859-1
`fr_CH` | French | Switzerland | ISO-8859-1
`fr_FR` | French | France | ISO-8859-1
`fr_FR@euro` | French | France | ISO-8859-15
`fr_LU` | French | Luxembourg | ISO-8859-1
`fr_LU@euro` | French | Luxembourg | ISO-8859-15
`ga_IE` | Irish | Ireland | ISO-8859-1
`ga_IE@euro` | Irish | Ireland | ISO-8859-15
`gl_ES` | Galician | Spain | ISO-8859-1
`gl_ES@euro` | Galician | Spain | ISO-8859-15
`gv_GB` | Gaelic | Great Britain | ISO-8859-1
`he_IL` | Hebrew | Israel | ISO-8859-8
`hi_IN` | Hindu | India | UTF-8
`hr_HR` | Croatian | Croatia | ISO-8859-2
`hu_HU` | Hungarian | Hungary | ISO-8859-2
`id_ID` | Indonesian | Indonesia | ISO-8859-1
`is_IS` | Icelandic | Iceland | ISO-8859-1
`it_CH` | Italian | Switzerland | ISO-8859-1
`it_IT` | Italian | Italy | ISO-8859-1
`it_IT@euro` | Italian | Italy | ISO-8859-15
`iw_IL` | Hebrew | Israel | ISO-8859-8
`ja_JP` | Japanese | Japan | EUC-JP
`ja_JP` | Japanese | Japan | UTF-8
`ja_JP` | Japanese | Japan | Shift_JIS
`ka_GE` | Georgian | Georgia | GEORGIAN-PS
`kl_GL` | Greenlandic | Greenland | ISO-8859-1
`ko_KR` | Korean | Korea | EUC-KR
`ko_KR` | Korean | Korea | UTF-8
`kw_GB` | Cornish | Great Britain | ISO-8859-1
`lt_LT` | Lithuanian | Lithuania | ISO-8859-13
`lv_LV` | Latvian | Latvia | ISO-8859-13
`mi_NZ` | Maori | New Zealand | ISO-8859-13
`mk_MK` | Macedonian | Macedonia | ISO-8859-5
`mr_IN` | Marathi | India | UTF-8
`ms_MY` | Malay | Malaysia | ISO-8859-1
`mt_MT` | Maltese | Malta | ISO-8859-3
`nl_BE` | Dutch | Belgium | ISO-8859-1
`nl_BE@euro` | Dutch | Belgium | ISO-8859-15
`nl_NL` | Dutch | Netherlands | ISO-8859-1
`nl_NL@euro` | Dutch | Netherlands | ISO-8859-15
`nn_NO` | Nynorsk | Norway | ISO-8859-1
`no_NO` | Norwegian | Norway | ISO-8859-1
`oc_FR` | Occitan | France | ISO-8859-1
`pl_PL` | Polish | Poland | ISO-8859-2
`pt_BR` | Portuguese | Brazil | ISO-8859-1
`pt_PT` | Portuguese | Portugal | ISO-8859-1
`pt_PT@euro` | Portuguese | Portugal | ISO-8859-15
`ro_RO` | Romanian | Romania | ISO-8859-2
`ru_RU` | Russian | Russia | ISO-8859-5
`ru_RU` | Russian | Russia | KOI8-R
`ru_UA` | Russian | Ukraine | KOI8-U
`sk_SK` | Slovak | Slovakia | ISO-8859-2
`sl_SI` | Slovenian | Slovenia | ISO-8859-2
`sq_AL` | Albanian | Albania | ISO-8859-1
`sr_YU` | Serbian | Yugoslavia | ISO-8859-2
`sr_YU@cyrillic` | Serbian | Yugoslavia | ISO-8859-5
`sv_FI` | Swedish | Finland | ISO-8859-1
`sv_FI@euro` | Swedish | Finland | ISO-8859-15
`sv_SE` | Swedish | Sweden | ISO-8859-1
`ta_IN` | Tamil | India | UTF-8
`te_IN` | Telgu | India | UTF-8
`tg_TJ` | Tadjik | Tadjikistan | KOI8-T
`th_TH` | Thai | Thailand | TIS-620
`tl_PH` | Tagalog | Philippines | ISO-8859-1
`tr_TR` | Turkish | Turkey | ISO-8859-9
`uk_UA` | Ukrainian | Ukraine | KOI8-U
`ur_PK` | Urdu | Pakistan | UTF-8
`uz_UZ` | Uzbek | Uzbekistan | ISO-8859-1
`vi_VN` | Vietnamese | Vietnam | UTF-8
`yi_US` | Yiddish | USA | CP1255
`zh_CN` | Chinese | China | GB2312
`zh_CN` | Chinese | China | GB18030
`zh_CN` | Chinese | China | GBK
`zh_HK` | Chinese | China | BIG5-HKSCS
`zh_TW` | Chinese | China | BIG5
`zh_TW` | Chinese | China | EUC-TW

### Example

    #include <algorithm>   // for copy, sort
    #include <iostream>    // for cout
    #include <iterator>    // for ostream_iterator
    #include <string>      // for string
    #include <vector>      // for vector

    #include <codecvte.h>

    int main ()
    {
        std::locale loc;  // Default locale

        // Construct new locale using default locale plus
        // user defined codecvt facet
        // This facet converts from ISO Latin
        // Alphabet No. 1 (ISO 8859-1) to
        // U.S. ASCII code page 437
        // This facet replaces the default for
        // codecvt<char,char,mbstate_t>
        std::locale my_loc (loc, new ex_codecvt);

        // imbue modified locale onto cout
        std::locale old = std::cout.imbue (my_loc);
        std::cout << "A \x93 jolly time was had by all" <<
                std::endl;

        std::cout.imbue (old);
        std::cout << "A jolly time was had by all" << std::endl;

        // Create a vector of strings
        std::vector<std::string, std::allocator<std::string> > v;
        v.insert (v.begin(), "antelope");
        v.insert (v.begin(), "bison");
        v.insert (v.begin(), "elk");

        typedef std::ostream_iterator<std::string, char,
                std::char_traits<char> >
            Iter;

        std::copy (v.begin (), v.end (), Iter (std::cout, " "));
        std::cout << std::endl;

        // Sort the strings using the locale as a comparitor
        std::sort (v.begin (), v.end (), loc);

        std::copy (v.begin (), v.end (), Iter (std::cout," "));

        std::cout << std::endl;

        return 0;
    }

    Program Output:
    Å ô jõlly time wãs hãd by ãll
    A jolly time was had by all
    elk bison antelope
    antelope bison elk

### See Also

Facets, `has_facet()`, `use_facet()`, `localedef`, and specific facet reference sections: collate, collate_byname, ctype, codecvt, ctype_byname, codecvt_byname, moneypunct, moneypunct_byname, money_put, money_get, numpunct, numpunct_byname, num_put, num_get, time_put, time_put_byname, time_get, time_get_byname, messages, messages_byname

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.1.1