The one exception is that <A HREF="../../lib/Pod/perlfunc.html#item_write"><CODE>write()</CODE></A> now <STRONG>always</STRONG> uses the current locale
- see <A HREF="#notes">NOTES</A>.</P>
<P>
<HR>
<H1><A NAME="preparing to use locales">PREPARING TO USE LOCALES</A></H1>
<P>If Perl applications are to understand and present your data
correctly according a locale of your choice, <STRONG>all</STRONG> of the following
must be true:</P>
<UL>
<LI>
<STRONG>Your operating system must support the locale system</STRONG>. If it does,
you should find that the <CODE>setlocale()</CODE> function is a documented part of
its C library.
<P></P>
<LI>
<STRONG>Definitions for locales that you use must be installed</STRONG>. You, or
your system administrator, must make sure that this is the case. The
available locales, the location in which they are kept, and the manner
in which they are installed all vary from system to system. Some systems
provide only a few, hard-wired locales and do not allow more to be
added. Others allow you to add ``canned'' locales provided by the system
supplier. Still others allow you or the system administrator to define
and add arbitrary locales. (You may have to ask your supplier to
provide canned locales that are not delivered with your operating
system.) Read your system documentation for further illumination.
<P></P>
<LI>
<STRONG>Perl must believe that the locale system is supported</STRONG>. If it does,
<CODE>perl -V:d_setlocale</CODE> will say that the value for <CODE>d_setlocale</CODE> is
<CODE>define</CODE>.
<P></P></UL>
<P>If you want a Perl application to process and present your data
according to a particular locale, the application code should include
the <CODE>use locale</CODE> pragma (see <A HREF="#the use locale pragma">The use locale pragma</A>) where
appropriate, and <STRONG>at least one</STRONG> of the following must be true:</P>
<UL>
<LI>
<STRONG>The locale-determining environment variables (see <A HREF="#environment">ENVIRONMENT</A>)
must be correctly set up</STRONG> at the time the application is started, either
by yourself or by whoever set up your system account.
<P></P>
<LI>
<STRONG>The application must set its own locale</STRONG> using the method described in
<H2><A NAME="the use locale pragma">The use locale pragma</A></H2>
<P>By default, Perl ignores the current locale. The <CODE>use locale</CODE>
pragma tells Perl to use the current locale for some operations:</P>
<UL>
<LI>
<STRONG>The comparison operators</STRONG> (<CODE>lt</CODE>, <CODE>le</CODE>, <CODE>cmp</CODE>, <CODE>ge</CODE>, and <CODE>gt</CODE>) and
the POSIX string collation functions <CODE>strcoll()</CODE> and <CODE>strxfrm()</CODE> use
<A HREF="#item_LC_COLLATE"><CODE>LC_COLLATE</CODE></A>. <A HREF="../../lib/Pod/perlfunc.html#item_sort"><CODE>sort()</CODE></A> is also affected if used without an
explicit comparison function, because it uses <CODE>cmp</CODE> by default.
<P><STRONG>Note:</STRONG> <CODE>eq</CODE> and <CODE>ne</CODE> are unaffected by locale: they always
perform a byte-by-byte comparison of their scalar operands. What's
more, if <CODE>cmp</CODE> finds that its operands are equal according to the
collation sequence specified by the current locale, it goes on to
perform a byte-by-byte comparison, and only returns <EM>0</EM> (equal) if the
operands are bit-for-bit identical. If you really want to know whether
two strings--which <CODE>eq</CODE> and <CODE>cmp</CODE> may consider different--are equal
as far as collation in the locale is concerned, see the discussion in
<STRONG>Regular expressions and case-modification functions</STRONG> (uc(), lc(),
ucfirst(), and <A HREF="../../lib/Pod/perlfunc.html#item_lcfirst"><CODE>lcfirst())</CODE></A> use <A HREF="#item_LC_CTYPE"><CODE>LC_CTYPE</CODE></A>
<P></P>
<LI>
<STRONG>The formatting functions</STRONG> (printf(), <A HREF="../../lib/Pod/perlfunc.html#item_sprintf"><CODE>sprintf()</CODE></A> and <A HREF="../../lib/Pod/perlfunc.html#item_write"><CODE>write())</CODE></A> use
<STRONG>The POSIX date formatting function</STRONG> (strftime()) uses <A HREF="#item_LC_TIME"><CODE>LC_TIME</CODE></A>.
<P></P></UL>
<P><A HREF="#item_LC_COLLATE"><CODE>LC_COLLATE</CODE></A>, <A HREF="#item_LC_CTYPE"><CODE>LC_CTYPE</CODE></A>, and so on, are discussed further in <A HREF="#locale categories">LOCALE CATEGORIES</A>.</P>
<P>The default behavior is restored with the <CODE>no locale</CODE> pragma, or
upon reaching the end of block enclosing <CODE>use locale</CODE>.</P>
<P>The string result of any operation that uses locale
information is tainted, as it is possible for a locale to be
untrustworthy. See <A HREF="#security">SECURITY</A>.</P>
<P>The POSIX::localeconv() function allows you to get particulars of the
locale-dependent numeric formatting information specified by the current
<A HREF="#item_LC_NUMERIC"><CODE>LC_NUMERIC</CODE></A> and <A HREF="#item_LC_MONETARY"><CODE>LC_MONETARY</CODE></A> locales. (If you just want the name of
the current locale for a particular category, use POSIX::setlocale()
with a single parameter--see <A HREF="#the setlocale function">The setlocale function</A>.)</P>
<PRE>
use POSIX qw(locale_h);</PRE>
<PRE>
# Get a reference to a hash of locale-dependent info
$locale_values = localeconv();</PRE>
<PRE>
# Output sorted list of the values
for (sort keys %$locale_values) {
printf "%-20s = %s\n", $_, $locale_values->{$_}
}</PRE>
<P><CODE>localeconv()</CODE> takes no arguments, and returns <STRONG>a reference to</STRONG> a hash.
The keys of this hash are variable names for formatting, such as
<CODE>decimal_point</CODE> and <CODE>thousands_sep</CODE>. The values are the
corresponding, er, values. See <EM>POSIX (3)/localeconv</EM> for a longer
example listing the categories an implementation might be expected to
provide; some provide more and others fewer. You don't need an
explicit <CODE>use locale</CODE>, because <CODE>localeconv()</CODE> always observes the
current locale.</P>
<P>Here's a simple-minded example program that rewrites its command-line
parameters as integers correctly formatted in the current locale:</P>
<PRE>
# See comments in previous example
require 5.004;
use POSIX qw(locale_h);</PRE>
<PRE>
# Get some of locale's numeric formatting parameters
<P>In the scope of <CODE>use locale</CODE>, Perl obeys the <A HREF="#item_LC_NUMERIC"><CODE>LC_NUMERIC</CODE></A> locale
information, which controls an application's idea of how numbers should
be formatted for human readability by the printf(), sprintf(), and
<A HREF="../../lib/Pod/perlfunc.html#item_write"><CODE>write()</CODE></A> functions. String-to-numeric conversion by the POSIX::strtod()
function is also affected. In most implementations the only effect is to
change the character used for the decimal point--perhaps from '.' to ','.
These functions aren't aware of such niceties as thousands separation and
so on. (See <A HREF="#the localeconv function">The localeconv function</A> if you care about these things.)</P>
<P>Output produced by <A HREF="../../lib/Pod/perlfunc.html#item_print"><CODE>print()</CODE></A> is <STRONG>never</STRONG> affected by the
current locale: it is independent of whether <CODE>use locale</CODE> or <CODE>no
locale</CODE> is in effect, and corresponds to what you'd get from <A HREF="../../lib/Pod/perlfunc.html#item_printf"><CODE>printf()</CODE></A>
in the ``C'' locale. The same is true for Perl's internal conversions
between numeric and string formats:</P>
<PRE>
use POSIX qw(strtod);
use locale;</PRE>
<PRE>
$n = 5/2; # Assign numeric 2.5 to $n</PRE>
<PRE>
$a = " $n"; # Locale-independent conversion to string</PRE>
<PRE>
print "half five is $n\n"; # Locale-independent output</PRE>
<PRE>
printf "half five is %g\n", $n; # Locale-dependent output</PRE>
<PRE>
print "DECIMAL POINT IS COMMA\n"
if $n == (strtod("2,5"))[0]; # Locale-dependent conversion</PRE>
<P>
<H2><A NAME="category lc_monetary: formatting of monetary amounts">Category LC_MONETARY: Formatting of monetary amounts</A></H2>
<P>The C standard defines the <A HREF="#item_LC_MONETARY"><CODE>LC_MONETARY</CODE></A> category, but no function
that is affected by its contents. (Those with experience of standards
committees will recognize that the working group decided to punt on the
issue.) Consequently, Perl takes no notice of it. If you really want
to use <A HREF="#item_LC_MONETARY"><CODE>LC_MONETARY</CODE></A>, you can query its contents--see <A HREF="#the localeconv function">The localeconv function</A>--and use the information that it returns in your application's
own formatting of currency amounts. However, you may well find that
the information, voluminous and complex though it may be, still does not
quite meet your requirements: currency formatting is a hard nut to crack.</P>
<P>
<H2><A NAME="lc_time">LC_TIME</A></H2>
<P>Output produced by POSIX::strftime(), which builds a formatted
human-readable date/time string, is affected by the current <A HREF="#item_LC_TIME"><CODE>LC_TIME</CODE></A>
locale. Thus, in a French locale, the output produced by the <CODE>%B</CODE>
format element (full month name) for the first month of the year would
be ``janvier''. Here's how to get a list of long month names in the
current locale:</P>
<PRE>
use POSIX qw(strftime);
for (0..11) {
$long_month_name[$_] =
strftime("%B", 0, 0, 0, 1, $_, 96);
}</PRE>
<P>Note: <CODE>use locale</CODE> isn't needed in this example: as a function that
exists only to generate locale-dependent results, <CODE>strftime()</CODE> always
obeys the current <A HREF="#item_LC_TIME"><CODE>LC_TIME</CODE></A> locale.</P>
In the absence of <A HREF="#item_LC_ALL"><CODE>LC_ALL</CODE></A>, <A HREF="#item_LC_CTYPE"><CODE>LC_CTYPE</CODE></A> chooses the character type
locale. In the absence of both <A HREF="#item_LC_ALL"><CODE>LC_ALL</CODE></A> and <A HREF="#item_LC_CTYPE"><CODE>LC_CTYPE</CODE></A>, <A HREF="#item_LANG"><CODE>LANG</CODE></A>
In the absence of <A HREF="#item_LC_ALL"><CODE>LC_ALL</CODE></A>, <A HREF="#item_LC_NUMERIC"><CODE>LC_NUMERIC</CODE></A> chooses the numeric format
locale. In the absence of both <A HREF="#item_LC_ALL"><CODE>LC_ALL</CODE></A> and <A HREF="#item_LC_NUMERIC"><CODE>LC_NUMERIC</CODE></A>, <A HREF="#item_LANG"><CODE>LANG</CODE></A>
