/** @file ../include/locale.h

@internalComponent

*/

/** @fn  localeconv(void)

@return   The localeconv function returns a pointer to a static object

which may be altered by later calls to setlocale or localeconv.

The localeconv function returns a pointer to a structure which provides parameters for formatting numbers, especially currency values: 

@code

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;

        char    int_p_cs_precedes;

        char    int_n_cs_precedes;

        char    int_p_sep_by_space;

        char    int_n_sep_by_space;

        char    int_p_sign_posn;

        char    int_n_sign_posn;

};

@endcode

The individual fields have the following meanings: 

@code

decimal_point  The decimal point character, except for currency values, cannot be an empty string.  

thousands_sep  The separator between groups of digits before the decimal point, except for currency values.  

grouping  The sizes of the groups of digits, except for currency values.  

int_curr_symbol  The standardized international currency symbol.  

currency_symbol  The local currency symbol.  

mon_decimal_point  The decimal point character for currency values.  

mon_thousands_sep  The separator for digit groups in currency values.  

mon_grouping  Like grouping but for currency values.  

positive_sign  The character used to denote nonnegative currency values, usually the empty string.  

negative_sign  The character used to denote negative currency values, usually a minus sign.  

int_frac_digits  The number of digits after the decimal point in an international-style currency value.  

frac_digits  The number of digits after the decimal point in the local style for currency values.  

p_cs_precedes  1 if the currency symbol precedes the currency value for nonnegative values, 0 if it follows.  

p_sep_by_space  1 if a space is inserted between the currency symbol and the currency value for nonnegative values, 0 otherwise.  

n_cs_precedes  Like p_cs_precedes but for negative values.  

n_sep_by_space  Like p_sep_by_space but for negative values.  

p_sign_posn  The location of the positive_sign with respect to a nonnegative quantity and the currency_symbol, coded as follows: 

@endcode

@code

0  Parentheses around the entire string.  

1  Before the string.  

2  After the string.  

3  Just before currency_symbol.  

4  Just after currency_symbol.  

@endcode

@code

n_sign_posn  

  Like p_sign_posn but for negative currency values.  

int_p_cs_precedes  

  Same as p_cs_precedes, but for internationally formatted monetary quantities.  

int_n_cs_precedes  

  Same as n_cs_precedes, but for internationally formatted monetary quantities.  

int_p_sep_by_space  

  Same as p_sep_by_space, but for internationally formatted monetary quantities.  

int_n_sep_by_space  

  Same as n_sep_by_space, but for internationally formatted monetary quantities.  

int_p_sign_posn  

  Same as p_sign_posn, but for internationally formatted monetary quantities.  

int_n_sign_posn  

  Same as n_sign_posn, but for internationally formatted monetary quantities.  

@endcode

Unless mentioned above, an empty string as a value for a field indicates a zero length result or a value that is not in the current locale. A CHAR_MAX result similarly denotes an unavailable value. 

Note: By default smartphone's monetary  settings will be returned from the localeconv instead of "C" structure

Examples:

@code

#include<stdio.h>

#include<locale.h>

int main()

{

        //Set the locale to German

        char* locale = setlocale(LC_ALL,"de_DE.ISO-8859-1");

        struct lconv* str = NULL;

        //Check whether locale setting is succesful or not

        if(NULL != locale)

        {

              printf("Locale setting is successful

");

              printf("Locale is set to %s

", locale);

              //Get numeric formatting information

              str = localeconv();

              printf("Decimal separator is %s

", str->mon_decimal_point);

              printf("Thousand separator is %s

", str->mon_thousands_sep);

        }

        else

        {

              printf("Locale setting failed

");

        }

        return 0;

}

@endcode

 Output

@code

Locale setting is successful

Locale is set to de_DE.ISO-8859-1

Decimal separator is,

Thousand separator is.

@endcode

@see setlocale()

@see strfmon()

@publishedAll

@externallyDefinedApi

*/

/** @fn  setlocale(int category, const char *locale)

@param category

@param locale

@return   Upon successful completion, setlocale returns the string associated with the specified category for the requested locale. The setlocale function returns NULL and fails to change the locale

if the given combination of category and locale makes no sense.

The setlocale function sets the C library’s notion of natural language formatting style for particular sets of routines. Each such style is called a 'locale' and is invoked using an appropriate name passed as a C string. 

The setlocale function recognizes several categories of routines. These are the categories and the sets of routines they select: 

@code

LC_ALL  Set the entire locale generically.  

LC_COLLATE  Set a locale for string collation routines. Currently locale setting does not have effect on this category.  

LC_CTYPE  This controls recognition of upper and lower case, alphabetic or non-alphabetic characters, and so on. Currently locale setting does not have effect on this category.  

LC_MESSAGES  

  Set a locale for message catalogs. Currently this category is not supported.  

LC_MONETARY  

  Set a locale for formatting monetary values; this affects the localeconv function.  

LC_NUMERIC  Set a locale for formatting numbers. This controls the formatting of decimal points in input and output of floating point numbers in functions such as printf and scanf, as well as values returned by localeconv.  

LC_TIME  Set a locale for formatting dates and times using the strftime function.  

@endcode

Only three locales are defined by default, the empty string which denotes the native environment, and the C and POSIX locales, which denote the C language environment. A locale argument of NULL causes setlocale to return the current locale. By default, C programs start in the C locale. The only function in the library that sets the locale is setlocale; the locale is never changed as a side effect of some other routine. 

Examples:

@code

#include<stdio.h>

#include<locale.h>

int main()

{

        //Set the locale to UK English

        char* locale = setlocale(LC_ALL,"en_GB.ISO-8859-1");

        //Check whether locale setting is succesful or not

        if(NULL != locale)

        {

                printf("Locale setting is successful

");

                printf("Locale is set to %s

", locale);

        }

        else

        {

                printf("Locale setting failed

");

        }

        return 0;

}

@endcode

 Output

@code

Locale setting is successful

Locale is set to en_GB.ISO-8859-1

@endcode

@see localeconv()

@see nl_langinfo()

@publishedAll

@externallyDefinedApi

*/

