C/C++ User Journal, September 1997
Klaus Kreft & Angelika Langer

Introduction

Computer users all over the world prefer to interact with their systems using their own language and cultural conventions. Cultural differences affect for instance the display of monetary values, of date and time. Just think of the way numeric values are formatted in different cultures: 1,000,000.00 in the US is 1.000.000,00 in Germany and 10,00,000.00 in Nepal. If you aim for high international acceptance of your products you must build into your software the flexibility to adapt to varying requirements that stem from cultural differences. Building into software the potential for worldwide use is called internationalization . It is one of the challenges of software development in these days.

Traditionally, internationalization was achieved by means of C. Standards like POSIX and X/Open define locales and wide character input and output for standard C. Windows 95 and Windows NT have a C interface, too, the Win32 NLSAPI. None of the Win32 NLSAPI interfaces matches any of the standard C interfaces though, and locales are thread-specific in Windows whereas they are provided per process in Unix. These are important differences. The concept and level of support, however, is equivalent. There is a common notion of locales, and the services provided cover almost the same range of i18n problems. Naturally, C++ cannot stand back. The ISO/ANSI C++ standard defines an extensible framework that facilitates internationalization of C++ programs in a portable manner. Its main elements are locales and facets . This article gives an overview of the locale framework and the standard facets defined by ISO/ANSI C++.

Overview

Code Examples
Multiple locales in C and C++
Class locale as defined in the C++ standard
Accessing a Locale's Facet
A locale-sensitive date inserter

A Recap - C Locales

Internationalization requires that developers consciously design and implement their software and avoid hard-coding information or rules that can be localized. For example, careful developers never assume specific conventions for formatting numeric or monetary values, or for displaying date and time, not even for comparing or sorting strings. For internationalization, all culture and language dependencies need to be represented in a kind of language table. Such a table is called a locale . A locale in the C library contains support for the several problem domains. The information in a C locale is composed of categories . Each of the categories represents a set of related information:
 

The C++ Locales

In C++, there is also a class called locale . Different from a C locale, which is a global data structure representing various culture and language dependencies, the C++ class locale is an abstraction that manages facets. Basically, you can think of a C++ locale as a container of facets. This concept is illustrated graphically below:

The Standard Facets

• Numeric. The facets num_get<charT,InputIterator> and num_put<charT, OutputIterator> handle numeric formatting and parsing. The facets provide get() and put() member functions for values of type long , double , etc.

The facet numpunct<charT> specifies numeric formats and punctuation. It provides functions like decimal_point(),thousands_sep(), etc.
• Monetary. The facets money_get<charT,bool,InputIterator> and money_put<charT, bool, OutputIterator> handle formatting and parsing of monetary values. They provide get() and put() member functions that parse or produce a sequence of digits, representing a count of the smallest unit of the currency. For example, the sequence $1,056.23 in a common US locale would yield 105623 units, or the character sequence "105623”.

The facet moneypunct <charT, bool International> handles monetary formats and punctuation like the facet numpunct<charT> handles numeric formats and punctuation. It comes with functions like curr_symbol(), etc.
• Time. The facets time_get<charT,InputIterator> and time_put<charT, OutputIterator> handle date and time formatting and parsing. They provide functions like put(), get_time(), get_date(), get_weekday(), etc.
• Ctype. The facet ctype<charT> encapsulates the Standard C++ Library ctype features for character classification, like tolower(), toupper(), is(ctype_base::space,...) etc.
• Collate. The facet collate<charT> provides features for string collation, including a compare() function used for string comparison.
• Code Conversion. The facet codecvt<internT,externT,stateT> is used when converting from one encoding scheme to another, such as from the multibyte encoding JIS to the wide-character encoding Unicode. The main member functions are in() and out().
• Messages. The facet messages<charT> implements message retrieval. It provides facilities to access message catalogues via open() and close(catalog), and to retrieve messages via get(..., int msgid,...).

C Locale vs. C++ Locales

• The Standard C locale is a global resource: there is only one locale for the entire application. This makes it hard to build an application that has to handle several locales at a time.
• The Standard C++ locale is a class. Numerous instances of class locale can be c reated at will, so you can have as many locale objects as you need.

