locale man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

locale(3C++)			       -			  locale(3C++)

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 con‐
       structed 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, messages, 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  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  refs
   is  1,  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  mul‐
   tiple 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. Oth‐
   erwise 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 comparison 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 con‐
   structor 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

Rogue Wave Software		  02 Apr 1998			  locale(3C++)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net