13.9 <clocale>

The <clocale> header (from the C standard <locale.h> header) declares types and functions to support internationalization and localization for the C standard library. C++ also offers <locale>, which has more flexibility and functionality, but at a cost of complexity and overhead.

The various locale settings are grouped into categories. Each category has a macro (named LC_category) to identify the category in a call to setlocale. Ordinarily, you would use LC_ALL to set all the categories at once, but you can pick a category from one locale and another category from a different locale.

int LC_ALL

The LC_ALL macro expands to a constant integer, which sets all categories in a call to setlocale.

int LC_COLLATE

The LC_COLLATE macro expands to a constant integer, which sets the collation order category in a call to setlocale. The collation order is used by functions such as strcoll (in <cstring>).

int LC_CTYPE

The LC_CTYPE macro expands to a constant integer, which sets the character type category in a call to setlocale. The <cctype> functions, such as isalpha, use character type information.

int LC_MONETARY

The LC_MONETARY macro expands to a constant integer, which sets the monetary-formatting category in a call to setlocale. Call localeconv to retrieve this information.

int LC_NUMERIC

The LC_NUMERIC macro expands to a constant integer, which sets the numeric-formatting category in a call to setlocale. I/O functions such as printf (in <cstdio>) use this information to format numbers. Call localeconv to retrieve this information.

int LC_TIME

The LC_TIME macro expands to a constant integer, which sets the time-formatting category in a call to setlocale. The strftime (in <ctime>) function uses this information.

struct lconv {
  char *decimal_point;
  char *thousands_sep;
  char *grouping;
  char *int_curr_symbol;
  char *currency_symbol;
  char *mon_decimal_point;
  char *mon_thousands_sep;
  char *mon_grouping;
  char *positive_sign;
  char *negative_sign;
  char int_frac_digits;
  char frac_digits;
  char p_cs_precedes;
  char p_sep_by_space;
  char n_cs_precedes;
  char n_sep_by_space;
  char p_sign_posn;
  char n_sign_posn;
};

The lconv structure stores information used to format numbers and monetary values. An implementation can add more members to the class and change the order of declaration.

The standard library is responsible for filling an lconv object with values that are appropriate for a locale. Do not modify the lconv object or its data members.

Each locale defines suitable values for the lconv members. The char-type members are all nonnegative integers, in which CHAR_MAX means the information is not available in the current locale. For the char* members, an empty string means the information is not available. The "C" locale uses "." for decimal_point, an empty string ("") for all other char* members, and CHAR_MAX for all char members. All strings are null-terminated.

The localeconv function returns a pointer to the current locale's lconv object.

The following are descriptions of the lconv members:

char* currency_symbol

The currency symbol for the current locale (e.g., "$").

char* decimal_point

The decimal point symbol for the current locale. This member is unique in that it cannot be an empty string. The default is ".".

char frac_digits

The number of digits to appear after the decimal point in monetary formatting.

char* grouping

A string that is interpreted as a series of integers, in which each integer is the number of digits in successive groups of digits for nonmonetary formatting. The value '\0' means to repeat the last grouping for the rest of the value. The value CHAR_MAX means not to group the remaining values. Any other value is the size of a digit group. The first character in the string specifies the size of the rightmost group of digits, the second character in the string specifies the size of the next (moving to the left) group of digits, and so forth. Digit groups are separated by thousands_sep.

A common value is "\3", which means to format digits in groups of three (e.g., "1,234,567").

char* int_curr_symbol

A four-character string, in which the first three characters are the international currency symbol (according to ISO standard 4217:1987), and the fourth character is the separator between the currency symbol and the number. For example, the symbol for United States Dollars is USD. If the locale uses a space as the separator, int_curr_symbol would be "USD ".

char int_frac_digits

The number of digits to appear after the decimal point in an internationally-formatted monetary amount.

char* mon_decimal_point

The monetary decimal point.

char* mon_grouping

The monetary grouping. (This works the same as grouping, except groups are separated by mon_thousands_sep.)

char* mon_thousands_sep

The monetary thousands separator. (This works the same as thousands_sep in monetary groups, as specified by mon_grouping.)

char n_cs_precedes

Equal to 1 if the currency symbol precedes the amount when formatting a negative monetary value. Equal to 0 if the symbol follows the value.

char n_sep_by_space

Equal to 1 if the currency symbol is separated from a negative value by a space. Equal to 0 if there is no space.

char n_sign_posn

The position of the sign for a negative monetary value. Table 13-3 lists all the position values.

Table 13-3. Position values for n_sign_posn and p_sign_posn

Value	Position
0	Parentheses surround the value and the currency symbol.
1	The sign precedes the value and the currency symbol.
2	The sign follows the value and the currency symbol.
3	The sign appears immediately before the currency symbol.
4	The sign appears immediately after the currency symbol.

char* negative_sign

Marker for a negative monetary value (e.g., "-").

char p_cs_precedes

Equal to 1 if the currency symbol precedes the amount when formatting a nonnegative monetary value. Equal to 0 if the symbol follows the value.

char p_sep_by_space

Equal to 1 if the currency symbol is separated from a nonnegative value by a space. Equal to 0 if there is no space.

char p_sign_posn

The position of the sign for a nonnegative monetary value. Table 13-3 lists all the position values.

char* positive_sign

Marker for a nonnegative monetary value.

char* thousands_sep

Thousands separator (e.g., ","), which is used in digit groups, as specified by grouping.

lconv* localeconv(  );

The localeconv function returns a pointer to the current locale's lconv object.

Do not modify the lconv object. A call to localeconv might overwrite the contents of the object returned from an earlier call (or simultaneous call in a multithreaded program). Calls to setlocale for LC_ALL, LC_NUMERIC, or LC_MONETARY categories might also overwrite the contents of the lconv object.

#define NULL  . . .

The NULL macro expands to a null pointer constant. It is defined in several C headers. See its description in <cstddef> for details.

char* setlocale(int category, const char* locale)

The setlocale function sets the locale for a specific category, which you must specify using one of the LC_ macros. Use LC_ALL to set all categories to the same locale.

The locale parameter is the name of the locale. The default for all categories is the "C" locale. The empty string ("") is an implementation-defined native locale. The implementation can define other possible values for locale.

To query the current locale, pass a null pointer as the locale. Note that each category might have a different locale, so, when querying for LC_ALL, the return value might contain multiple locale names.

The return value is a pointer to a string that contains the new locale (or current locale if you are querying with a null locale parameter) for the specified category. If the locale cannot be set, a null pointer is returned.

Do not modify the string returned from setlocale. A call to setlocale might overwrite the contents of the string returned from an earlier call (or simultaneous call in a multithreaded program).