13.34 <locale>

The <locale> header declares class and function templates for internationalization and localization. It supports conversion between narrow and wide character sets, character classification and collation, formatting and parsing numbers, currency, dates and times, and retrieving messages. For example, every I/O stream has a locale, which it uses to parse formatted input or to format output.

A locale is an embodiment of a set of cultural conventions, including information about the native character set, how dates are formatted, which symbol to use for currency, and so on. Each set of related attributes is called a facet, which are grouped into categories.

The categories are fixed and defined by the standard (see Table 13-20, under locale::category, for a complete list), and each category has several predefined facets. For example, one of the facets in the time category is time_get<charT, InputIter>, which specifies rules for parsing a time string. You can define additional facets; see the description of the locale::facet class in this section for details.

Many of the facets come in two flavors: plain and named. The plain versions implement default behavior, and the named versions implement the behavior for a named locale. See the locale class later in this section for a discussion of locale names.

When a program starts, the global locale is initialized to the "C" locale, and the standard I/O streams use this locale for character conversions and formatting. A program can change the locale at any time; see the locale class in this section for details.

The C++ <locale> header provides more functionality than the C <clocale>, <cctype>, and <cwchar> headers, especially the ability to extend a locale with your own facets. On the other hand, facets and the locale class template are more complicated than the C functions. For simple character classification in a single locale, you are probably better off using the C functions. If a program must work with multiple locales simultaneously, use the C++ locale template.

codecvt class template

Facet for mapping one character set to another

template <typename internT,typename externT,typename stateT>
class codecvt : public locale::facet, public codecvt_base
{
public:
  typedef internT intern_type;
  typedef externT extern_type;
  typedef stateT state_type;
  explicit codecvt(size_t refs = 0);
  result out(stateT& state, const internT* from, const internT* from_end,
             const internT*& from_next, externT* to, externT* to_limit, 
             externT*& to_next) const;
  result unshift(stateT& state, externT* to, externT* to_limit, 
                 externT*& to_next) const;
  result in(stateT& state, const externT* from, const externT* from_end,
            const externT*& from_next, internT* to, internT* to_limit, 
            internT*& to_next) const;
  int encoding(  ) const throw(  );
  bool always_noconv(  ) const throw(  );
  int length(stateT&, const externT* from, const externT* end, size_t max)
    const;
  int max_length(  ) const throw(  );
  static locale::id id;
protected:
  virtual ~codecvt(  );
  virtual result do_out(stateT& state, const internT* from, 
                        const internT* from_end, const internT*& from_next, 
                        externT* to, externT* to_limit, externT*& to_next)
    const;
  virtual result do_in(stateT& state, const externT* from, 
                       const externT* from_end, const externT*& from_next,
                       internT* to, internT* to_limit, internT*& to_next)
    const;
  virtual result do_unshift(stateT& state, externT* to, externT* to_limit,
                            externT*& to_next) const;
  virtual int do_encoding(  ) const throw(  );
  virtual bool do_always_noconv(  ) const throw(  );
  virtual int do_length(stateT&, const externT* from, const externT* end,
                        size_t max) const;
  virtual int do_max_length(  ) const throw(  );
};

The codecvt template converts characters from one character encoding to another. It is most often used to convert multibyte characters to and from wide characters.

The following template specializations are required by the standard:

codecvt<wchar_t, char, mbstate_t>: Converts multibyte narrow characters to wide characters (in) and wide to multibyte (out)
codecvt<char, char, mbstate_t>: A no-op, "converting" characters to themselves

As with other facets, the public members of codecvt call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public functions, such as in and out, which in turn call do_in and do_out. The descriptions below are for the virtual functions because they do the real work. Imagine that for each virtual function description, there is a corresponding description for a public, nonvirtual function, such as:

bool always_noconv( ) const throw( ): Returns do_always_noconv( )

The following are the virtual, protected members of codecvt:

virtual bool do_always_noconv( ) const throw( )

Returns true if the codecvt object does not actually perform any conversions, that is, in and out are no-ops. For example, for the specialization codecvt<char,char,mbstate_t>, do_always_noconv always returns true.

virtual int do_encoding ( ) const throw( )

Returns the number of externT characters needed to represent a single internT character. If this number is not a fixed constant, the return value is 0. The return value is -1 if externT character sequences are not state-dependent.

virtual result do_in (stateT& state, const externT* from, const externT* from_end, const externT*& from_next, internT* to, internT* to_limit, internT*& to_next) const

Converts externT characters to internT characters. The characters in the range [from, from_end) are converted and stored in the array starting at to. The number of characters converted is the minimum of from_end - from and to_limit - to.

The from_next parameter is set to point to the value in [from, from_end) where the conversion stopped, and to_next points to the value in [to, to_limit) where the conversion stopped. If no conversion was performed, from_next is the same as from, and to_next is equal to to.

