localeconv - change components of locale

Syntax

include <locale.h>

struct lconv *localeconv(void);  

Description 

localeconv() sets the components of a structure of type struct lconv (defined in locale.h) with the values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the current locale.

The *char members of the structure lconv are pointers to strings, any of which (except decimal_point) can point to "", to indicate that the value is not available in the current locale or is of zero length.

The *char members of the structure lconv are non-negative numbers, any of which can assume the value {CHAR_MAX} (see limits.h), to indicate that the value is not available in the current locale.

The members for non-monetary numeric values (LC_NUMERIC) are interpreted as follows:

char *decimal_point

The radix character used to format non-monetary quantities.

char *thousands_sep

The character used to separate groups of digits before the decimal-point character in formatted non-monetary quantities.

char *grouping

A string whose elements taken as one-byte integer values indicate the size of each group of digits in non-monetary quantities (see below).

The members for monetary numeric values (LC_MONETARY) are interpreted as follows:

char *int_curr_symbol

The international currency symbol used in the current locale. The operand consists of a string of four characters: the first three characters contain the alphabetic international currency symbol, as defined in ISO 4217:1897; the fourth character, which immediately precedes the null byte, is the separator between the international currency symbol and the monetary quantity. In the "De.EDF04F@euro" locale the value “EUR“ is entered as an alphabetical currency symbol.

char *currency_symbol

The local currency symbol applicable to the current locale.

char *mon_decimal_point

The radix character used to format monetary quantities. This member is restricted to one byte in the ISO-C standard. If a multi-byte operand is specified, the result is undefined.

char *mon_thousands_sep

The separator for groups of digits before the decimal point in formatted monetary quantities. This member is restricted to one byte in the ISO-C standard. If a multi-byte operand is specified, the result is undefined.

char *mon_grouping

A string whose elements taken as one-byte integer values indicate the size of each group of digits in formatted monetary quantities. The operand consists of a sequence of integers, delimited by semi-colons. Each number specifies the number of positions in each group; the first number indicates the size of the group that immediately precedes the decimal separator, and the following numbers define the preceding groups. If the last number is not equal to -1, the preceding group (if one exists) is repeatedly used for the remaining positions. If the last number is -1, no further grouping is performed (see below).

char *positive_sign

The string used to indicate a non-negative, formatted monetary quantity.

char *negative_sign

The string used to indicate a negative formatted monetary quantity.

char int_frac_digits

The number of decimal places to be displayed in internationally formatted monetary quantities, where int_curr_symbol is used.

char frac_digits

The number of decimal places to be displayed in a formatted monetary quantity, where currency_symbol is used.

char p_cs_precedes

Set to 1 if currency_symbol or int_curr_symbol precedes the value for a non-negative formatted monetary quantity. Set to 0 if either of these symbols follows the value.

char p_sep_by_space

Set to 0 if no space separates the currency_symbol or i int_curr_symbol from the value for a non-negative formatted monetary quantity. Set to 1 if a space separates the symbol from the value, and set to 2 if a space separates the symbol and the sign string, if adjacent.

char n_cs_precedes

If the value of this member is 1, the currency_symbol or int_curr_symbol precedes the value for a negative formatted monetary quantity. Otherwise, the member is set to 0.

char n_sep_by_space

Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a negative formatted monetary quantity. Set to 1 if a space separates the symbol from the value, and set to 2 if a space separates the symbol and the sign string, if adjacent.

char p_sign_posn

This member is set to a value that indicates the position of the positive_sign for a non-negative formatted monetary quantity (see below).

char n_sign_posn

Set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity (see below).

The elements of grouping and mon_grouping are interpreted as follows:

 

CHAR-MAX

No further grouping is to be performed.

 

0

The previous element is to be repeatedly used for the remainder of the digits.

 

other

The integer value is the number of digits that comprise the current group. The next element is examined to determine the size of the next group of digits before the current group.

 

The values of p_sign_posn and n_sign_posn are interpreted as follows: 

 

0

Parentheses surround the quantity and currency_symbol or int_curr_symbol.

 

1

The sign precedes the quantity and currency_symbol or int_curr_symbol.

 

2

The sign follows the quantity and currency_symbol or int_curr_symbol.

 

3

The sign immediately precedes the currency_symbol or int_curr_symbol.

 

4

The sign immediately follows the currency_symbol or int_curr_symbol.

The implementation will behave as if no function calls localeconv(). 

Return val.

Pointer to the structure in which the values were entered

upon successful completion. 

Notes

The structure pointed to by the return value must not be modified by the program, but may be overwritten by a subsequent call to localeconv(). In addition, calls to setlocale() with the categories LC_ALL, LC_MONETARY, or LC_NUMERIC may overwrite the contents of the structure. 

Example

The following table illustrates the rules which may be used by three countries to format monetary quantities:

Country	Positive format	Negative format	International format
Germany	EUR 1.234,56	-EUR 1.234,56	EUR 1.234,56
Norway	kr1.234,56	kr1.234,56-	NOK 1.234,56
Switzerland	SFrs.1,234.56	SFrs.1,234.56C	CHF 1,234.56

For these three countries, the respective values for the monetary members of the structure returned by localeconv() are:

Component value	Germany	Norway	Switzerland
int_curr_symbol	"EUR"	"NOK "	"CHF "
currency_symbol	"?"	"kr"	"SFrs."
mon_decimal_point	","	","	"."
mon_thousands_sep	"."	"."	","
mon_grouping	3;3	"\3"	"\3
positive_sign	""	""	""
negative_sign	"-"	"-"	"C"
int_frac_digits	2	2	2
frac_digits	2	2	2
p_cs_precedes	0	1	1
p_sep_by_space	1	0	0
n_cs_precedes	0	1	1
n_sep_by_space	1	0	0
p_sign_posn	1	1	1
n_sign_posn	1	2	2

See also

isalpha(), isascii(), nl_langinfo(), printf(), scanf(), setlocale(), strcat(), strchr(), strcmp(), strcoll(), strcpy(), strftime(), strlen(), strpbrk(), strspn(), strtok(), strxrfm(), strtod(), langinfo.h, local.h, section “Locale”.