Let's discuss an application that works with multiple locales. Say, the application runs at a US company that ships products worldwide. Our application's responsibility is printing of invoices to be sent to customers all over the world. Of course, the invoices need to be printed in the customer's native language. Say, the application reads input (the product price list) in US English, and writes output (the invoice) in the customer's native language, say German. Since there is only one global locale in C that affects both input and output, the global locale must change between input and output operations.

Here is the C code that corresponds to the previous example:

float price;

while ( … )  // processing the German invoice

{  setlocale(LC_ALL, "En_US”);

   fscanf(priceFile,”%f”,&price);

   // convert $ to DM accosrding to the current exchange rate

   setlocale(LC_ALL,”De_DE”);

   fprintf(invoiceFile,”%f”,price);

}

Here is the C++ code corresponding to the previous example:

priceFile.imbue(locale("En_US”));

invoiceFile.imbue(locale("De_DE”));

float price;

while ( … )  // processing the German invoice

{  priceFile >> price;

   // convert $ to DM according to the current exchange rate

   invoiceFile << price;

}

Ideally, you would want to have locales be completely independent of each other. Each component shall have a locale of its own, that is unrelated to other locales in your program. This is what you have in C++. You can create infinitely many, independent, light-weight locale objects that you can attach to streams, and exchange between components, or pass around as function arguments for instance.

Relationship between the C Locale and the C++ Locale.

The C locale and the C++ locales are mostly unrelated. There is only one occasion when they effect each other: making a C++ locale global.

The matter is that there is a global locale in C++, as there is in C. You can make a given locale object global by calling locale::global() . The notion of a global C++ locale was added for all those users who do not want to bother with internationalization and rely on internationalized components to pick a sensible default locale. The global C++ locale is often used as the default locale. IOStreams, for instance, uses it; if you do not explicitly imbue your streams with any particular locale object, a snapshot of the global locale is used.

Making a C++ locale object global via locale::global() affects the global C locale in that it results in a call to setlocale() . When this happens, locale-sensitive C functions called from within a C++ program will use the global C++ locale. Conversely, there is no way to affect the C++ locale from within a C program though.

Using C++ Locales and Facets

• Create a locale. First, you create a locale object and stuff all the facets you need into the locale.
• Make available a locale. You can pass around such a locale object to those components that might need it; for instance, you can attach it to a stream and the stream's shift operator will use it.
• Retrieve a facet. When you need a service from the locale, then you ask the locale to give you a handle to the respective facet that contains the service you need.
• Invoke a service. Via this handle you eventually invoke the facet's service.

Creating Locales

1. By name. You can create a locale object from a C locale's external representation. Class locale has a constructor locale::locale(const char* std_name) that takes the name of a C locale. This locale name is like the one you would use for a call to the C library function setlocale() . We have already used this constructor in the example above when we created a US English locale by invoking locale("En_US");. A locale created this way contains all the standard facets and therefore makes available all services and information equivalent to the C locale you specified.
2. The classic locale. The standard C++ library contains a predefined locale object, locale :: classic() , which represents the US English ASCII environment. The is the counterpart to the locale named "C" in the C library.
3. By composition. You can construct a new locale object as a copy of an existing locale object, that has one or several fac et objects replaced. Below are a couple of constructors of class locale that allow creation of locales by composition.

class locale {

public:

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

  template <class Facet> locale(const locale& other, Facet* f);

  template <class Facet> locale(const locale& other

                               ,const locale& one);

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

};

locale loc ( locale::classic(), locale("De_DE”), LC_NUMERIC );

Note that some of the constructors are member templates, which is a language feature that is relatively new to the language and not supported by all compilers.

Immutability of Locales . It's important to understand that locales are immutable objects: once a locale object is created, it cannot be modified, i.e. no facets can be replaced after construction. This makes locales reliable and easy to use and you can safely pass them around between components.

Copying locales. Copying a locale object is a cheap operation. You should have no hesitation about passing locale objects around by value. You may copy locale objects for composing new locale objects; you may pass copies of locale objects as arguments to functions, etc.

Locales are implemented using reference counting and the handle-body-idiom: When a locale object is copied, only its handle is duplicated, a fast and inexpensive action.

The following figure gives an overview of the locale architecture. A locale is a handle to a body that maintains a sequence of pointers to facets. The facets are reference-counted, too.

Accessing a Locale's Facets

template <class Facet> const Facet&     use_facet(const locale&);

template <class Facet> bool             has_facet(const locale&);

The code below demonstrates how these functions are used to get access to a facet and invoke an internationalization service. It is an example of the conversion service tolower() from the ctype facet; all upper case letters of a string read from the standard input stream are converted to lower case letters and are written to the standard output stream.

string in;

cin >> in;

use_facet< ctype<char> >(locale::locale()).tolower(in.c_str(),in.c_str()+in.length());

cout << in;

Explicit Template Argument Specification. The syntax of the call use_facet < ctype<char> > (locale::locale()) might look surprising to you. It is an example of explicit template argument specification, a language feature that is relatively new to C++. Template arguments of a function instantiated from a function template can either be explicitly specified in a call or be deduced from the function arguments. The explicit template argument specification is needed in the call to use_facet above, because the compiler can only deduce a template argument if it is the type of one of the function arguments.

Storing references to facets. Note, that we do not store the reference to the facet, but just use the temporary reference returned by use_facet for immediately calling the desired member function of that facet. This is a safe way of using facets retrieved from a locale. If you kept the reference, you needed to keep track of the object's lifetime and validity. The facet reference does stay valid throughout the lifetime of the locale object it was retrieved from. Moreover, the facet referred to does not even change in any way; it is immutable. However, when the locale goes out of scope, the references obtained from it might become invalid. For this reason it is advisable to combine retrieval and invocation as shown in the example above, unless you have a need for doing differently.

Need for has_facet . Note also, that we did not call has_facet< ctype<char> >() in order to check whether the locale has a ctype facet. In most situations, you do not have to check for the presence of a standard facet object like ctype<char> . This is because locale objects are created by composition; you start with the classic locale or a locale object constructed "by name" from a C locale's external representation. Because you can only add or replace facet objects in a locale object, you cannot compose a locale that misses one of the standard facets. A call to has_facet() is useful, however, when you expect that a certain non-standard facet object should be present in a locale object.

Locales and IOStreams

Here is an example that demonstrates how one can use a stream's locale for printing a date. Let us assume we have a date object of type tm , which is the time structure defined in the standard C library, and we want to print it. Let's assume our program is supposed to run in a German-speaking canton of Switzerland. Hence, we attach a Swiss locale to the standard output stream. When we print the date we expect an output like: 1. September 1989 or 01.09.89

struct tm aDate;                                              

aDate.tm_year = 1989;

aDate.tm_mon = 9;

aDate.tm_mday = 1;                                            



cout.imbue(locale::locale("De_CH”));                          

cout << aDate;

template<class Ostream >

Ostream& operator<< (Ostream& os, const struct tm& date)   

{

  typedef typename Ostream::char_type          char_t;

  typedef typename Ostream::traits_type        traits_t;

  typedef ostreambuf_iterator<char_t,traits_t> outIter_t;        



  locale loc = os.getloc();                                  

 

  const time_put<char_t,outIter_t>& fac = 

     use_facet < time_put<char_t, outIter_t > > (loc);

   

  outIter_t nextpos = fac.put(os,os,os.fill(),&date,'x');



  if (nextpos.failed())                                      

        os.setstate(ios_base::badbit);   

                        

  return os;

There's a lot going on here. Let's discuss the interface of the shift operator first. The code above shows a typical stream inserter. As function arguments it takes a reference to an output stream and a constant reference to the object to be printed. It returns a reference to the same stream. The inserter is a template function because the standard iostreams are templates; they take a character type and an associated traits type describing the character type as template arguments. Naturally, we have the same template parameters for our date inserter.

Now, we need to get hold of the stream's locale object, because we want to use its time formatting facet for output of our date object. As you can see in the code above, the stream's locale object is obtained via the stream's member function getloc() . We retrieve the time formatting facet from the locale via use_facet ; that's an old hat meanwhile. We then call the facet's member function put().

The put() function does all the magic, i.e. it produces a character sequence that represents the equivalent of the date object, formatted according to culture-dependent rules and information. It then inserts the formatted output into the stream via an output iterator. Before we delve into the details of the put() function let us take a look at its return value.

The put() function returns an output iterator that points to the position immediately after the last inserted character. The output iterator used here is an output stream buffer iterator. These are special purpose iterators contained in the standard C++ library that bypass the stream's formatting layer and write directly to the output stream's underlying stream buffer. Output stream buffer iterators have a member function failed() for error indication. So we can check for errors happening during the time formatting. If there was an error, we set the stream's state accordingly which is done via the stream's setstate() function.

Let's return to the facet's formatting service put() and see what arguments it takes. Here is the function's interface:

Here is the actual call:

nextpos = fac.put(os,os,os.fill(),&date,'x');

1. The first parameter is supposed to be an output iterator. We provide an iterator to the stream's underlying stream buffer. The reference os to the output stream is converted to an output iterator, because output stream buffer iterators have a constructor taking an output stream, that is, basic_ostream<charT,traits>& .
2. The second parameter is of type ios_base&, which is one of the stream base classes. The class ios_base contains data for format control (see the section on iostreams for details). The facet object uses this formatting information. We provide the output stream's ios_base part here, using the automatic cast from a reference to an output stream, to a reference to its base class.
3. The third parameter is the fill character. It is used when the output has to be adjusted and blank characters have to be filled in. We provide the stream's fill character, which one can get by calling the stream's fill() function.
4. The fourth parameter is a pointer to a time structure tm from the C library.
5. The fifth parameter is a format character as in the C function strftime() ; the x stands for the locale's appropriate date representation.

Summary
This article gave a brief overview of locales and facets - the components in the standard C++ library for support of internationalization of C++ programs. The functionality of the standard facets contained in the standard C++ library covers traditional C functionality. However, C++ allows multiple locales and overcomes the limitation of one, single global locale that was imposed by C. Naturally, this brief introduction to internationalization support in standard C++ is far from being comprehensive. For instance, we concealed that locales and facets are designed as an open and extensible frame. A description of the framework's architecture and of techniques for extending the framework would fill another article.

Acknowledgements

Code Examples

Example 1: Multiple locales in C and C++

#include <stdio.h>

#include <locale.h>

#include <iostream>

#include <locale>



/*

using namespace ::std;

*/



void c_style_example()

{

        float price;

        int i = 1;



        while ( i-- )  // processing the German invoice

        {        setlocale(LC_ALL, "American_America.1252");

                printf("Type in the amount(as float): ");

                scanf("%f",&price);

                // convert $ to DM according to the current exchange rate

                setlocale(LC_ALL,"German_Germany.1252");

                printf("Der Betrag ist: %f \n",price);

        }

        setlocale(LC_ALL, "American_America.1252");

}



void cplusplus_style_example()

{



        cin.imbue(locale("American_America.1252"));

        cout.imbue(locale("German_Germany.1252"));



        int i= 1;

        float price;



        while ( i-- )  // processing the German invoice

        {      cout << "Type in the amount(as float): ";

                cin >> price;

                // convert $ to DM according to the current exchange rate

                cout << "Der Betrag ist: " << price << endl;

        }

}



int main()

{

        cout << "Test Begin !!!" << endl;



        cout << "***** c_style_example *****" << endl;

        c_style_example();

        cout << endl;



        cout << "***** cplusplus_style_example *****" << endl;

        cplusplus_style_example();

        cout << endl;



        cout << "Test End !!!" << endl;

        cout << endl;

}

Example 2: Class locale as defined in the C++ standard

  
namespace std {

    class locale {

    public:

    // types:

      class facet;

      class id;

      typedef int category;

      static const category   // values assigned here are for exposition only

        none     = 0,

        collate  = 0x010, ctype    = 0x020,

        monetary = 0x040, numeric  = 0x080,

        time     = 0x100, messages = 0x200,

        all = collate | ctype | monetary | numeric | time  | messages;

    // construct/copy/destroy:

      locale() throw()

      locale(const locale& other) throw()

      explicit locale(const char* std_name);

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

      template <class Facet> locale(const locale& other, Facet* f);

      template <class Facet> locale(const locale& other,

                                    const locale& one);

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

     ~locale() throw();  // non-virtual

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

    // locale operations:

      basic_string<char>                  name() const;

      bool operator==(const locale& other) const;

      bool operator!=(const locale& other) const;

      template <class charT, class Traits, class Allocator>

        bool operator()(const basic_string<charT,Traits,Allocator>& s1,

                        const basic_string<charT,Traits,Allocator>& s2) const;

    // global locale objects:

      static       locale  global(const locale&);

      static const locale& classic();

    };

  }

Example 3: Accessing a Locale's Facet

MVC does not support explicit template argument specification. For this reason the standard interface of function templates like use_facet and has_facet cannot be implemented. The library that comes with MVC 4.0 offers a workaround, which is shown below.

#include <iostr
eam>

#include <locale>

#include <sstream>



/*

using namespace ::std;

*/



void tolower_example()

{

        string in;

        cout << "Input string needed(with uppercase characters): ";

        cin >> in;



/* original code:

        if (has_facet< ctype<char> >(locale::locale()))

        {  use_facet< ctype<char> >(locale::locale())

                .tolower(in.c_str(),in.c_str()+in.length());

                cout << in;

        }

*/



// workaround for MVC 4.0

        if (_HAS(locale::locale(), ctype<char>))

        {

                _USE(locale::locale(), ctype<char>).tolower(in.begin(),in.end());

                cout << in;

        }

}

Example 4: A locale-sensitive date inserter

MVC does not support explicit template argument specification. For this reason the standard interface of function templates like use_facet and has_facet cannot be implemented. The library that comes with MVC 4.0 offers a workaround, which is shown below.

MVC does not support default template arguments. For reasons we simplified the example and implemented the inserter only for tiny character streams of type ostream , instead of providing an inserter template, which would be natural.

MVC does not support the standard interface of the time_put facet's put() function; we had to omit one of the arguments.

#include <iostream>

#include <locale>


#include <sstream>



/*

using namespace ::std;

*/





/* original code:



template<class Ostream>

Ostream& operator<< (Ostream& os, const struct tm& date)   

{

  typedef typename Ostream::char_type          char_t;

  typedef typename Ostream::traits_type        traits_t; 

  typedef ostreambuf_iterator<char_t,traits_t> outIter_t;        



  locale loc = os.getloc();                                  

 

  const time_put<char_t,outIter_t>& fac = 

     use_facet < time_put<char_t, outIter_t > > (loc);    

  outIter_t nextpos = fac.put(os,os,os.fill(),&date,'x');

  if (nextpos.failed())                                      

        os.setstate(ios_base::badbit);                           

  return os;

}

*/





// simplified version for MVC 4.0



ostream& operator<< (ostream& os, const struct tm& date)

{

        typedef ostream::char_type charType;

        typedef ostream::traits_type traitsType;

        typedef ostreambuf_iterator<charType,traitsType> outIter_t;

        typedef time_put<charType, outIter_t> time_put_facet_t;

                 



        locale loc = os.getloc();                                    

 

        const time_put<charType,outIter_t>& fac =

 

       /* original code

       use_facet < time_put<charType, bufIter_t > > (loc); 

       */

       // workaround for MVC 4.0

           _USE(loc,time_put_facet_t);

                 

        outIter_t nextpos = fac.put(os,os /* ,os.fill() */ ,&date,'x');

        if (nextpos.failed())                                         

                os.setstate(ios_base::badbit);                            

    return os;

}







void date_inserter_example()

{

        struct tm aDate;                                              

        aDate.tm_year = 1989;

        aDate.tm_mon = 9;

        aDate.tm_mday = 1;                                            



        cout.imbue(locale::locale("german-swiss"));



        cout << "Das Datum: " << aDate << endl;      

}

 
 
 

If you are interested to hear more about this and related topics you might want to check out the following seminar:

Seminar   Effective STL Programming - The Standard Template Library in Depth 4-day seminar (open enrollment and on-site) IOStreams and Locales - Standard C++ IOStreams and Locales in Depth 5-day seminar (open enrollment and on-site)