The return value is a result, as described in Table 13-19 (under the codecvt_base class).

virtual int do_length (stateT&, const externT* from, const externT* from_end, size_t max) const

Returns the number of externT characters in the range [from, from_end) that are used to convert to internT characters. At most, max internT characters are converted.

virtual int do_max_length ( ) const throw( )

Returns the maximum number of externT characters needed to represent a single internT character, that is, the maximum value that do_length can return when max is 1.

virtual result do_out (stateT& state, const internT* from, const internT* from_end, const internT*& from_next, externT* to, externT* to_limit, externT*& to_next) const

Converts internT characters to externT characters. The characters in the range [from, from_end) are converted and stored in the array starting at to. The number of characters converted is the minimum of from_end - from and to_limit - to.

The return value is a result, as described in Table 13-19 (under codecvt_base class).

virtual result do_unshift (stateT& state, externT* to, externT* to_limit, externT*& to_next) const

Ends a shift state by storing characters in the array starting at to such that the characters undo the state shift given by state. Up to to_limit - to characters are written, and to_next is set to point to one past the last character written into to.

The return value is a result, as described in Table 13-19 (under codecvt_base class).

Example

Example 13-24. Testing whether a locale supports a facet

// The units facet is defined under the locale::facet class (later in this
// section).
   
