Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
locale
- A localization class containing a polymorphic set of
facets.
SYNOPSIS
#include <locale>
class locale;
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 has_facet function,
and the program can obtain a reference to that facet with
the use_facet 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.
INTERFACE
class locale {
public:
// types:
class facet;
class id;
typedef int category;
static const category none, collate, ctype, monetary,
numeric, time, messages,
all = collate | ctype | monetary |
numeric | time | messages;
// construct/copy/destroy:
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(); // non-virtual
const locale& operator=(const locale&) throw();
template <class Facet> locale combine (const locale&);
// locale operations:
basic_string<char> 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;
// global locale objects:
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
};
TYPES
category
Standard facets fall into eight broad categories. These
are: none, collate, ctype, monetary, numeric, time, mes-
sages, and all. all is a combination of all the other
categories except none. Bitwise operations may be applied
to combine or screen these categories. For instance, all
is defined as:
(collate | ctype | monetary | numeric | time | messages)
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,
LC_CTYPE).
facet
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, facet -> ctype<char> ->
my_ctype).
If the refs argument to the constructor is 0, then des-
truction 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 refs is
1, then the object must be explicitly deleted; the locale
does not do so. In this case, the object can be main-
tained across the lifetime of multiple locales.
Copy construction and assignment of this class are not
allowed.
id
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.
CONSTRUCTORS
locale()
throw()
Constructs a default locale object. This locale is the
same as the last argument passed to locale::global(), or,
if that function has not been called, the locale is the
same as the classic "C" locale.
locale(const locale& other)
throw()
Constructs a copy of the locale argument other.
explicit locale(const char* std_name);
Constructs a_locale object on the named locale indicated
by std_name. Throws a runtime_error exception if std_name
is not a valid locale name.
locale(const locale& other, const char* std_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. These facets are obtained from the named locale
identified by std_name. Throws a runtime_error exception
if std_name is not a valid locale name.
The resulting locale has a name only if other has a name.
template <class Facet>
locale(const locale& other, Facet* f);
Constructs a locale object that is a copy of other,
except for the facet of type Facet. Unless f is null, it
is used to supply the missing facet. Otherwise the facet
comes from other as well.
Note that the resulting locale 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 facets that are in the category specified by
category argument cat. These missing facets are obtained
from the other locale argument, one.
Note that the resulting locale has a name only if both
other and one have names.
DESTRUCTORS
~locale();
Destroys the locale.
PUBLIC MEMBER OPERATORS
const locale&
operator=(const locale& other) throw();
Replaces *this with a copy of other. Returns *this.
template <class Facet>
locale combine(const locale& other);
Returns a locale object that is a copy of *this, except
for the facet of type Facet, which is taken from other.
If other does not contain a facet of type Facet, a
runtime_error exception is thrown.
Note that the returned locale does not have a name.
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,Traits>
bool
operator()(const basic_string<charT,Traits>& s1,
const basic_string<charT,Traits>& s2) const;
This operator allows a locale object to be used as a com-
parison 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 to be used with standard algorithms,
such as sort, for localized comparison of strings.
PUBLIC MEMBER FUNCTIONS
basic_string<char>
name() const;
Returns the name of this locale, if it has one; otherwise
returns the string "*".
STATIC PUBLIC MEMBER FUNCTIONS
static const locale&
classic();
Returns a locale with the semantics of the classic "C"
locale.
static locale
global(const locale& loc);
Sets the global locale to loc. 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
std::setlocale(LC_ALL,loc.name().c_str());. Returns
the previous value of locale().
EXAMPLE
//
// locale.cpp
//
#include <string>
#include <vector>
#include <iostream>
#include "codecvte.h"
int main ()
{
using namespace 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>
locale my_loc(loc,new ex_codecvt);
// imbue modified locale onto cout
locale old = cout.imbue(my_loc);
cout << "A \x93 jolly time was had by all" << endl;
cout.imbue(old);
cout << "A jolly time was had by all" << endl;
// Create a vector of strings
vector<string,allocator<void> > v;
v.insert(v.begin(),"antelope");
v.insert(v.begin(),"bison");
v.insert(v.begin(),"elk");
copy(v.begin(),v.end(),
ostream_iterator<string,char,
char_traits<char> >(cout," "));
cout << endl;
// Sort the strings using the locale as a comparitor
sort(v.begin(),v.end(),loc);
copy(v.begin(),v.end(),
ostream_iterator<string,char,
char_traits<char> >(cout," "));
cout << endl;
return 0;
}
SEE ALSO
facets, has_facet, use_facet, specific 'facet'
reference_sections