GNU Info

Info Node: (libc.info)The Elegant and Fast Way

(libc.info)The Elegant and Fast Way


Prev: The Lame Way to Locale Data Up: Locale Information
Enter node , (file) or (file)node

Pinpoint Access to Locale Data
------------------------------

   When writing the X/Open Portability Guide the authors realized that
the `localeconv' function is not enough to provide reasonable access to
locale information.  The information which was meant to be available in
the locale (as later specified in the POSIX.1 standard) requires more
ways to access it.  Therefore the `nl_langinfo' function was introduced.

 - Function: char * nl_langinfo (nl_item ITEM)
     The `nl_langinfo' function can be used to access individual
     elements of the locale categories.  Unlike the `localeconv'
     function, which returns all the information, `nl_langinfo' lets
     the caller select what information it requires.  This is very fast
     and it is not a problem to call this function multiple times.

     A second advantage is that in addition to the numeric and monetary
     formatting information, information from the `LC_TIME' and
     `LC_MESSAGES' categories is available.

     The type `nl_type' is defined in `nl_types.h'.  The argument ITEM
     is a numeric value defined in the header `langinfo.h'.  The X/Open
     standard defines the following values:

    `CODESET'
          `nl_langinfo' returns a string with the name of the coded
          character set used in the selected locale.

    `ABDAY_1'
    `ABDAY_2'
    `ABDAY_3'
    `ABDAY_4'
    `ABDAY_5'
    `ABDAY_6'
    `ABDAY_7'
          `nl_langinfo' returns the abbreviated weekday name.  `ABDAY_1'
          corresponds to Sunday.

    `DAY_1'
    `DAY_2'
    `DAY_3'
    `DAY_4'
    `DAY_5'
    `DAY_6'
    `DAY_7'
          Similar to `ABDAY_1' etc., but here the return value is the
          unabbreviated weekday name.

    `ABMON_1'
    `ABMON_2'
    `ABMON_3'
    `ABMON_4'
    `ABMON_5'
    `ABMON_6'
    `ABMON_7'
    `ABMON_8'
    `ABMON_9'
    `ABMON_10'
    `ABMON_11'
    `ABMON_12'
          The return value is abbreviated name of the month.  `ABMON_1'
          corresponds to January.

    `MON_1'
    `MON_2'
    `MON_3'
    `MON_4'
    `MON_5'
    `MON_6'
    `MON_7'
    `MON_8'
    `MON_9'
    `MON_10'
    `MON_11'
    `MON_12'
          Similar to `ABMON_1' etc., but here the month names are not
          abbreviated.  Here the first value `MON_1' also corresponds
          to January.

    `AM_STR'
    `PM_STR'
          The return values are strings which can be used in the
          representation of time as an hour from 1 to 12 plus an am/pm
          specifier.

          Note that in locales which do not use this time representation
          these strings might be empty, in which case the am/pm format
          cannot be used at all.

    `D_T_FMT'
          The return value can be used as a format string for
          `strftime' to represent time and date in a locale-specific
          way.

    `D_FMT'
          The return value can be used as a format string for
          `strftime' to represent a date in a locale-specific way.

    `T_FMT'
          The return value can be used as a format string for
          `strftime' to represent time in a locale-specific way.

    `T_FMT_AMPM'
          The return value can be used as a format string for
          `strftime' to represent time in the am/pm format.

          Note that if the am/pm format does not make any sense for the
          selected locale, the return value might be the same as the
          one for `T_FMT'.

    `ERA'
          The return value represents the era used in the current
          locale.

          Most locales do not define this value.  An example of a
          locale which does define this value is the Japanese one.  In
          Japan, the traditional representation of dates includes the
          name of the era corresponding to the then-emperor's reign.

          Normally it should not be necessary to use this value
          directly.  Specifying the `E' modifier in their format
          strings causes the `strftime' functions to use this
          information.  The format of the returned string is not
          specified, and therefore you should not assume knowledge of
          it on different systems.

    `ERA_YEAR'
          The return value gives the year in the relevant era of the
          locale.  As for `ERA' it should not be necessary to use this
          value directly.

    `ERA_D_T_FMT'
          This return value can be used as a format string for
          `strftime' to represent dates and times in a locale-specific
          era-based way.

    `ERA_D_FMT'
          This return value can be used as a format string for
          `strftime' to represent a date in a locale-specific era-based
          way.

    `ERA_T_FMT'
          This return value can be used as a format string for
          `strftime' to represent time in a locale-specific era-based
          way.

    `ALT_DIGITS'
          The return value is a representation of up to 100 values used
          to represent the values 0 to 99.  As for `ERA' this value is
          not intended to be used directly, but instead indirectly
          through the `strftime' function.  When the modifier `O' is
          used in a format which would otherwise use numerals to
          represent hours, minutes, seconds, weekdays, months, or
          weeks, the appropriate value for the locale is used instead.

    `INT_CURR_SYMBOL'
          The same as the value returned by `localeconv' in the
          `int_curr_symbol' element of the `struct lconv'.

    `CURRENCY_SYMBOL'
    `CRNCYSTR'
          The same as the value returned by `localeconv' in the
          `currency_symbol' element of the `struct lconv'.

          `CRNCYSTR' is a deprecated alias still required by Unix98.

    `MON_DECIMAL_POINT'
          The same as the value returned by `localeconv' in the
          `mon_decimal_point' element of the `struct lconv'.

    `MON_THOUSANDS_SEP'
          The same as the value returned by `localeconv' in the
          `mon_thousands_sep' element of the `struct lconv'.

    `MON_GROUPING'
          The same as the value returned by `localeconv' in the
          `mon_grouping' element of the `struct lconv'.

    `POSITIVE_SIGN'
          The same as the value returned by `localeconv' in the
          `positive_sign' element of the `struct lconv'.

    `NEGATIVE_SIGN'
          The same as the value returned by `localeconv' in the
          `negative_sign' element of the `struct lconv'.

    `INT_FRAC_DIGITS'
          The same as the value returned by `localeconv' in the
          `int_frac_digits' element of the `struct lconv'.

    `FRAC_DIGITS'
          The same as the value returned by `localeconv' in the
          `frac_digits' element of the `struct lconv'.

    `P_CS_PRECEDES'
          The same as the value returned by `localeconv' in the
          `p_cs_precedes' element of the `struct lconv'.

    `P_SEP_BY_SPACE'
          The same as the value returned by `localeconv' in the
          `p_sep_by_space' element of the `struct lconv'.

    `N_CS_PRECEDES'
          The same as the value returned by `localeconv' in the
          `n_cs_precedes' element of the `struct lconv'.

    `N_SEP_BY_SPACE'
          The same as the value returned by `localeconv' in the
          `n_sep_by_space' element of the `struct lconv'.

    `P_SIGN_POSN'
          The same as the value returned by `localeconv' in the
          `p_sign_posn' element of the `struct lconv'.

    `N_SIGN_POSN'
          The same as the value returned by `localeconv' in the
          `n_sign_posn' element of the `struct lconv'.

    `INT_P_CS_PRECEDES'
          The same as the value returned by `localeconv' in the
          `int_p_cs_precedes' element of the `struct lconv'.

    `INT_P_SEP_BY_SPACE'
          The same as the value returned by `localeconv' in the
          `int_p_sep_by_space' element of the `struct lconv'.

    `INT_N_CS_PRECEDES'
          The same as the value returned by `localeconv' in the
          `int_n_cs_precedes' element of the `struct lconv'.

    `INT_N_SEP_BY_SPACE'
          The same as the value returned by `localeconv' in the
          `int_n_sep_by_space' element of the `struct lconv'.

    `INT_P_SIGN_POSN'
          The same as the value returned by `localeconv' in the
          `int_p_sign_posn' element of the `struct lconv'.

    `INT_N_SIGN_POSN'
          The same as the value returned by `localeconv' in the
          `int_n_sign_posn' element of the `struct lconv'.

    `DECIMAL_POINT'
    `RADIXCHAR'
          The same as the value returned by `localeconv' in the
          `decimal_point' element of the `struct lconv'.

          The name `RADIXCHAR' is a deprecated alias still used in
          Unix98.

    `THOUSANDS_SEP'
    `THOUSEP'
          The same as the value returned by `localeconv' in the
          `thousands_sep' element of the `struct lconv'.

          The name `THOUSEP' is a deprecated alias still used in Unix98.

    `GROUPING'
          The same as the value returned by `localeconv' in the
          `grouping' element of the `struct lconv'.

    `YESEXPR'
          The return value is a regular expression which can be used
          with the `regex' function to recognize a positive response to
          a yes/no question.  The GNU C library provides the `rpmatch'
          function for easier handling in applications.

    `NOEXPR'
          The return value is a regular expression which can be used
          with the `regex' function to recognize a negative response to
          a yes/no question.

    `YESSTR'
          The return value is a locale-specific translation of the
          positive response to a yes/no question.

          Using this value is deprecated since it is a very special
          case of message translation, and is better handled by the
          message translation functions (Note: Message Translation).

          The use of this symbol is deprecated.  Instead message
          translation should be used.

    `NOSTR'
          The return value is a locale-specific translation of the
          negative response to a yes/no question.  What is said for
          `YESSTR' is also true here.

          The use of this symbol is deprecated.  Instead message
          translation should be used.

     The file `langinfo.h' defines a lot more symbols but none of them
     is official.  Using them is not portable, and the format of the
     return values might change.  Therefore we recommended you not use
     them.

     Note that the return value for any valid argument can be used for
     in all situations (with the possible exception of the am/pm time
     formatting codes).  If the user has not selected any locale for the
     appropriate category, `nl_langinfo' returns the information from
     the `"C"' locale.  It is therefore possible to use this function as
     shown in the example below.

     If the argument ITEM is not valid, a pointer to an empty string is
     returned.

   An example of `nl_langinfo' usage is a function which has to print a
given date and time in a locale-specific way.  At first one might think
that, since `strftime' internally uses the locale information, writing
something like the following is enough:

     size_t
     i18n_time_n_data (char *s, size_t len, const struct tm *tp)
     {
       return strftime (s, len, "%X %D", tp);
     }

   The format contains no weekday or month names and therefore is
internationally usable.  Wrong!  The output produced is something like
`"hh:mm:ss MM/DD/YY"'.  This format is only recognizable in the USA.
Other countries use different formats.  Therefore the function should
be rewritten like this:

     size_t
     i18n_time_n_data (char *s, size_t len, const struct tm *tp)
     {
       return strftime (s, len, nl_langinfo (D_T_FMT), tp);
     }

   Now it uses the date and time format of the locale selected when the
program runs.  If the user selects the locale correctly there should
never be a misunderstanding over the time and date format.


automatically generated by info2www version 1.2.2.9