toolchain/gcc/newlib/libc/locale/locale.tex

   1 @node Locale
   2 @chapter Locale (@file{locale.h})
   3
   4 A @dfn{locale} is the name for a collection of parameters (affecting
   5 collating sequences and formatting conventions) that may be different
   6 depending on location or culture.  The @code{"C"} locale is the only
   7 one defined in the ANSI C standard.
   8
   9 This is a minimal implementation, supporting only the required @code{"C"}
  10 value for locale; strings representing other locales are not
  11 honored.  (@code{""} is also accepted; it represents the default locale
  12 for an implementation, here equivalent to @code{"C"}.
  13
  14
  15 @file{locale.h} defines the structure @code{lconv} to collect the
  16 information on a locale, with the following fields:
  17
  18 @table @code
  19 @item char *decimal_point
  20 The decimal point character used to format ``ordinary'' numbers (all
  21 numbers except those referring to amounts of money).  @code{"."} in the
  22 C locale.
  23
  24 @item char *thousands_sep
  25 The character (if any) used to separate groups of digits, when
  26 formatting ordinary numbers.
  27 @code{""} in the C locale.
  28
  29 @item char *grouping
  30 Specifications for how many digits to group (if any grouping is done at
  31 all) when formatting ordinary numbers.  The @emph{numeric value} of each
  32 character in the string represents the number of digits for the next
  33 group, and a value of @code{0} (that is, the string's trailing
  34 @code{NULL}) means to continue grouping digits using the last value
  35 specified.  Use @code{CHAR_MAX} to indicate that no further grouping is
  36 desired.  @code{""} in the C locale.
  37
  38 @item char *int_curr_symbol
  39 The international currency symbol (first three characters), if any, and
  40 the character used to separate it from numbers.
  41 @code{""} in the C locale.
  42
  43 @item char *currency_symbol
  44 The local currency symbol, if any.
  45 @code{""} in the C locale.
  46
  47 @item char *mon_decimal_point
  48 The symbol used to delimit fractions in amounts of money.
  49 @code{""} in the C locale.
  50
  51 @item char *mon_thousands_sep
  52 Similar to @code{thousands_sep}, but used for amounts of money.
  53 @code{""} in the C locale.
  54
  55 @item char *mon_grouping
  56 Similar to @code{grouping}, but used for amounts of money.
  57 @code{""} in the C locale.
  58
  59 @item char *positive_sign
  60 A string to flag positive amounts of money when formatting.
  61 @code{""} in the C locale.
  62
  63 @item char *negative_sign
  64 A string to flag negative amounts of money when formatting.
  65 @code{""} in the C locale.
  66
  67 @item char int_frac_digits
  68 The number of digits to display when formatting amounts of money to
  69 international conventions.
  70 @code{CHAR_MAX} (the largest number representable as a @code{char}) in
  71 the C locale.
  72
  73 @item char frac_digits
  74 The number of digits to display when formatting amounts of money to
  75 local conventions.
  76 @code{CHAR_MAX} in the C locale.
  77
  78 @item char p_cs_precedes
  79 @code{1} indicates the local currency symbol is used before a
  80 @emph{positive or zero} formatted amount of money; @code{0} indicates
  81 the currency symbol is placed after the formatted number.
  82 @code{CHAR_MAX} in the C locale.
  83
  84 @item char p_sep_by_space
  85 @code{1} indicates the local currency symbol must be separated from
  86 @emph{positive or zero} numbers by a space; @code{0} indicates that it
  87 is immediately adjacent to numbers.
  88 @code{CHAR_MAX} in the C locale.
  89
  90 @item char n_cs_precedes
  91 @code{1} indicates the local currency symbol is used before a
  92 @emph{negative} formatted amount of money; @code{0} indicates
  93 the currency symbol is placed after the formatted number.
  94 @code{CHAR_MAX} in the C locale.
  95
  96 @item char n_sep_by_space
  97 @code{1} indicates the local currency symbol must be separated from
  98 @emph{negative} numbers by a space; @code{0} indicates that it
  99 is immediately adjacent to numbers.
 100 @code{CHAR_MAX} in the C locale.
 101
 102 @item char p_sign_posn
 103 Controls the position of the @emph{positive} sign for
 104 numbers representing money.  @code{0} means parentheses surround the
 105 number; @code{1} means the sign is placed before both the number and the
 106 currency symbol; @code{2} means the sign is placed after both the number
 107 and the currency symbol; @code{3} means the sign is placed just before
 108 the currency symbol; and @code{4} means the sign is placed just after
 109 the currency symbol.
 110 @code{CHAR_MAX} in the C locale.
 111
 112 @item char n_sign_posn
 113 Controls the position of the @emph{negative} sign for numbers
 114 representing money, using the same rules as @code{p_sign_posn}.
 115 @code{CHAR_MAX} in the C locale.
 116 @end table
 117
 118 @menu
 119 * setlocale::  Select or query locale
 120 @end menu
 121
 122 @page
 123 @include locale/locale.def