info guile

6.24.5 Accessing Locale Information

It is sometimes useful to obtain very specific information about a locale such as the word it uses for days or months, its format for representing floating-point figures, etc. The (ice-9 i18n) module provides support for this in a way that is similar to the libc functions nl_langinfo () and localeconv () (see accessing locale information from C in The GNU C Library Reference Manual). The available functions are listed below.

Scheme Procedure: locale-encoding [locale]: Return the name of the encoding (a string whose interpretation is system-dependent) of either locale or the current locale.

The following functions deal with dates and times.

Scheme Procedure: locale-day day [locale]
Scheme Procedure: locale-day-short day [locale]
Scheme Procedure: locale-month month [locale]
Scheme Procedure: locale-month-short month [locale]: Return the word (a string) used in either locale or the current locale to name the day (or month) denoted by day (or month), an integer between 1 and 7 (or 1 and 12). The -short variants provide an abbreviation instead of a full name.

Scheme Procedure: locale-am-string [locale]
Scheme Procedure: locale-pm-string [locale]: Return a (potentially empty) string that is used to denote ante meridiem (or post meridiem) hours in 12-hour format.

Scheme Procedure: locale-date+time-format [locale]
Scheme Procedure: locale-date-format [locale]
Scheme Procedure: locale-time-format [locale]
Scheme Procedure: locale-time+am/pm-format [locale]
Scheme Procedure: locale-era-date-format [locale]
Scheme Procedure: locale-era-date+time-format [locale]
Scheme Procedure: locale-era-time-format [locale]: These procedures return format strings suitable to strftime (see section Time) that may be used to display (part of) a date/time according to certain constraints and to the conventions of either locale or the current locale (see the nl_langinfo () items in The GNU C Library Reference Manual).

Scheme Procedure: locale-era [locale]
Scheme Procedure: locale-era-year [locale]: These functions return, respectively, the era and the year of the relevant era used in locale or the current locale. Most locales do not define this value. In this case, the empty string is returned. An example of a locale that does define this value is the Japanese one.

The following procedures give information about number representation.

Scheme Procedure: locale-decimal-point [locale]
Scheme Procedure: locale-thousands-separator [locale]: These functions return a string denoting the representation of the decimal point or that of the thousand separator (respectively) for either locale or the current locale.

Scheme Procedure: locale-digit-grouping [locale]

Return a (potentially circular) list of integers denoting how digits of the integer part of a number are to be grouped, starting at the decimal point and going to the left. The list contains integers indicating the size of the successive groups, from right to left. If the list is non-circular, then no grouping occurs for digits beyond the last group.

For instance, if the returned list is a circular list that contains only 3 and the thousand separator is "," (as is the case with English locales), then the number 12345678 should be printed 12,345,678.

The following procedures deal with the representation of monetary amounts. Some of them take an additional intl? argument (a boolean) that tells whether the international or local monetary conventions for the given locale are to be used.

Scheme Procedure: locale-monetary-decimal-point [locale]
Scheme Procedure: locale-monetary-thousands-separator [locale]
Scheme Procedure: locale-monetary-grouping [locale]: These are the monetary counterparts of the above procedures. These procedures apply to monetary amounts.

Scheme Procedure: locale-currency-symbol intl? [locale]

Return the currency symbol (a string) of either locale or the current locale.

The following example illustrates the difference between the local and international monetary formats:

(define us (make-locale LC_MONETARY "en_US"))
(locale-currency-symbol #f us)
⇒ "-$"
(locale-currency-symbol #t us)
⇒ "USD "

Scheme Procedure: locale-monetary-fractional-digits intl? [locale]: Return the number of fractional digits to be used when printing monetary amounts according to either locale or the current locale. If the locale does not specify it, then #f is returned.

Scheme Procedure: locale-currency-symbol-precedes-positive? intl? [locale]
Scheme Procedure: locale-currency-symbol-precedes-negative? intl? [locale]
Scheme Procedure: locale-positive-separated-by-space? intl? [locale]
Scheme Procedure: locale-negative-separated-by-space? intl? [locale]: These procedures return a boolean indicating whether the currency symbol should precede a positive/negative number, and whether a whitespace should be inserted between the currency symbol and a positive/negative amount.

Scheme Procedure: locale-monetary-positive-sign [locale]
Scheme Procedure: locale-monetary-negative-sign [locale]: Return a string denoting the positive (respectively negative) sign that should be used when printing a monetary amount.

Scheme Procedure: locale-positive-sign-position

Scheme Procedure: locale-negative-sign-position

These functions return a symbol telling where a sign of a positive/negative monetary amount is to appear when printing it. The possible values are:

parenthesize: The currency symbol and quantity should be surrounded by parentheses.
sign-before: Print the sign string before the quantity and currency symbol.
sign-after: Print the sign string after the quantity and currency symbol.
sign-before-currency-symbol: Print the sign string right before the currency symbol.
sign-after-currency-symbol: Print the sign string right after the currency symbol.
unspecified: Unspecified. We recommend you print the sign after the currency symbol.

Finally, the two following procedures may be helpful when programming user interfaces:

Scheme Procedure: locale-yes-regexp [locale]

Scheme Procedure: locale-no-regexp [locale]

Return a string that can be used as a regular expression to recognize a positive (respectively, negative) response to a yes/no question. For the C locale, the default values are typically "^[yY]" and "^[nN]", respectively.

Here is an example:

(use-modules (ice-9 rdelim))
(format #t "Does Guile rock?~%")
(let lp ((answer (read-line)))
  (cond ((string-match (locale-yes-regexp) answer)
         (format #t "High fives!~%"))
        ((string-match (locale-no-regexp) answer)
         (format #t "How about now? Does it rock yet?~%")
         (lp (read-line)))
        (else
         (format #t "What do you mean?~%")
         (lp (read-line)))))

For an internationalized yes/no string output, gettext should be used (see section Gettext Support).

Example uses of some of these functions are the implementation of the number->locale-string and monetary-amount->locale-string procedures (see section Number Input and Output), as well as that the SRFI-19 date and time conversion to/from strings (see section SRFI-19 - Time/Date Library).

This document was generated on April 20, 2013 using texi2html 5.0.