/** @struct lconv

Includes the following members,

@publishedAll

@externallyDefinedApi

*/

/** @var lconv::decimal_point

The operand is a string containing the symbol that shall be used as the decimal delimiter (radix character) in numeric, non-monetary formatted quantities. This keyword cannot be omitted and cannot be set to the empty string. In contexts where standards limit the decimal_point to a single byte, the result of specifying a multi-byte operand shall be unspecified.

*/

/** @var lconv::thousands_sep

The operand is a string containing the symbol that shall be used as a separator for groups of digits to the left of the decimal delimiter in numeric, non-monetary formatted monetary quantities. In contexts where standards limit the thousands_sep to a single byte, the result of specifying a multi-byte operand shall be unspecified.

*/

/** @var lconv::grouping

Define the size of each group of digits in formatted non-monetary quantities. The operand is a sequence of integers separated by semicolons. Each integer specifies the number of digits in each group, with the initial integer defining the size of the group immediately preceding the decimal delimiter, and the following integers defining the preceding groups. If the last integer is not -1, then the size of the previous group (if any) shall be repeatedly used for the remainder of the digits. If the last integer is -1, then no further grouping shall be performed.

*/

/** @var lconv::int_curr_symbol

The international currency symbol. The operand shall be a four-character string, with the first three characters containing the alphabetic international currency symbol. The international currency symbol should be chosen in accordance with those specified in the ISO 4217 standard. The fourth character shall be the character used to separate the international currency symbol from the monetary quantity.

*/

/** @var lconv::currency_symbol

The string that shall be used as the local currency symbol.

*/

/** @var lconv::mon_decimal_point

The operand is a string containing the symbol that shall be used as the decimal delimiter (radix character) in monetary formatted quantities.

*/

/** @var lconv::mon_thousands_sep

The operand is a string containing the symbol that shall be used as a separator for groups of digits to the left of the decimal delimiter in formatted monetary quantities.

*/

/** @var lconv::mon_grouping

Define the size of each group of digits in formatted monetary quantities. The operand is a sequence of integers separated by semicolons. Each integer specifies the number of digits in each group, with the initial integer defining the size of the group immediately preceding the decimal delimiter, and the following integers defining the preceding groups. If the last integer is not -1, then the size of the previous group (if any) shall be repeatedly used for the remainder of the digits. If the last integer is -1, then no further grouping shall be performed.

*/

/** @var lconv::positive_sign

A string that shall be used to indicate a non-negative-valued formatted monetary quantity.

*/

/** @var lconv::negative_sign

A string that shall be used to indicate a negative-valued formatted monetary quantity.

*/

/** @var lconv::int_frac_digits

An integer representing the number of fractional digits (those to the right of the decimal delimiter) to be written in a formatted monetary quantity using int_curr_symbol.

*/

/** @var lconv::frac_digits

An integer representing the number of fractional digits (those to the right of the decimal delimiter) to be written in a formatted monetary quantity using currency_symbol.

*/

/** @var lconv::p_cs_precedes

An integer set to 1 if the currency_symbol precedes the value for a monetary quantity with a non-negative value, and set to 0 if the symbol succeeds the value.

*/

/** @var lconv::p_sep_by_space

Set to a value indicating the separation of the currency_symbol, the sign string, and the value for a non-negative formatted monetary quantity.

*/

/** @var lconv::n_cs_precedes

An integer set to 1 if the currency_symbol precedes the value for a monetary quantity with a negative value, and set to 0 if the symbol succeeds the value.

*/

/** @var lconv::n_sep_by_space

Set to a value indicating the separation of the currency_symbol, the sign string, and the value for a negative formatted monetary quantity.

*/

/** @var lconv::p_sign_posn

An integer set to a value indicating the positioning of the positive_sign for a monetary quantity with a non-negative value.

*/

/** @var lconv::n_sign_posn

An integer set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity.

*/

/** @var lconv::int_p_cs_precedes

An integer set to 1 if the int_curr_symbol precedes the value for a monetary quantity with a non-negative value, and set to 0 if the symbol succeeds the value.

*/

/** @var lconv::int_n_cs_precedes

An integer set to 1 if the int_curr_symbol precedes the value for a monetary quantity with a negative value, and set to 0 if the symbol succeeds the value.

*/

/** @var lconv::int_p_sep_by_space

Set to a value indicating the separation of the int_curr_symbol, the sign string, and the value for a non-negative internationally formatted monetary quantity.

*/

/** @var lconv::int_n_sep_by_space

Set to a value indicating the separation of the int_curr_symbol, the sign string, and the value for a negative internationally formatted monetary quantity.

*/

/** @var lconv::int_p_sign_posn

An integer set to a value indicating the positioning of the positive_sign for a positive monetary quantity formatted with the international format.

*/

/** @var lconv::int_n_sign_posn

An integer set to a value indicating the positioning of the negative_sign for a negative monetary quantity formatted with the international format.

*/

/** @def LC_ALL

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_COLLATE

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_CTYPE

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_MONETARY

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_NUMERIC

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_TIME	

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def LC_MESSAGES

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@externallyDefinedApi

*/

/** @def _LC_LAST

It shall expand to distinct integer constant expressions, for use as the first argument to the setlocale() function.

@publishedAll

@released

*/