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

Members

category classic() facet

global() id locale()

name() operator!=() operator()()

operator=() operator==() ~locale()

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

#include <locale> 

namespace std {
  class locale;
}

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.

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
    };
}

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.

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.

~locale();

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

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.

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

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 

#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

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

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