localeconv Subroutine

Purpose

Sets the locale-dependent conventions of an object.

Library

Standard C Library (libc.a)

Syntax

#include <locale.h>
struct lconv *localeconv ( )

Description

The localeconv subroutine sets the components of an object using the lconv structure. The lconv structure contains values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the current locale.

The fields of the structure with the type char * are strings, any of which (except decimal_point) can point to a null string, which indicates that the value is not available in the current locale or is of zero length. The fields with type char are nonnegative numbers, any of which can be the CHAR_MAX value which indicates that the value is not available in the current locale. The fields of the Iconv structure include the following:

Item Description
char *decimal_point The decimal-point character used to format non-monetary quantities.
char *thousands_sep The character used to separate groups of digits to the left of the decimal point in formatted non-monetary quantities.
char *grouping A string whose elements indicate the size of each group of digits in formatted non-monetary quantities.

The value of the grouping field is interpreted according to the following:

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 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 to the left of the current group.
char *int_curr_symbol The international currency symbol applicable to the current locale, left-justified within a four-character space-padded field. The character sequences are in accordance with those specified in ISO 4217, "Codes for the Representation of Currency and Funds."
char *currency_symbol The local currency symbol applicable to the current locale.
char *mon_decimal_point The decimal point used to format monetary quantities.
char *mon_thousands_sep The separator for groups of digits to the left of the decimal point in formatted monetary quantities.
char *mon_grouping A string whose elements indicate the size of each group of digits in formatted monetary quantities.

The value of the mon_grouping field is interpreted according to the following:

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 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 to the left of the current group.
char *positive_sign The string used to indicate a nonnegative formatted monetary quantity.
char *negative_sign The string used to indicate a negative formatted monetary quantity.
char int_frac_digits The number of fractional digits (those to the right of the decimal point) to be displayed in a formatted monetary quantity.
char p_cs_precedes Set to 1 if the specified currency symbol (the currency_symbol or int_curr_symbol field) precedes the value for a nonnegative formatted monetary quantity and set to 0 if the specified currency symbol follows the value for a nonnegative formatted monetary quantity.
char p_sep_by_space Set to 1 if the currency_symbol or int_curr_symbol field is separated by a space from the value for a nonnegative formatted monetary quantity and set to 0 if the currency_symbol or int_curr_symbol field is not separated by a space from the value for a nonnegative formatted monetary quantity.
char n_cs_precedes Set to 1 if the currency_symbol or int_curr_symbol field precedes the value for a negative formatted monetary quantity and set to 0 if the currency_symbol or int_curr_symbol field follows the value for a negative formatted monetary quantity.
char n_sep_by_space Set to 1 if the currency_symbol or int_curr_symbol field is separated by a space from the value for a negative formatted monetary quantity and set to 0 if the currency_symbol or int_curr_symbol field is not separated by a space from the value for a negative formatted monetary quantity. Set to 2 if the symbol and the sign string are adjacent and separated by a blank character.
char p_sign_posn Set to a value indicating the positioning of the positive sign (the positive_sign fields) for nonnegative formatted monetary quantity.
char n_sign_posn Set to a value indicating the positioning of the negative sign (the negative_sign fields) for a negative formatted monetary quantity.

The values of the p_sign_posn and n_sign_posn fields are interpreted according to the following definitions:

0
Parentheses surround the quantity and the specified currency symbol or international currency symbol.
1
The sign string precedes the quantity and the currency symbol or international currency symbol.
2
The sign string follows the quantity and currency symbol or international currency symbol.
3
The sign string immediately precedes the currency symbol or international currency symbol.
4
The sign string immediately follows the currency symbol or international currency symbol.

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

Country Formats
Italy
Positive Format:
L.1234
Negative Format:
-L.1234
International Format:
ITL.1234
Norway
Positive Format:
krl.234.56
Negative Format:
krl.234.56-
International Format:
NOK 1.234.56
Switzerland
Positive Format:
SFrs.1.234.56
Negative Format:
SFrs.1.234.56C
International Format:
CHF 1.234.56

The following table shows the values of the monetary members of the structure returned by the localeconv subroutine for these countries:

struct localeconv Countries
char *in_curr_symbol
Italy:
"ITL."
Norway:
"NOK"
Switzerland:
"CHF"
char *currency_symbol
Italy:
"L."
Norway:
"kr"
Switzerland:
"SFrs."
char *mon_decimal_point
Italy:
" "
Norway:
"."
Switzerland:
"."
char *mon_thousands_sep
Italy:
"."
Norway:
"."
Switzerland:
"."
char *mon_grouping
Italy:
"\3"
Norway:
"\3"
Switzerland:
"\3"
char *positive_sign
Italy:
" "
Norway:
" "
Switzerland:
" "
char *negative_sign
Italy:
"_"
Norway:
"_"
Switzerland:
"C"
char int_frac_digits
Italy:
0
Norway:
2
Switzerland:
2
char frac_digits
Italy:
0
Norway:
2
Switzerland:
2
char p_cs_precedes
Italy:
1
Norway:
1
Switzerland:
1
char p_sep_by_space
Italy:
0
Norway:
0
Switzerland:
0
char n_cs_precedes
Italy:
1
Norway:
1
Switzerland:
1
char n_sep_by_space
Italy:
0
Norway:
0
Switzerland:
0
char p_sign_posn
Italy:
1
Norway:
1
Switzerland:
1
char n_sign_posn
Italy:
1
Norway:
2
Switzerland:
2

Return Values

A pointer to the filled-in object is returned. In addition, calls to the setlocale subroutine with the LC_ALL, LC_MONETARY or LC_NUMERIC categories may cause subsequent calls to the localeconv subroutine to return different values based on the selection of the locale.

Note: The structure pointed to by the return value is not modified by the program but may be overwritten by a subsequent call to the localeconv subroutine.