[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

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:

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.

Related Information

The nl_langinfo Subroutine, rpmatch subroutine, setlocale subroutine.

Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and Setting the Locale in AIX 5L Version 5.2 National Language Support Guide and Reference.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]