Chapter 16. Locale objects

Chapter 16. Locale objects
Prev	Part I. Core classes	Next

Index

gettextmsg()
Single and plural forms

This is a reference-counted wrapper for the C++ library's localization library:

#include <x/locale.H>

x::locale myLocale;

x::locale is a reference to a reference-counted object that represents a C++ library locale. The default constructor creates a locale object for the current global application locale.

x::locale myLocale(x::locale::create("en_US.utf-8"));

This example creates a reference to an object for an explicitly named locale.

x::locale myLocale(x::locale::create(""));

An empty locale name creates a locale object for the locale specified by the environment variables. x::const_locale is a reference to a constant locale object, that cannot be modified. At present, no methods are defined for modifying an existing locale object, at this time x::locale is converted to x::const_locale without any loss of functionality (but not the other way around, of course).

std::cout << myLocale->name() << std::endl;

std::cout << myLocale->charset() << std::endl;

name() returns the locale's name. name() returns the locale's character set.

myLocale->global();

global() sets the given locale as the applications global locale.

auto locale=x::locale::base::global();

This returns an object representing whatever the current global application locale is.

auto locale=x::locale::base::utf8();

This is a convenience function that returns the C.UTF-8 locale. This is equivalent to invoking x::locale::create("C.UTF-8")

auto locale=x::locale::base::environment();

This is a convenience function that returns the system environment locale. This is equivalent to invoking x::locale::create("")

auto locale=x::locale::base::c();

This is a convenience function that returns the C locale. This is equivalent to invoking x::locale::create("C")

myLocale->imbue(std::cout);

imbue() invokes the imbue() method of the given C++ library object, to imbue the object with the referenced locale.

Note

See ??? regarding portability notes that affect x::locale.

Message catalogs

#include <x/messages.H>

x::messages msgcat=x::messages::create("app");

x::messages is a reference to a reference-counted object that provides access to internationalized message catalogs created by the gettext library.

x::const_messages is a reference to a constant message catalog access object. At this time, none of the referenced objects' method modify the object, so the constant references are equivalent to their non-constant version, in terms of functionality.

gettextmsg()

The gettextmsg() function uses messages catalogs containing messages with placeholders for parameters, then takes the values for those parameters and constructs a complete localized message in a stream-like fashion:

std::cout << x::gettextmsg(msgcat->get("Window size: %1% rows, %2% columns"),
                      nrows, ncols) << std::endl;

The first argument to gettextmsg() is typically a localized string returned by a message catalog's get() method, that contains %n% placeholders. The remaining variadic arguments to gettextmsg() provide the values for each placeholder. Each placeholder gets replaced by the nth variadic parameter. The message catalog may specify a string with placeholders appearing in a different order, the parameters get rearranged accordingly. gettextmsg returns a std::string.

The argument to gettextmsg() is a character string. The result of gettextmsg() can be used used with the “<<”, or assigned to a string, appropriately.

Each formatting parameter may be any class with a copy constructor and a << operator into an output stream. This includes I/O manipulators, which are treated no differently than any other parameter.

For convenience, message catalogs provide a format() method, that employs gettextmsg():

std::cout << msgcat->format("Window size: %1% rows, %2% columns",
                      nrows, ncols) << std::endl;

std::string str=msgcat->format("Window size: %1% rows, %2% columns",
                      nrows, ncols);

Single and plural forms

#include <x/messages.H>

void onthewall(size_t nbeers)
{
    x::messages msgcat(x::messages::create("app"));

    printf(msgcat->get("%d bottle of beer\n",
                       "%d bottles of beer\n", nbeers).c_str(),
        nbeers);
}

A three-argument form of get() implements localization of single and plural forms of a given string. Different locales may use something other than a “1 is singular, all other values are plural” rule. This form of get() returns a localized string that corresponds to the numerical value of the third parameter.

formatn() combines this with gettextmsg:

#include <x/messages.H>

void onthewall(size_t nbeers)
{
    x::messages msgcat(x::messages::create(l, "app"));

    std::cout << msgcat->formatn("%1% bottle of beer",
                                 "%1% bottles of beer", nbeers,
                                 nbeers) << std::endl;
}

This is equivalent to calling the three argument version of get() and then using gettextmsg(). Note that “nbeers” appears twice, in the above example. Its first occurence becomes a parameter to get() that selects the singular or the plural form of a localized string. The second occurence becomes the first formatting parameter, that replaces the “%1%” placeholder.

Prev	Up	Next
Chapter 15. Forking other processes	Table Of Contents	Chapter 17. Parsing command line options