.\" ident @(#)locale.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH locale 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2locale\fP \ - A localization class containing a polymorphic set of facets. .SH SYNOPSIS .RE .RS 0 #include .br class locale; .SH DESCRIPTION locale is a localization interface and a set of indexed facets, each of which covers one particular localization issue. The default locale object is constructed on the "C" locale. Locales can also be constructed on named locales. A calling program can determine whether a particular facet is contained in a locale by using the \f2has_facet\fP function, and the program can obtain a reference to that facet with the \f2use_facet\fP function. These are not member functions, but instead take a locale object as an argument. locale has several important characteristics. First, successive calls to member functions always return the same result. This allows a calling program to safely cache the results of a call. Only a locale constructed from a name, from parts of two named locales, or from a stream, has a name. All other locales are unnamed. Only named locales may be compared for equality. An unnamed locale is equal only to itself. .SH INTERFACE .br class locale { .br public: .RE .RS 2 // types: .RE .RS 1 class facet; .br class id; .br typedef int category; .br static const category none, collate, ctype, monetary, .RE .RS 25 numeric, time, messages, .br all = collate | ctype | monetary | .RE .RS 31 numeric | time | messages; .RE .RS 2 // construct/copy/destroy: .RE .RS 1 locale() throw() .br locale(const locale&) throw() .br explicit locale(const char*); .br locale(const locale&, const char*, category); .br template locale(const locale&, Facet*); .br locale(const locale&, const locale&, category); .RE .RS 2 ~locale() throw(); // non-virtual .RE .RS 1 const locale& operator=(const locale&) throw(); .br template locale combine (const locale&); .RE .RS 2 // locale operations: .RE .RS 1 basic_string name() const; .br bool operator==(const locale&) const; .br bool operator!=(const locale&) const; .br template .RE .RS 3 bool operator()(const basic_string&, .RE .RS 19 const basic_string&) .RE .RS 19 const; .RE .RS 2 // global locale objects: .RE .RS 1 static locale global(const locale&); .br static const locale& classic(); .RE .RS 0 }; .br .br class locale::facet { .br protected: .RE .RS 1 explicit facet(size_t refs = 0); .br virtual ~facet(); .RE .RS 0 private: .RE .RS 1 facet(const facet&); // not defined .br void operator=(const facet&); // not defined .RE .RS 0 }; .br .br class locale::id { .br public: .RE .RS 1 id(); .RE .RS 0 private: .RE .RS 1 void operator=(const id&); // not defined .br id(const id&); // not defined .RE .RS 0 }; .SH TYPES .br category .RE .RS 3 Standard facets fall into eight broad categories. These are: \f2none, collate, ctype, monetary, numeric, time, messages,\fP and \f2all.\fP \f2all\fP is a combination of all the other categories except \f2none\fP. Bitwise operations may be applied to combine or screen these categories. For instance, \f2all\fP is defined as: \f2(collate | ctype | monetary | numeric | time | messages)\fP locale member functions that take a category argument must be included with one of the above values or with one of the constants from the old C locale (for example, \f2LC_CTYPE\fP). .RE .br facet .RE .RS 3 Base class for facets. This class exists primarily to allow for reference counting services to derived classes. All facets must derive from it, either directly or indirectly (for example, \f2facet -> ctype -> my_ctype\fP). If the \f2refs\fP argument to the constructor is \f20\fP, then destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other hand, if \f2refs\fP is \f21\fP, then the object must be explicitly deleted; the locale does not do so. In this case, the object can be maintained across the lifetime of multiple locales. Copy construction and assignment of this class are not allowed. .RE .br id .RE .RS 3 Type used to index facets in the locale container. Every facet must contain a member of this type. Copy construction and assignment of this type are not allowed. .RE .SH CONSTRUCTORS .br locale() .RE .RS 1 throw() .RE .RS 3 Constructs a default locale object. This locale is the same as the last argument passed to\f2 locale::global()\fP, or, if that function has not been called, the locale is the same as the classic "C" locale. .RE .RE .RS 0 locale(const locale& other) .RE .RS 1 throw() .RE .RS 3 Constructs a copy of the locale argument \f2other\fP. .RE .RE .RS 0 explicit locale(const char* std_name); .RE .RS 3 Constructs a_locale object on the named locale indicated by\f2 std_name\fP. Throws a runtime_error exception if \f2std_name\fP is not a valid locale name. .RE .br locale(const locale& other, const char* std_name, .RE .RS 6 category cat); .RE .RS 3 Constructs a locale object that is a copy of \f2other\fP, except for the facets that are in the category specified by \f2cat\fP. These facets are obtained from the named locale identified by \f2std_name\fP. Throws a \f2runtime_error\fP exception if \f2std_name\fP is not a valid locale name. The resulting locale has a name only if \f2other\fP has a name. .RE .RE .RS 0 template .br locale(const locale& other, Facet* f); .RE .RS 3 Constructs a locale object that is a copy of \f2other\fP, except for the facet of type \f2Facet\fP. Unless \f2f\fP is null, it is used to supply the missing facet. Otherwise the facet comes from \f2other\fP as well. Note that the resulting locale does not have a name. .RE .br locale(const locale& other, const locale& one, .RE .RS 6 category cat); .RE .RS 3 Constructs a locale object that is a copy of \f2other\fP, except for facets that are in the category specified by category argument \f2cat\fP. These missing facets are obtained from the other locale argument, \f2one\fP. Note that the resulting locale has a name only if both \f2other\fP and \f2one\fP have names. .RE .SH DESTRUCTORS .RE .RS 0 ~locale(); .RE .RS 3 Destroys the locale. .RE .SH PUBLIC MEMBER OPERATORS .br const locale& .br operator=(const locale& other) throw(); .RE .RS 3 Replaces \f2*this\fP with a copy of \f2other\fP. Returns \f2*this\fP. .RE .br template .br locale combine(const locale& other); .RE .RS 3 Returns a locale object that is a copy of \f2*this\fP, except for the facet of type \f2Facet\fP, which is taken from \f2other\fP. If \f2other\fP does not contain a facet of type \f2Facet\fP, a runtime_error exception is thrown. Note that the returned locale does not have a name. .RE .br bool .br operator==(const locale& other) const; .RE .RS 3 Returns \f2true\fP if both \f2other\fP and \f2*this\fP are the same object, if one is a copy of another, or if both have the same name. Otherwise returns \f2false\fP. .RE .br bool .br operator!=(const locale& other) const; .RE .RS 3 Returns !\f2(*this == other)\fP .RE .br template .br bool .br operator()(const basic_string& s1, .RE .RS 10 const basic_string& s2) const; .RE .RS 3 This operator allows a locale object to be used as a comparison object for comparing two strings. Returns the result of comparing the two strings using the \f2compare\fP member function of the \f2collate\fP facet contained in \f2*this\fP. Specifically, this function returns the following: .RE .RS 3 use_facet< collate >(*this).compare(s1.data(), .br s1.data()+s1.size(), s2.data(), .br s2.data()+s2.size()) < 0; This allows a \f2locale\fP to be used with standard algorithms, such as \f2sort\fP, for localized comparison of strings. .RE .SH PUBLIC MEMBER FUNCTIONS .RE .RS 0 basic_string .br name() const; .RE .RS 3 Returns the name of this locale, if it has one; otherwise returns the string \f2"*"\fP. .RE .SH STATIC PUBLIC MEMBER FUNCTIONS .br static const locale& .br classic(); .RE .RS 3 Returns a locale with the semantics of the classic "C" locale. .RE .br static locale .br global(const locale& loc); .RE .RS 3 Sets the global locale to \f2loc\fP. This causes future uses of the default constructor for \f2locale\fP to return a copy of \f2loc\fP. If \f2loc\fP has a name, this function has the further effect of calling \f2std::setlocale(LC_ALL,loc.name().c_str());.\fP Returns the previous value of \f2locale()\fP. .RE .SH EXAMPLE .br // .br // locale.cpp .br // .br .RE .RS 1 #include .br #include .br #include .br #include "codecvte.h" .RE .RS 0 .br int main () .RE .RS 1 { .br using namespace std; .RE .RS 0 .RE .RS 1 locale loc; // Default locale .RE .RS 0 .RE .RS 2 // Construct new locale using default locale plus .br // user defined codecvt facet .br // This facet converts from ISO Latin .br // Alphabet No. 1 (ISO 8859-1) to .br // U.S. ASCII code page 437 .br // This facet replaces the default for .br // codecvt .RE .RS 1 locale my_loc(loc,new ex_codecvt); .RE .RS 0 .RE .RS 2 // imbue modified locale onto cout .RE .RS 1 locale old = cout.imbue(my_loc); .br cout << "A \\x93 jolly time was had by all" << endl; .RE .RS 0 .RE .RS 1 cout.imbue(old); .br cout << "A jolly time was had by all" << endl; .RE .RS 0 .RE .RS 2 // Create a vector of strings .RE .RS 1 vector > v; .br v.insert(v.begin(),"antelope"); .br v.insert(v.begin(),"bison"); .br v.insert(v.begin(),"elk"); .RE .RS 0 .RE .RS 1 copy(v.begin(),v.end(), .RE .RS 6 ostream_iterator >(cout," ")); .RE .RS 1 cout << endl; .RE .RS 0 .RE .RS 2 // Sort the strings using the locale as a comparitor .RE .RS 1 sort(v.begin(),v.end(),loc); .RE .RS 0 .RE .RS 1 copy(v.begin(),v.end(), .RE .RS 6 ostream_iterator >(cout," ")); .RE .RS 0 .RE .RS 1 cout << endl; .br return 0; .RE .RS 0 } .SH SEE ALSO facets, has_facet, use_facet, specific_facet_reference_sections