--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/locale.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,578 @@
+
+:mod:`locale` --- Internationalization services
+===============================================
+
+.. module:: locale
+ :synopsis: Internationalization services.
+.. moduleauthor:: Martin von Löwis <martin@v.loewis.de>
+.. sectionauthor:: Martin von Löwis <martin@v.loewis.de>
+
+
+The :mod:`locale` module opens access to the POSIX locale database and
+functionality. The POSIX locale mechanism allows programmers to deal with
+certain cultural issues in an application, without requiring the programmer to
+know all the specifics of each country where the software is executed.
+
+.. index:: module: _locale
+
+The :mod:`locale` module is implemented on top of the :mod:`_locale` module,
+which in turn uses an ANSI C locale implementation if available.
+
+The :mod:`locale` module defines the following exception and functions:
+
+
+.. exception:: Error
+
+ Exception raised when :func:`setlocale` fails.
+
+
+.. function:: setlocale(category[, locale])
+
+ If *locale* is specified, it may be a string, a tuple of the form ``(language
+ code, encoding)``, or ``None``. If it is a tuple, it is converted to a string
+ using the locale aliasing engine. If *locale* is given and not ``None``,
+ :func:`setlocale` modifies the locale setting for the *category*. The available
+ categories are listed in the data description below. The value is the name of a
+ locale. An empty string specifies the user's default settings. If the
+ modification of the locale fails, the exception :exc:`Error` is raised. If
+ successful, the new locale setting is returned.
+
+ If *locale* is omitted or ``None``, the current setting for *category* is
+ returned.
+
+ :func:`setlocale` is not thread safe on most systems. Applications typically
+ start with a call of ::
+
+ import locale
+ locale.setlocale(locale.LC_ALL, '')
+
+ This sets the locale for all categories to the user's default setting (typically
+ specified in the :envvar:`LANG` environment variable). If the locale is not
+ changed thereafter, using multithreading should not cause problems.
+
+ .. versionchanged:: 2.0
+ Added support for tuple values of the *locale* parameter.
+
+
+.. function:: localeconv()
+
+ Returns the database of the local conventions as a dictionary. This dictionary
+ has the following strings as keys:
+
+ +----------------------+-------------------------------------+--------------------------------+
+ | Category | Key | Meaning |
+ +======================+=====================================+================================+
+ | :const:`LC_NUMERIC` | ``'decimal_point'`` | Decimal point character. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'grouping'`` | Sequence of numbers specifying |
+ | | | which relative positions the |
+ | | | ``'thousands_sep'`` is |
+ | | | expected. If the sequence is |
+ | | | terminated with |
+ | | | :const:`CHAR_MAX`, no further |
+ | | | grouping is performed. If the |
+ | | | sequence terminates with a |
+ | | | ``0``, the last group size is |
+ | | | repeatedly used. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'thousands_sep'`` | Character used between groups. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | :const:`LC_MONETARY` | ``'int_curr_symbol'`` | International currency symbol. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'currency_symbol'`` | Local currency symbol. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_cs_precedes/n_cs_precedes'`` | Whether the currency symbol |
+ | | | precedes the value (for |
+ | | | positive resp. negative |
+ | | | values). |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_sep_by_space/n_sep_by_space'`` | Whether the currency symbol is |
+ | | | separated from the value by a |
+ | | | space (for positive resp. |
+ | | | negative values). |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_decimal_point'`` | Decimal point used for |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'frac_digits'`` | Number of fractional digits |
+ | | | used in local formatting of |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'int_frac_digits'`` | Number of fractional digits |
+ | | | used in international |
+ | | | formatting of monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_thousands_sep'`` | Group separator used for |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_grouping'`` | Equivalent to ``'grouping'``, |
+ | | | used for monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'positive_sign'`` | Symbol used to annotate a |
+ | | | positive monetary value. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'negative_sign'`` | Symbol used to annotate a |
+ | | | negative monetary value. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_sign_posn/n_sign_posn'`` | The position of the sign (for |
+ | | | positive resp. negative |
+ | | | values), see below. |
+ +----------------------+-------------------------------------+--------------------------------+
+
+ All numeric values can be set to :const:`CHAR_MAX` to indicate that there is no
+ value specified in this locale.
+
+ The possible values for ``'p_sign_posn'`` and ``'n_sign_posn'`` are given below.
+
+ +--------------+-----------------------------------------+
+ | Value | Explanation |
+ +==============+=========================================+
+ | ``0`` | Currency and value are surrounded by |
+ | | parentheses. |
+ +--------------+-----------------------------------------+
+ | ``1`` | The sign should precede the value and |
+ | | currency symbol. |
+ +--------------+-----------------------------------------+
+ | ``2`` | The sign should follow the value and |
+ | | currency symbol. |
+ +--------------+-----------------------------------------+
+ | ``3`` | The sign should immediately precede the |
+ | | value. |
+ +--------------+-----------------------------------------+
+ | ``4`` | The sign should immediately follow the |
+ | | value. |
+ +--------------+-----------------------------------------+
+ | ``CHAR_MAX`` | Nothing is specified in this locale. |
+ +--------------+-----------------------------------------+
+
+
+.. function:: nl_langinfo(option)
+
+ Return some locale-specific information as a string. This function is not
+ available on all systems, and the set of possible options might also vary across
+ platforms. The possible argument values are numbers, for which symbolic
+ constants are available in the locale module.
+
+
+.. function:: getdefaultlocale([envvars])
+
+ Tries to determine the default locale settings and returns them as a tuple of
+ the form ``(language code, encoding)``.
+
+ According to POSIX, a program which has not called ``setlocale(LC_ALL, '')``
+ runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets
+ it use the default locale as defined by the :envvar:`LANG` variable. Since we
+ do not want to interfere with the current locale setting we thus emulate the
+ behavior in the way described above.
+
+ To maintain compatibility with other platforms, not only the :envvar:`LANG`
+ variable is tested, but a list of variables given as envvars parameter. The
+ first found to be defined will be used. *envvars* defaults to the search path
+ used in GNU gettext; it must always contain the variable name ``LANG``. The GNU
+ gettext search path contains ``'LANGUAGE'``, ``'LC_ALL'``, ``'LC_CTYPE'``, and
+ ``'LANG'``, in that order.
+
+ Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
+ *language code* and *encoding* may be ``None`` if their values cannot be
+ determined.
+
+ .. versionadded:: 2.0
+
+
+.. function:: getlocale([category])
+
+ Returns the current setting for the given locale category as sequence containing
+ *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
+ except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
+
+ Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
+ *language code* and *encoding* may be ``None`` if their values cannot be
+ determined.
+
+ .. versionadded:: 2.0
+
+
+.. function:: getpreferredencoding([do_setlocale])
+
+ Return the encoding used for text data, according to user preferences. User
+ preferences are expressed differently on different systems, and might not be
+ available programmatically on some systems, so this function only returns a
+ guess.
+
+ On some systems, it is necessary to invoke :func:`setlocale` to obtain the user
+ preferences, so this function is not thread-safe. If invoking setlocale is not
+ necessary or desired, *do_setlocale* should be set to ``False``.
+
+ .. versionadded:: 2.3
+
+
+.. function:: normalize(localename)
+
+ Returns a normalized locale code for the given locale name. The returned locale
+ code is formatted for use with :func:`setlocale`. If normalization fails, the
+ original name is returned unchanged.
+
+ If the given encoding is not known, the function defaults to the default
+ encoding for the locale code just like :func:`setlocale`.
+
+ .. versionadded:: 2.0
+
+
+.. function:: resetlocale([category])
+
+ Sets the locale for *category* to the default setting.
+
+ The default setting is determined by calling :func:`getdefaultlocale`.
+ *category* defaults to :const:`LC_ALL`.
+
+ .. versionadded:: 2.0
+
+
+.. function:: strcoll(string1, string2)
+
+ Compares two strings according to the current :const:`LC_COLLATE` setting. As
+ any other compare function, returns a negative, or a positive value, or ``0``,
+ depending on whether *string1* collates before or after *string2* or is equal to
+ it.
+
+
+.. function:: strxfrm(string)
+
+ .. index:: builtin: cmp
+
+ Transforms a string to one that can be used for the built-in function
+ :func:`cmp`, and still returns locale-aware results. This function can be used
+ when the same string is compared repeatedly, e.g. when collating a sequence of
+ strings.
+
+
+.. function:: format(format, val[, grouping[, monetary]])
+
+ Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
+ The format follows the conventions of the ``%`` operator. For floating point
+ values, the decimal point is modified if appropriate. If *grouping* is true,
+ also takes the grouping into account.
+
+ If *monetary* is true, the conversion uses monetary thousands separator and
+ grouping strings.
+
+ Please note that this function will only work for exactly one %char specifier.
+ For whole format strings, use :func:`format_string`.
+
+ .. versionchanged:: 2.5
+ Added the *monetary* parameter.
+
+
+.. function:: format_string(format, val[, grouping])
+
+ Processes formatting specifiers as in ``format % val``, but takes the current
+ locale settings into account.
+
+ .. versionadded:: 2.5
+
+
+.. function:: currency(val[, symbol[, grouping[, international]]])
+
+ Formats a number *val* according to the current :const:`LC_MONETARY` settings.
+
+ The returned string includes the currency symbol if *symbol* is true, which is
+ the default. If *grouping* is true (which is not the default), grouping is done
+ with the value. If *international* is true (which is not the default), the
+ international currency symbol is used.
+
+ Note that this function will not work with the 'C' locale, so you have to set a
+ locale via :func:`setlocale` first.
+
+ .. versionadded:: 2.5
+
+
+.. function:: str(float)
+
+ Formats a floating point number using the same format as the built-in function
+ ``str(float)``, but takes the decimal point into account.
+
+
+.. function:: atof(string)
+
+ Converts a string to a floating point number, following the :const:`LC_NUMERIC`
+ settings.
+
+
+.. function:: atoi(string)
+
+ Converts a string to an integer, following the :const:`LC_NUMERIC` conventions.
+
+
+.. data:: LC_CTYPE
+
+ .. index:: module: string
+
+ Locale category for the character type functions. Depending on the settings of
+ this category, the functions of module :mod:`string` dealing with case change
+ their behaviour.
+
+
+.. data:: LC_COLLATE
+
+ Locale category for sorting strings. The functions :func:`strcoll` and
+ :func:`strxfrm` of the :mod:`locale` module are affected.
+
+
+.. data:: LC_TIME
+
+ Locale category for the formatting of time. The function :func:`time.strftime`
+ follows these conventions.
+
+
+.. data:: LC_MONETARY
+
+ Locale category for formatting of monetary values. The available options are
+ available from the :func:`localeconv` function.
+
+
+.. data:: LC_MESSAGES
+
+ Locale category for message display. Python currently does not support
+ application specific locale-aware messages. Messages displayed by the operating
+ system, like those returned by :func:`os.strerror` might be affected by this
+ category.
+
+
+.. data:: LC_NUMERIC
+
+ Locale category for formatting numbers. The functions :func:`format`,
+ :func:`atoi`, :func:`atof` and :func:`str` of the :mod:`locale` module are
+ affected by that category. All other numeric formatting operations are not
+ affected.
+
+
+.. data:: LC_ALL
+
+ Combination of all locale settings. If this flag is used when the locale is
+ changed, setting the locale for all categories is attempted. If that fails for
+ any category, no category is changed at all. When the locale is retrieved using
+ this flag, a string indicating the setting for all categories is returned. This
+ string can be later used to restore the settings.
+
+
+.. data:: CHAR_MAX
+
+ This is a symbolic constant used for different values returned by
+ :func:`localeconv`.
+
+The :func:`nl_langinfo` function accepts one of the following keys. Most
+descriptions are taken from the corresponding description in the GNU C library.
+
+
+.. data:: CODESET
+
+ Return a string with the name of the character encoding used in the selected
+ locale.
+
+
+.. data:: D_T_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ time and date in a locale-specific way.
+
+
+.. data:: D_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ a date in a locale-specific way.
+
+
+.. data:: T_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ a time in a locale-specific way.
+
+
+.. data:: T_FMT_AMPM
+
+ The return value can be used as a format string for 'strftime' to represent time
+ in the am/pm format.
+
+
+.. data:: DAY_1 ... DAY_7
+
+ Return name of the n-th day of the week.
+
+ .. warning::
+
+ This follows the US convention of :const:`DAY_1` being Sunday, not the
+ international convention (ISO 8601) that Monday is the first day of the week.
+
+
+.. data:: ABDAY_1 ... ABDAY_7
+
+ Return abbreviated name of the n-th day of the week.
+
+
+.. data:: MON_1 ... MON_12
+
+ Return name of the n-th month.
+
+
+.. data:: ABMON_1 ... ABMON_12
+
+ Return abbreviated name of the n-th month.
+
+
+.. data:: RADIXCHAR
+
+ Return radix character (decimal dot, decimal comma, etc.)
+
+
+.. data:: THOUSEP
+
+ Return separator character for thousands (groups of three digits).
+
+
+.. data:: YESEXPR
+
+ Return a regular expression that can be used with the regex function to
+ recognize a positive response to a yes/no question.
+
+ .. warning::
+
+ The expression is in the syntax suitable for the :cfunc:`regex` function from
+ the C library, which might differ from the syntax used in :mod:`re`.
+
+
+.. data:: NOEXPR
+
+ Return a regular expression that can be used with the regex(3) function to
+ recognize a negative response to a yes/no question.
+
+
+.. data:: CRNCYSTR
+
+ Return the currency symbol, preceded by "-" if the symbol should appear before
+ the value, "+" if the symbol should appear after the value, or "." if the symbol
+ should replace the radix character.
+
+
+.. data:: 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 :func:`strftime` function 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.
+
+
+.. data:: ERA_YEAR
+
+ The return value gives the year in the relevant era of the locale.
+
+
+.. data:: ERA_D_T_FMT
+
+ This return value can be used as a format string for :func:`strftime` to
+ represent dates and times in a locale-specific era-based way.
+
+
+.. data:: ERA_D_FMT
+
+ This return value can be used as a format string for :func:`strftime` to
+ represent time in a locale-specific era-based way.
+
+
+.. data:: ALT_DIGITS
+
+ The return value is a representation of up to 100 values used to represent the
+ values 0 to 99.
+
+Example::
+
+ >>> import locale
+ >>> loc = locale.getlocale(locale.LC_ALL) # get current locale
+ >>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
+ >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
+ >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
+ >>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
+ >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
+
+
+Background, details, hints, tips and caveats
+--------------------------------------------
+
+The C standard defines the locale as a program-wide property that may be
+relatively expensive to change. On top of that, some implementation are broken
+in such a way that frequent locale changes may cause core dumps. This makes the
+locale somewhat painful to use correctly.
+
+Initially, when a program is started, the locale is the ``C`` locale, no matter
+what the user's preferred locale is. The program must explicitly say that it
+wants the user's preferred locale settings by calling ``setlocale(LC_ALL, '')``.
+
+It is generally a bad idea to call :func:`setlocale` in some library routine,
+since as a side effect it affects the entire program. Saving and restoring it
+is almost as bad: it is expensive and affects other threads that happen to run
+before the settings have been restored.
+
+If, when coding a module for general use, you need a locale independent version
+of an operation that is affected by the locale (such as :func:`string.lower`, or
+certain formats used with :func:`time.strftime`), you will have to find a way to
+do it without using the standard library routine. Even better is convincing
+yourself that using locale settings is okay. Only as a last resort should you
+document that your module is not compatible with non-\ ``C`` locale settings.
+
+.. index:: module: string
+
+The case conversion functions in the :mod:`string` module are affected by the
+locale settings. When a call to the :func:`setlocale` function changes the
+:const:`LC_CTYPE` settings, the variables ``string.lowercase``,
+``string.uppercase`` and ``string.letters`` are recalculated. Note that code
+that uses these variable through ':keyword:`from` ... :keyword:`import` ...',
+e.g. ``from string import letters``, is not affected by subsequent
+:func:`setlocale` calls.
+
+The only way to perform numeric operations according to the locale is to use the
+special functions defined by this module: :func:`atof`, :func:`atoi`,
+:func:`format`, :func:`str`.
+
+
+.. _embedding-locale:
+
+For extension writers and programs that embed Python
+----------------------------------------------------
+
+Extension modules should never call :func:`setlocale`, except to find out what
+the current locale is. But since the return value can only be used portably to
+restore it, that is not very useful (except perhaps to find out whether or not
+the locale is ``C``).
+
+When Python code uses the :mod:`locale` module to change the locale, this also
+affects the embedding application. If the embedding application doesn't want
+this to happen, it should remove the :mod:`_locale` extension module (which does
+all the work) from the table of built-in modules in the :file:`config.c` file,
+and make sure that the :mod:`_locale` module is not accessible as a shared
+library.
+
+
+.. _locale-gettext:
+
+Access to message catalogs
+--------------------------
+
+The locale module exposes the C library's gettext interface on systems that
+provide this interface. It consists of the functions :func:`gettext`,
+:func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`,
+and :func:`bind_textdomain_codeset`. These are similar to the same functions in
+the :mod:`gettext` module, but use the C library's binary format for message
+catalogs, and the C library's search algorithms for locating message catalogs.
+
+Python applications should normally find no need to invoke these functions, and
+should use :mod:`gettext` instead. A known exception to this rule are
+applications that link use additional C libraries which internally invoke
+:cfunc:`gettext` or :func:`dcgettext`. For these applications, it may be
+necessary to bind the text domain, so that the libraries can properly locate
+their message catalogs.
+