using std::locale;
if (std::has_facet<units>(locale(  )) {
  // Get a reference to the units facet of the locale.
  const units& u = std::use_facet<units>(locale(  ));
  // Construct a value of 42 cm.
  units::value_t len = u.make(42, units::cm);
  // Print the length (42 cm) in the locale's preferred units.
  u.length_put(std::cout, len);
}

Example

Example 13-25. Using locales for input and output

// Open a file and read floating-point numbers from it, computing the mean.
// Return the mean or 0 if the file contains no data. The data is in the classic
// format, that is, the same format used by C++.
double mean(const char* filename)
{
  std::ifstream in(filename);
  // Force the datafile to be interpreted in the classic locale, so the same
  // datafile can be used everywhere.
  in.imbue(std::locale::classic(  ));
  double sum = 0;
  unsigned long count = 0;
  std::istream_iterator<double> iter(in), end;
  for ( ; iter != end; ++iter) {
    ++count;
    sum += *iter;
  }
  return count == 0 ? 0.0 : sum / count;
}
   
int main(  )
{
  // Print results in the user's native locale.
  std::cout.imbue(std::locale(""));
  std::cout << mean("data.txt") << '\n';
}

The following are the member functions of locale:

locale( ) throw( )

Initializes the locale with a copy of the current global locale. The initial global locale is locale::classic( ).

locale(const locale& other) throw( )

Copies the other locale.

explicit locale(const char* std_name)

Initializes the locale using a standard name. The names "C" and "" (empty string) are always defined, in which "C" is the locale returned by the classic( ) function, and "" identifies the implementation-defined native locale.

An implementation can define additional names. Many C++ implementations use ISO language codes and country codes to identify a locale. For example, the ISO 639 language code for English is "en", and the ISO 3166 country code for the United States is "US", so "en_US" could identify the locale for U.S. English.

locale(const locale& other, const char* std_name, category mask)

Copies the locale from other, except for those categories identified by mask, which are copied from the standard locale identified by std_name. The new locale has a name only if other has a name.

template <typename Facet>

locale(const locale& other, Facet* f)

Copies the locale from other except for the facet Facet, which is obtained from f if f is not null.

locale(const locale& other, const locale& one, category mask)

Copies the locale from other except for those categories identified by mask, which are copied from one. The new locale has a name only if other and one have names.

template <typename Facet>

locale combine(const locale& other) const

Returns a new locale that is a copy of *this, except for Facet, which is copied from other. If other does not support the facet—that is, has_facet<Facet>(other) is false—runtime_error is thrown. The new locale has no name.

basic_string<char> name( ) const

Returns the locale's name or "*" if the locale has no name. The exact contents of the name string are implementation-defined, but you can use the string to construct a new locale that is equal to *this—that is, *this == locale(name( ).c_str( )).

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

Copies other and returns *this.

bool operator==(const locale& other) const

Returns true if the two locales are the same object, one locale object is a copy of the other, or the two locales are named and have the same name. Otherwise, the function returns false.

bool operator!=(const locale& other) const

Returns !(*this == other).

template <typename charT, typename Tr, typename A>

bool operator( )(const basic_string<charT, Tr, A>& s1, const basic_string<charT,Tr,A>& s2) const

Compares two strings using the collate<charT> facet and returns true if s1 < s2. You can use the locale object as a comparator predicate to compare strings. See <string> for more information.

static locale global(const locale& loc)

Sets the global locale to loc and returns the previous global locale. If the new locale has a name, the C locale is set by calling setlocale(LC_ALL, loc.name( ).c_str( )); if the locale does not have a name, the effect on the C locale is implementation-defined.

static const locale& classic( )

Returns a locale that implements the "C" locale.

Example

Example 13-26. A simple facet for working with units of measure

class units : public std::locale::facet
{
public:
  enum length_units {
     length_base=1,
     mm=10, cm=10*mm, m=10*cm, km=1000*m,
     in=254, ft=12*in, yd=3*ft, mi=5280*ft };
   
  typedef double value_t;
   
  // All facets must have a static ID member.
  static std::locale::id id;
   
  // Constructor initializes length_units_ according to local preferences.
  units(  );
   
  // Read a length and its units, and return the length in base units.
  value_t length_get(std::istream& stream) const;
   
  // Convert value to the preferred units, and print the converted value followed
  // by the unit name.
  void length_put(std::ostream& stream, value_t value) const;
   
  // Make a base unit value from a value in src_units.
  value_t make(value_t src_value, length_units src_units)
    const;
  // Convert base units to dst_unit.
  value_t convert(value_t src_value, length_units dst_units)
    const;
  // Return the name of a unit.
  const char* unit_name(length_units units) const;
  // Return the preferred unit for length.
  length_units get_length_unit(  ) const;
private:
  length_units length_units_;
};
   
int main(  )
{
  // Add the units facet to the global locale:
  // 1. Construct a new locale that is a copy of the global locale, with the new
  //    units facet added to it.
  // 2. Set the new locale as the global locale.
  std::locale loc(std::locale(std::locale(  ), new units));
  std::locale::global(loc);
   
  // Now anyone can get the units facet from the global locale.
  const units& u = std::use_facet<units>(std::locale(  ));
  units::value_t size = u.make(42, units::cm);
  u.length_put(std::cout, size);
}

Example

Example 13-27. Reading and writing monetary values

#include <iostream>
#include <locale>
#include <ostream>
   
int main(  )
{
  std::ios_base::iostate err = std::ios_base::goodbit;
  long double value;
  std::cout << "What is your hourly wage? ";
  std::use_facet<std::money_get<char> >(std::locale(  )).get(
    std::cin, std::istreambuf_iterator<char>(  ),
    false, std::cin, err, value);
  if (err)
    std::cerr << "Invalid input\n";
  else {
    std::cout << value << '\n';
    std::cout << "You make ";
    std::use_facet<std::money_put<char> >(std::locale(  )).put(
      std::cout, false, std::cout, std::cout.fill(  ),
      value * 40);
    std::cout << " in a 40-hour work week.\n";
  }
}

As with other facets, the public members call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public function get, which calls do_get. The description below is for the virtual functions because they do the real work. Imagine that for each virtual-function description, there is a corresponding description for a public, nonvirtual function, such as:

iter_type get(iter_type begin, iter_type end, bool intl, ios_base& stream, ios_base::iostate& err, long double& units) const: Calls do_get(begin, end, intl, stream, err, units)

The following are the virtual, protected members of money_get:

virtual iter_type do_get(iter_type begin, iter_type end, bool intl, ios_base& stream, ios_base::iostate& err, long double& units) const

virtual iter_type do_get(iter_type begin, iter_type end, bool intl, ios_base& stream, ios_base::iostate& err, string_type& digits) const

Reads characters in the range [begin, end) and interprets them as a monetary value. If intl is true, the value is parsed using international format; otherwise, local format is used. That is, the intl value is used as the Intl template parameter to moneypunct<char_type, Intl>. If a valid monetary value is read from the input stream, the integral value is stored in units or is formatted as a string in digits. (For example, the input "$1,234.56" yields the units 123456 or the digits "123456".) The digit string starts with an optional minus sign ('-') followed by digits ('0'-'9'), in which each character c is produced by calling ctype<char_type>.widen(c).

If a valid sequence is not found, err is modified to include stream.failbit. If the end of the input is reached without forming a valid monetary value, stream.eofbit is also set.

If the showbase flag is set (stream.flags( ) & stream.showbase is not 0), the currency symbol is required; otherwise, it is optional. Thousands grouping, if the local format supports it, is optional.

The sign of the result is dictated by positive_sign( ) and negative_sign( ) from the moneypunct facet.

The return value is an iterator that points to one past the last character of the monetary value.

13.34 <locale>

See Also

Table 13-19. codecvt_base::result literals

See Also

See Also

See Also

See Also

See Also

See Also

Table 13-20. mask literals for classifying characters

See Also

See Also

See Also

Example

Example 13-24. Testing whether a locale supports a facet

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

Example

Example 13-25. Using locales for input and output

See Also

Table 13-21. Standard categories and their facets

See Also

Example

Example 13-26. A simple facet for working with units of measure

See Also

See Also

See Also

See Also

See Also

See Also

Example

Example 13-27. Reading and writing monetary values

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

Table 13-22. Format specifiers for do_put

See Also

See Also

See Also

See Also

See Also