Technical Reference: Base Operating System and Extensions, Volume 1

localeconv Subroutine

Purpose

Sets the locale-dependent conventions of an object.

Syntax

#include <locale.h>

struct lconv *localeconv ( )

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:

`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	Positive Format	Negative Format	International Format
Italy	L.1234	-L.1234	ITL.1234
Norway	krl.234.56	krl.234.56-	NOK 1.234.56
Switzerland	SFrs.1.234.56	SFrs.1.234.56C	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	Italy	Norway	Switzerland
char *in_curr_symbol	"ITL."	"NOK"	"CHF"
char *currency_symbol	"L."	"kr"	"SFrs."
char *mon_decimal_point	" "	"."	"."
char *mon_thousands_sep	"."	"."	"."
char *mon_grouping	"\3"	"\3"	"\3"
char *positive_sign	" "	" "	" "
char *negative_sign	"_"	"_"	"C"
char int_frac_digits	0	2	2
char frac_digits	0	2	2
char p_cs_precedes	1	1	1
char p_sep_by_space	0	0	0
char n_cs_precedes	1	1	1
char n_sep_by_space	0	0	0
char p_sign_posn	1	1	1
char n_sign_posn	1	2	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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The nl_langinfo (nl_langinfo Subroutine) subroutine, rpmatch subroutine, setlocale subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Locale Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.