Draft 2002-10-11

<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.

LC_ALL macro

Syntax

int LC_ALL

Description

The LC_ALL macro expands to a constant integer, to be used to set all categories in a call to setlocale.

LC_COLLATE macro

Syntax

int LC_COLLATE

Description

The LC_COLLATE macro expands to a constant integer, to be used to set the collation category in a call to setlocale. The collation order is used by functions such as strcoll.

LC_CTYPE macro

Syntax

int LC_CTYPE

Description

The LC_CTYPE macro expands to a constant integer, to be used to set the character type category in a call to setlocale. The character type information is used by the <cctype> functions such as isalpha.

LC_MONETARY macro

Syntax

int LC_MONETARY

Description

The LC_MONETARY macro expands to a constant integer, to be used to set the monetary formatting category in a call to setlocale. Call localeconv to retrieve this information.

LC_NUMERIC macro

Syntax

int LC_NUMERIC

Description

The LC_NUMERIC macro expands to a constant integer, to be used to set the numeric formatting category in a call to setlocale. I/O functions such as printf use this information to format numbers.

LC_TIME macro

Syntax

int LC_TIME

Description

The LC_TIME macro expands to a constant integer, to be used to set the time formatting category in a call to setlocale. The strftime function uses this information.

lconv structure

Syntax

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;
};

Description

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

Each locale defines suitable values for the lconv members. The char-type members are all non-negative integers, where 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.

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, where each integer is the number of digits in successive groups of digits for non-monetary 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 next character in the string specifies the size of the preceding group. Thus, the grouping string is read in the opposite order of the formatted digits.
A common value is "\3", to format digits in groups of three, e.g., "1,234,567."
char* int_curr_symbol
A four-character string, where the first three characters are the internaltion 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
Monetary decimal point.
char* mon_grouping
Monetary grouping (see grouping).
char* mon_thousands_sep
Monetary thousands separator.
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 currency symbol
2 The sign follows the value and 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 non-negative 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 non-negative value by a space. Equal to 0 if there is no space.
char p_sign_posn
The position of the sign for a non-negative monetary value. Table 13-3 lists all the position values.
char* positive_sign
Marker for a non-negative monetary value.
char* thousands_sep
Thousands separator (e.g., ",").

localeconv function

Syntax

lconv* localeconv();

Description

The localeconv function returns a pointer to the current locale's lconv object. You must not modify the lconv object, and a subsequent call to localeconv might overwrite its contents. Calls to setlocale for LC_ALL, LC_NUMERIC, or LC_MONETARY categories might also overwrite the contents of the lconv object.

NULL macro

Syntax

#define NULL 0

Description

The NULL macro is defined in several C headers. See its description in <cstddef> for details.

setlocale function

Syntax

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

Description

The setlocale function sets the locale for a specific category, which must be one of the LC_ macros.

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 defines other possible values for locale.

To query the current locale, pass NULL as the locale. Note that each category might have a different locale, so the return value might contain multiple locale names.

The return value is a pointer to a string associated with the given category and new locale (or current locale if querying with a NULL locale parameter). If the locale cannot be set, a null pointer is returned.

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