]>
Commit | Line | Data |
---|---|---|
390955cb | 1 | @node Locales, Message Translation, Character Set Handling, Top |
7a68c94a | 2 | @c %MENU% The country and language can affect the behavior of library functions |
28f540f4 RM |
3 | @chapter Locales and Internationalization |
4 | ||
5 | Different countries and cultures have varying conventions for how to | |
6 | communicate. These conventions range from very simple ones, such as the | |
7 | format for representing dates and times, to very complex ones, such as | |
8 | the language spoken. | |
9 | ||
10 | @cindex internationalization | |
11 | @cindex locales | |
12 | @dfn{Internationalization} of software means programming it to be able | |
f65fd747 | 13 | to adapt to the user's favorite conventions. In @w{ISO C}, |
28f540f4 RM |
14 | internationalization works by means of @dfn{locales}. Each locale |
15 | specifies a collection of conventions, one convention for each purpose. | |
16 | The user chooses a set of conventions by specifying a locale (via | |
17 | environment variables). | |
18 | ||
19 | All programs inherit the chosen locale as part of their environment. | |
20 | Provided the programs are written to obey the choice of locale, they | |
21 | will follow the conventions preferred by the user. | |
22 | ||
23 | @menu | |
24 | * Effects of Locale:: Actions affected by the choice of | |
f65fd747 | 25 | locale. |
28f540f4 RM |
26 | * Choosing Locale:: How the user specifies a locale. |
27 | * Locale Categories:: Different purposes for which you can | |
f65fd747 | 28 | select a locale. |
28f540f4 | 29 | * Setting the Locale:: How a program specifies the locale |
f65fd747 | 30 | with library functions. |
28f540f4 | 31 | * Standard Locales:: Locale names available on all systems. |
85c165be | 32 | * Locale Information:: How to access the information for the locale. |
5e0889da | 33 | * Formatting Numbers:: A dedicated function to format numbers. |
28f540f4 RM |
34 | @end menu |
35 | ||
36 | @node Effects of Locale, Choosing Locale, , Locales | |
37 | @section What Effects a Locale Has | |
38 | ||
39 | Each locale specifies conventions for several purposes, including the | |
40 | following: | |
41 | ||
42 | @itemize @bullet | |
43 | @item | |
44 | What multibyte character sequences are valid, and how they are | |
390955cb | 45 | interpreted (@pxref{Character Set Handling}). |
28f540f4 RM |
46 | |
47 | @item | |
48 | Classification of which characters in the local character set are | |
49 | considered alphabetic, and upper- and lower-case conversion conventions | |
50 | (@pxref{Character Handling}). | |
51 | ||
52 | @item | |
53 | The collating sequence for the local language and character set | |
54 | (@pxref{Collation Functions}). | |
55 | ||
56 | @item | |
85c165be | 57 | Formatting of numbers and currency amounts (@pxref{General Numeric}). |
28f540f4 RM |
58 | |
59 | @item | |
99a20616 | 60 | Formatting of dates and times (@pxref{Formatting Calendar Time}). |
28f540f4 RM |
61 | |
62 | @item | |
85c165be UD |
63 | What language to use for output, including error messages |
64 | (@pxref{Message Translation}). | |
28f540f4 RM |
65 | |
66 | @item | |
67 | What language to use for user answers to yes-or-no questions. | |
68 | ||
69 | @item | |
70 | What language to use for more complex user input. | |
71 | (The C library doesn't yet help you implement this.) | |
72 | @end itemize | |
73 | ||
74 | Some aspects of adapting to the specified locale are handled | |
75 | automatically by the library subroutines. For example, all your program | |
76 | needs to do in order to use the collating sequence of the chosen locale | |
77 | is to use @code{strcoll} or @code{strxfrm} to compare strings. | |
78 | ||
79 | Other aspects of locales are beyond the comprehension of the library. | |
80 | For example, the library can't automatically translate your program's | |
81 | output messages into other languages. The only way you can support | |
82 | output in the user's favorite language is to program this more or less | |
85c165be UD |
83 | by hand. The C library provides functions to handle translations for |
84 | multiple languages easily. | |
28f540f4 RM |
85 | |
86 | This chapter discusses the mechanism by which you can modify the current | |
87 | locale. The effects of the current locale on specific library functions | |
88 | are discussed in more detail in the descriptions of those functions. | |
89 | ||
90 | @node Choosing Locale, Locale Categories, Effects of Locale, Locales | |
91 | @section Choosing a Locale | |
92 | ||
93 | The simplest way for the user to choose a locale is to set the | |
94 | environment variable @code{LANG}. This specifies a single locale to use | |
95 | for all purposes. For example, a user could specify a hypothetical | |
96 | locale named @samp{espana-castellano} to use the standard conventions of | |
97 | most of Spain. | |
98 | ||
99 | The set of locales supported depends on the operating system you are | |
100 | using, and so do their names. We can't make any promises about what | |
101 | locales will exist, except for one standard locale called @samp{C} or | |
6dd5b57e | 102 | @samp{POSIX}. Later we will describe how to construct locales. |
85c165be | 103 | @comment (@pxref{Building Locale Files}). |
28f540f4 RM |
104 | |
105 | @cindex combining locales | |
106 | A user also has the option of specifying different locales for different | |
107 | purposes---in effect, choosing a mixture of multiple locales. | |
108 | ||
109 | For example, the user might specify the locale @samp{espana-castellano} | |
110 | for most purposes, but specify the locale @samp{usa-english} for | |
111 | currency formatting. This might make sense if the user is a | |
112 | Spanish-speaking American, working in Spanish, but representing monetary | |
113 | amounts in US dollars. | |
114 | ||
115 | Note that both locales @samp{espana-castellano} and @samp{usa-english}, | |
116 | like all locales, would include conventions for all of the purposes to | |
117 | which locales apply. However, the user can choose to use each locale | |
118 | for a particular subset of those purposes. | |
119 | ||
120 | @node Locale Categories, Setting the Locale, Choosing Locale, Locales | |
121 | @section Categories of Activities that Locales Affect | |
122 | @cindex categories for locales | |
123 | @cindex locale categories | |
124 | ||
125 | The purposes that locales serve are grouped into @dfn{categories}, so | |
126 | that a user or a program can choose the locale for each category | |
127 | independently. Here is a table of categories; each name is both an | |
128 | environment variable that a user can set, and a macro name that you can | |
129 | use as an argument to @code{setlocale}. | |
130 | ||
85c165be | 131 | @vtable @code |
28f540f4 | 132 | @comment locale.h |
f65fd747 | 133 | @comment ISO |
28f540f4 | 134 | @item LC_COLLATE |
28f540f4 RM |
135 | This category applies to collation of strings (functions @code{strcoll} |
136 | and @code{strxfrm}); see @ref{Collation Functions}. | |
137 | ||
138 | @comment locale.h | |
f65fd747 | 139 | @comment ISO |
28f540f4 | 140 | @item LC_CTYPE |
28f540f4 RM |
141 | This category applies to classification and conversion of characters, |
142 | and to multibyte and wide characters; | |
390955cb | 143 | see @ref{Character Handling}, and @ref{Character Set Handling}. |
28f540f4 RM |
144 | |
145 | @comment locale.h | |
f65fd747 | 146 | @comment ISO |
28f540f4 | 147 | @item LC_MONETARY |
85c165be | 148 | This category applies to formatting monetary values; see @ref{General Numeric}. |
28f540f4 RM |
149 | |
150 | @comment locale.h | |
f65fd747 | 151 | @comment ISO |
28f540f4 | 152 | @item LC_NUMERIC |
28f540f4 | 153 | This category applies to formatting numeric values that are not |
85c165be | 154 | monetary; see @ref{General Numeric}. |
28f540f4 RM |
155 | |
156 | @comment locale.h | |
f65fd747 | 157 | @comment ISO |
28f540f4 | 158 | @item LC_TIME |
28f540f4 | 159 | This category applies to formatting date and time values; see |
99a20616 | 160 | @ref{Formatting Calendar Time}. |
28f540f4 | 161 | |
28f540f4 | 162 | @comment locale.h |
f65fd747 UD |
163 | @comment XOPEN |
164 | @item LC_MESSAGES | |
85c165be | 165 | This category applies to selecting the language used in the user |
8b7fb588 UD |
166 | interface for message translation (@pxref{The Uniforum approach}; |
167 | @pxref{Message catalogs a la X/Open}). | |
28f540f4 RM |
168 | |
169 | @comment locale.h | |
f65fd747 | 170 | @comment ISO |
28f540f4 | 171 | @item LC_ALL |
28f540f4 | 172 | This is not an environment variable; it is only a macro that you can use |
85c165be UD |
173 | with @code{setlocale} to set a single locale for all purposes. Setting |
174 | this environment variable overwrites all selections by the other | |
175 | @code{LC_*} variables or @code{LANG}. | |
28f540f4 RM |
176 | |
177 | @comment locale.h | |
f65fd747 | 178 | @comment ISO |
28f540f4 | 179 | @item LANG |
28f540f4 RM |
180 | If this environment variable is defined, its value specifies the locale |
181 | to use for all purposes except as overridden by the variables above. | |
85c165be UD |
182 | @end vtable |
183 | ||
184 | @vindex LANGUAGE | |
185 | When developing the message translation functions it was felt that the | |
6dd5b57e | 186 | functionality provided by the variables above is not sufficient. For |
6941c42a | 187 | example, it should be possible to specify more than one locale name. |
6dd5b57e UD |
188 | Take a Swedish user who better speaks German than English, and a program |
189 | whose messages are output in English by default. It should be possible | |
190 | to specify that the first choice of language is Swedish, the second | |
191 | German, and if this also fails to use English. This is | |
85c165be UD |
192 | possible with the variable @code{LANGUAGE}. For further description of |
193 | this GNU extension see @ref{Using gettextized software}. | |
28f540f4 RM |
194 | |
195 | @node Setting the Locale, Standard Locales, Locale Categories, Locales | |
196 | @section How Programs Set the Locale | |
197 | ||
198 | A C program inherits its locale environment variables when it starts up. | |
199 | This happens automatically. However, these variables do not | |
200 | automatically control the locale used by the library functions, because | |
f65fd747 | 201 | @w{ISO C} says that all programs start by default in the standard @samp{C} |
28f540f4 RM |
202 | locale. To use the locales specified by the environment, you must call |
203 | @code{setlocale}. Call it as follows: | |
204 | ||
205 | @smallexample | |
206 | setlocale (LC_ALL, ""); | |
207 | @end smallexample | |
208 | ||
209 | @noindent | |
85c165be UD |
210 | to select a locale based on the user choice of the appropriate |
211 | environment variables. | |
28f540f4 RM |
212 | |
213 | @cindex changing the locale | |
214 | @cindex locale, changing | |
215 | You can also use @code{setlocale} to specify a particular locale, for | |
216 | general use or for a specific category. | |
217 | ||
218 | @pindex locale.h | |
219 | The symbols in this section are defined in the header file @file{locale.h}. | |
220 | ||
221 | @comment locale.h | |
f65fd747 | 222 | @comment ISO |
28f540f4 | 223 | @deftypefun {char *} setlocale (int @var{category}, const char *@var{locale}) |
f65fd747 | 224 | The function @code{setlocale} sets the current locale for |
28f540f4 RM |
225 | category @var{category} to @var{locale}. |
226 | ||
227 | If @var{category} is @code{LC_ALL}, this specifies the locale for all | |
228 | purposes. The other possible values of @var{category} specify an | |
6dd5b57e | 229 | single purpose (@pxref{Locale Categories}). |
28f540f4 RM |
230 | |
231 | You can also use this function to find out the current locale by passing | |
232 | a null pointer as the @var{locale} argument. In this case, | |
233 | @code{setlocale} returns a string that is the name of the locale | |
234 | currently selected for category @var{category}. | |
235 | ||
236 | The string returned by @code{setlocale} can be overwritten by subsequent | |
237 | calls, so you should make a copy of the string (@pxref{Copying and | |
238 | Concatenation}) if you want to save it past any further calls to | |
239 | @code{setlocale}. (The standard library is guaranteed never to call | |
240 | @code{setlocale} itself.) | |
241 | ||
242 | You should not modify the string returned by @code{setlocale}. | |
f65fd747 | 243 | It might be the same string that was passed as an argument in a |
28f540f4 RM |
244 | previous call to @code{setlocale}. |
245 | ||
246 | When you read the current locale for category @code{LC_ALL}, the value | |
247 | encodes the entire combination of selected locales for all categories. | |
248 | In this case, the value is not just a single locale name. In fact, we | |
249 | don't make any promises about what it looks like. But if you specify | |
250 | the same ``locale name'' with @code{LC_ALL} in a subsequent call to | |
251 | @code{setlocale}, it restores the same combination of locale selections. | |
252 | ||
6dd5b57e UD |
253 | To be sure you can use the returned string encoding the currently selected |
254 | locale at a later time, you must make a copy of the string. It is not | |
255 | guaranteed that the returned pointer remains valid over time. | |
85c165be | 256 | |
28f540f4 | 257 | When the @var{locale} argument is not a null pointer, the string returned |
6dd5b57e | 258 | by @code{setlocale} reflects the newly-modified locale. |
28f540f4 RM |
259 | |
260 | If you specify an empty string for @var{locale}, this means to read the | |
261 | appropriate environment variable and use its value to select the locale | |
262 | for @var{category}. | |
263 | ||
6dd5b57e UD |
264 | If a nonempty string is given for @var{locale}, then the locale of that |
265 | name is used if possible. | |
85c165be | 266 | |
28f540f4 RM |
267 | If you specify an invalid locale name, @code{setlocale} returns a null |
268 | pointer and leaves the current locale unchanged. | |
269 | @end deftypefun | |
270 | ||
271 | Here is an example showing how you might use @code{setlocale} to | |
272 | temporarily switch to a new locale. | |
273 | ||
274 | @smallexample | |
275 | #include <stddef.h> | |
276 | #include <locale.h> | |
277 | #include <stdlib.h> | |
278 | #include <string.h> | |
279 | ||
280 | void | |
281 | with_other_locale (char *new_locale, | |
282 | void (*subroutine) (int), | |
283 | int argument) | |
284 | @{ | |
285 | char *old_locale, *saved_locale; | |
286 | ||
287 | /* @r{Get the name of the current locale.} */ | |
288 | old_locale = setlocale (LC_ALL, NULL); | |
f65fd747 | 289 | |
28f540f4 RM |
290 | /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */ |
291 | saved_locale = strdup (old_locale); | |
816e6eb5 | 292 | if (saved_locale == NULL) |
28f540f4 | 293 | fatal ("Out of memory"); |
f65fd747 | 294 | |
28f540f4 RM |
295 | /* @r{Now change the locale and do some stuff with it.} */ |
296 | setlocale (LC_ALL, new_locale); | |
297 | (*subroutine) (argument); | |
f65fd747 | 298 | |
28f540f4 RM |
299 | /* @r{Restore the original locale.} */ |
300 | setlocale (LC_ALL, saved_locale); | |
301 | free (saved_locale); | |
302 | @} | |
303 | @end smallexample | |
304 | ||
f65fd747 | 305 | @strong{Portability Note:} Some @w{ISO C} systems may define additional |
6dd5b57e | 306 | locale categories, and future versions of the library will do so. For |
85c165be UD |
307 | portability, assume that any symbol beginning with @samp{LC_} might be |
308 | defined in @file{locale.h}. | |
28f540f4 | 309 | |
85c165be | 310 | @node Standard Locales, Locale Information, Setting the Locale, Locales |
28f540f4 RM |
311 | @section Standard Locales |
312 | ||
313 | The only locale names you can count on finding on all operating systems | |
314 | are these three standard ones: | |
315 | ||
316 | @table @code | |
317 | @item "C" | |
318 | This is the standard C locale. The attributes and behavior it provides | |
f65fd747 | 319 | are specified in the @w{ISO C} standard. When your program starts up, it |
28f540f4 RM |
320 | initially uses this locale by default. |
321 | ||
322 | @item "POSIX" | |
323 | This is the standard POSIX locale. Currently, it is an alias for the | |
324 | standard C locale. | |
325 | ||
326 | @item "" | |
327 | The empty name says to select a locale based on environment variables. | |
328 | @xref{Locale Categories}. | |
329 | @end table | |
330 | ||
331 | Defining and installing named locales is normally a responsibility of | |
332 | the system administrator at your site (or the person who installed the | |
85c165be UD |
333 | GNU C library). It is also possible for the user to create private |
334 | locales. All this will be discussed later when describing the tool to | |
6dd5b57e | 335 | do so. |
85c165be | 336 | @comment (@pxref{Building Locale Files}). |
28f540f4 RM |
337 | |
338 | If your program needs to use something other than the @samp{C} locale, | |
339 | it will be more portable if you use whatever locale the user specifies | |
340 | with the environment, rather than trying to specify some non-standard | |
341 | locale explicitly by name. Remember, different machines might have | |
342 | different sets of locales installed. | |
343 | ||
85c165be | 344 | @node Locale Information, Formatting Numbers, Standard Locales, Locales |
6dd5b57e | 345 | @section Accessing Locale Information |
85c165be | 346 | |
6dd5b57e | 347 | There are several ways to access locale information. The simplest |
85c165be | 348 | way is to let the C library itself do the work. Several of the |
6dd5b57e UD |
349 | functions in this library implicitly access the locale data, and use |
350 | what information is provided by the currently selected locale. This is | |
85c165be UD |
351 | how the locale model is meant to work normally. |
352 | ||
6dd5b57e | 353 | As an example take the @code{strftime} function, which is meant to nicely |
99a20616 | 354 | format date and time information (@pxref{Formatting Calendar Time}). |
85c165be | 355 | Part of the standard information contained in the @code{LC_TIME} |
6dd5b57e | 356 | category is the names of the months. Instead of requiring the |
85c165be | 357 | programmer to take care of providing the translations the |
6dd5b57e UD |
358 | @code{strftime} function does this all by itself. @code{%A} |
359 | in the format string is replaced by the appropriate weekday | |
360 | name of the locale currently selected by @code{LC_TIME}. This is an | |
361 | easy example, and wherever possible functions do things automatically | |
362 | in this way. | |
363 | ||
364 | But there are quite often situations when there is simply no function | |
365 | to perform the task, or it is simply not possible to do the work | |
85c165be UD |
366 | automatically. For these cases it is necessary to access the |
367 | information in the locale directly. To do this the C library provides | |
368 | two functions: @code{localeconv} and @code{nl_langinfo}. The former is | |
369 | part of @w{ISO C} and therefore portable, but has a brain-damaged | |
370 | interface. The second is part of the Unix interface and is portable in | |
371 | as far as the system follows the Unix standards. | |
28f540f4 | 372 | |
85c165be UD |
373 | @menu |
374 | * The Lame Way to Locale Data:: ISO C's @code{localeconv}. | |
375 | * The Elegant and Fast Way:: X/Open's @code{nl_langinfo}. | |
376 | @end menu | |
377 | ||
378 | @node The Lame Way to Locale Data, The Elegant and Fast Way, ,Locale Information | |
c66dbe00 | 379 | @subsection @code{localeconv}: It is portable but @dots{} |
85c165be UD |
380 | |
381 | Together with the @code{setlocale} function the @w{ISO C} people | |
6dd5b57e UD |
382 | invented the @code{localeconv} function. It is a masterpiece of poor |
383 | design. It is expensive to use, not extendable, and not generally | |
384 | usable as it provides access to only @code{LC_MONETARY} and | |
385 | @code{LC_NUMERIC} related information. Nevertheless, if it is | |
386 | applicable to a given situation it should be used since it is very | |
387 | portable. The function @code{strfmon} formats monetary amounts | |
388 | according to the selected locale using this information. | |
28f540f4 RM |
389 | @pindex locale.h |
390 | @cindex monetary value formatting | |
391 | @cindex numeric value formatting | |
392 | ||
393 | @comment locale.h | |
f65fd747 | 394 | @comment ISO |
28f540f4 RM |
395 | @deftypefun {struct lconv *} localeconv (void) |
396 | The @code{localeconv} function returns a pointer to a structure whose | |
397 | components contain information about how numeric and monetary values | |
398 | should be formatted in the current locale. | |
399 | ||
85c165be | 400 | You should not modify the structure or its contents. The structure might |
28f540f4 RM |
401 | be overwritten by subsequent calls to @code{localeconv}, or by calls to |
402 | @code{setlocale}, but no other function in the library overwrites this | |
403 | value. | |
404 | @end deftypefun | |
405 | ||
406 | @comment locale.h | |
f65fd747 | 407 | @comment ISO |
28f540f4 | 408 | @deftp {Data Type} {struct lconv} |
6dd5b57e UD |
409 | @code{localeconv}'s return value is of this data type. Its elements are |
410 | described in the following subsections. | |
28f540f4 RM |
411 | @end deftp |
412 | ||
413 | If a member of the structure @code{struct lconv} has type @code{char}, | |
414 | and the value is @code{CHAR_MAX}, it means that the current locale has | |
415 | no value for that parameter. | |
416 | ||
417 | @menu | |
418 | * General Numeric:: Parameters for formatting numbers and | |
419 | currency amounts. | |
420 | * Currency Symbol:: How to print the symbol that identifies an | |
421 | amount of money (e.g. @samp{$}). | |
422 | * Sign of Money Amount:: How to print the (positive or negative) sign | |
423 | for a monetary amount, if one exists. | |
424 | @end menu | |
425 | ||
85c165be UD |
426 | @node General Numeric, Currency Symbol, , The Lame Way to Locale Data |
427 | @subsubsection Generic Numeric Formatting Parameters | |
28f540f4 RM |
428 | |
429 | These are the standard members of @code{struct lconv}; there may be | |
430 | others. | |
431 | ||
432 | @table @code | |
433 | @item char *decimal_point | |
434 | @itemx char *mon_decimal_point | |
435 | These are the decimal-point separators used in formatting non-monetary | |
436 | and monetary quantities, respectively. In the @samp{C} locale, the | |
437 | value of @code{decimal_point} is @code{"."}, and the value of | |
438 | @code{mon_decimal_point} is @code{""}. | |
439 | @cindex decimal-point separator | |
440 | ||
441 | @item char *thousands_sep | |
442 | @itemx char *mon_thousands_sep | |
443 | These are the separators used to delimit groups of digits to the left of | |
444 | the decimal point in formatting non-monetary and monetary quantities, | |
445 | respectively. In the @samp{C} locale, both members have a value of | |
446 | @code{""} (the empty string). | |
447 | ||
448 | @item char *grouping | |
449 | @itemx char *mon_grouping | |
450 | These are strings that specify how to group the digits to the left of | |
451 | the decimal point. @code{grouping} applies to non-monetary quantities | |
452 | and @code{mon_grouping} applies to monetary quantities. Use either | |
453 | @code{thousands_sep} or @code{mon_thousands_sep} to separate the digit | |
454 | groups. | |
455 | @cindex grouping of digits | |
456 | ||
bcf6d602 UD |
457 | Each member of these strings is to be interpreted as an integer value of |
458 | type @code{char}. Successive numbers (from left to right) give the | |
459 | sizes of successive groups (from right to left, starting at the decimal | |
460 | point.) The last member is either @code{0}, in which case the previous | |
461 | member is used over and over again for all the remaining groups, or | |
462 | @code{CHAR_MAX}, in which case there is no more grouping---or, put | |
463 | another way, any remaining digits form one large group without | |
464 | separators. | |
465 | ||
466 | For example, if @code{grouping} is @code{"\04\03\02"}, the correct | |
467 | grouping for the number @code{123456787654321} is @samp{12}, @samp{34}, | |
28f540f4 RM |
468 | @samp{56}, @samp{78}, @samp{765}, @samp{4321}. This uses a group of 4 |
469 | digits at the end, preceded by a group of 3 digits, preceded by groups | |
470 | of 2 digits (as many as needed). With a separator of @samp{,}, the | |
471 | number would be printed as @samp{12,34,56,78,765,4321}. | |
472 | ||
bcf6d602 | 473 | A value of @code{"\03"} indicates repeated groups of three digits, as |
28f540f4 RM |
474 | normally used in the U.S. |
475 | ||
476 | In the standard @samp{C} locale, both @code{grouping} and | |
477 | @code{mon_grouping} have a value of @code{""}. This value specifies no | |
478 | grouping at all. | |
479 | ||
480 | @item char int_frac_digits | |
481 | @itemx char frac_digits | |
482 | These are small integers indicating how many fractional digits (to the | |
483 | right of the decimal point) should be displayed in a monetary value in | |
484 | international and local formats, respectively. (Most often, both | |
485 | members have the same value.) | |
486 | ||
487 | In the standard @samp{C} locale, both of these members have the value | |
f65fd747 | 488 | @code{CHAR_MAX}, meaning ``unspecified''. The ISO standard doesn't say |
6dd5b57e | 489 | what to do when you find this value; we recommend printing no |
28f540f4 RM |
490 | fractional digits. (This locale also specifies the empty string for |
491 | @code{mon_decimal_point}, so printing any fractional digits would be | |
492 | confusing!) | |
493 | @end table | |
494 | ||
85c165be UD |
495 | @node Currency Symbol, Sign of Money Amount, General Numeric, The Lame Way to Locale Data |
496 | @subsubsection Printing the Currency Symbol | |
28f540f4 RM |
497 | @cindex currency symbols |
498 | ||
499 | These members of the @code{struct lconv} structure specify how to print | |
500 | the symbol to identify a monetary value---the international analog of | |
501 | @samp{$} for US dollars. | |
502 | ||
503 | Each country has two standard currency symbols. The @dfn{local currency | |
504 | symbol} is used commonly within the country, while the | |
505 | @dfn{international currency symbol} is used internationally to refer to | |
506 | that country's currency when it is necessary to indicate the country | |
507 | unambiguously. | |
508 | ||
509 | For example, many countries use the dollar as their monetary unit, and | |
510 | when dealing with international currencies it's important to specify | |
511 | that one is dealing with (say) Canadian dollars instead of U.S. dollars | |
512 | or Australian dollars. But when the context is known to be Canada, | |
513 | there is no need to make this explicit---dollar amounts are implicitly | |
514 | assumed to be in Canadian dollars. | |
515 | ||
516 | @table @code | |
517 | @item char *currency_symbol | |
518 | The local currency symbol for the selected locale. | |
519 | ||
520 | In the standard @samp{C} locale, this member has a value of @code{""} | |
f65fd747 | 521 | (the empty string), meaning ``unspecified''. The ISO standard doesn't |
28f540f4 | 522 | say what to do when you find this value; we recommend you simply print |
6dd5b57e UD |
523 | the empty string as you would print any other string pointed to by this |
524 | variable. | |
28f540f4 RM |
525 | |
526 | @item char *int_curr_symbol | |
527 | The international currency symbol for the selected locale. | |
528 | ||
529 | The value of @code{int_curr_symbol} should normally consist of a | |
530 | three-letter abbreviation determined by the international standard | |
531 | @cite{ISO 4217 Codes for the Representation of Currency and Funds}, | |
532 | followed by a one-character separator (often a space). | |
533 | ||
534 | In the standard @samp{C} locale, this member has a value of @code{""} | |
6dd5b57e UD |
535 | (the empty string), meaning ``unspecified''. We recommend you simply print |
536 | the empty string as you would print any other string pointed to by this | |
537 | variable. | |
28f540f4 RM |
538 | |
539 | @item char p_cs_precedes | |
540 | @itemx char n_cs_precedes | |
bcf6d602 UD |
541 | @itemx char int_p_cs_precedes |
542 | @itemx char int_n_cs_precedes | |
543 | These members are @code{1} if the @code{currency_symbol} or | |
544 | @code{int_curr_symbol} strings should precede the value of a monetary | |
545 | amount, or @code{0} if the strings should follow the value. The | |
546 | @code{p_cs_precedes} and @code{int_p_cs_precedes} members apply to | |
547 | positive amounts (or zero), and the @code{n_cs_precedes} and | |
548 | @code{int_n_cs_precedes} members apply to negative amounts. | |
549 | ||
550 | In the standard @samp{C} locale, all of these members have a value of | |
f65fd747 | 551 | @code{CHAR_MAX}, meaning ``unspecified''. The ISO standard doesn't say |
6dd5b57e UD |
552 | what to do when you find this value. We recommend printing the |
553 | currency symbol before the amount, which is right for most countries. | |
28f540f4 RM |
554 | In other words, treat all nonzero values alike in these members. |
555 | ||
bcf6d602 UD |
556 | The members with the @code{int_} prefix apply to the |
557 | @code{int_curr_symbol} while the other two apply to | |
558 | @code{currency_symbol}. | |
28f540f4 RM |
559 | |
560 | @item char p_sep_by_space | |
561 | @itemx char n_sep_by_space | |
bcf6d602 UD |
562 | @itemx char int_p_sep_by_space |
563 | @itemx char int_n_sep_by_space | |
28f540f4 | 564 | These members are @code{1} if a space should appear between the |
bcf6d602 UD |
565 | @code{currency_symbol} or @code{int_curr_symbol} strings and the |
566 | amount, or @code{0} if no space should appear. The | |
567 | @code{p_sep_by_space} and @code{int_p_sep_by_space} members apply to | |
568 | positive amounts (or zero), and the @code{n_sep_by_space} and | |
569 | @code{int_n_sep_by_space} members apply to negative amounts. | |
28f540f4 | 570 | |
bcf6d602 | 571 | In the standard @samp{C} locale, all of these members have a value of |
f65fd747 | 572 | @code{CHAR_MAX}, meaning ``unspecified''. The ISO standard doesn't say |
28f540f4 | 573 | what you should do when you find this value; we suggest you treat it as |
6dd5b57e | 574 | 1 (print a space). In other words, treat all nonzero values alike in |
28f540f4 RM |
575 | these members. |
576 | ||
bcf6d602 UD |
577 | The members with the @code{int_} prefix apply to the |
578 | @code{int_curr_symbol} while the other two apply to | |
579 | @code{currency_symbol}. There is one specialty with the | |
580 | @code{int_curr_symbol}, though. Since all legal values contain a space | |
581 | at the end the string one either printf this space (if the currency | |
582 | symbol must appear in front and must be separated) or one has to avoid | |
583 | printing this character at all (especially when at the end of the | |
584 | string). | |
28f540f4 RM |
585 | @end table |
586 | ||
85c165be | 587 | @node Sign of Money Amount, , Currency Symbol, The Lame Way to Locale Data |
6dd5b57e | 588 | @subsubsection Printing the Sign of a Monetary Amount |
28f540f4 RM |
589 | |
590 | These members of the @code{struct lconv} structure specify how to print | |
6dd5b57e | 591 | the sign (if any) of a monetary value. |
28f540f4 RM |
592 | |
593 | @table @code | |
594 | @item char *positive_sign | |
595 | @itemx char *negative_sign | |
596 | These are strings used to indicate positive (or zero) and negative | |
6dd5b57e | 597 | monetary quantities, respectively. |
28f540f4 RM |
598 | |
599 | In the standard @samp{C} locale, both of these members have a value of | |
600 | @code{""} (the empty string), meaning ``unspecified''. | |
601 | ||
f65fd747 | 602 | The ISO standard doesn't say what to do when you find this value; we |
28f540f4 RM |
603 | recommend printing @code{positive_sign} as you find it, even if it is |
604 | empty. For a negative value, print @code{negative_sign} as you find it | |
605 | unless both it and @code{positive_sign} are empty, in which case print | |
606 | @samp{-} instead. (Failing to indicate the sign at all seems rather | |
607 | unreasonable.) | |
608 | ||
609 | @item char p_sign_posn | |
610 | @itemx char n_sign_posn | |
bcf6d602 UD |
611 | @itemx char int_p_sign_posn |
612 | @itemx char int_n_sign_posn | |
6dd5b57e | 613 | These members are small integers that indicate how to |
28f540f4 RM |
614 | position the sign for nonnegative and negative monetary quantities, |
615 | respectively. (The string used by the sign is what was specified with | |
616 | @code{positive_sign} or @code{negative_sign}.) The possible values are | |
617 | as follows: | |
618 | ||
619 | @table @code | |
620 | @item 0 | |
621 | The currency symbol and quantity should be surrounded by parentheses. | |
622 | ||
623 | @item 1 | |
624 | Print the sign string before the quantity and currency symbol. | |
625 | ||
626 | @item 2 | |
627 | Print the sign string after the quantity and currency symbol. | |
628 | ||
629 | @item 3 | |
630 | Print the sign string right before the currency symbol. | |
631 | ||
632 | @item 4 | |
633 | Print the sign string right after the currency symbol. | |
634 | ||
635 | @item CHAR_MAX | |
636 | ``Unspecified''. Both members have this value in the standard | |
637 | @samp{C} locale. | |
638 | @end table | |
639 | ||
f65fd747 | 640 | The ISO standard doesn't say what you should do when the value is |
28f540f4 RM |
641 | @code{CHAR_MAX}. We recommend you print the sign after the currency |
642 | symbol. | |
28f540f4 | 643 | |
bcf6d602 UD |
644 | The members with the @code{int_} prefix apply to the |
645 | @code{int_curr_symbol} while the other two apply to | |
646 | @code{currency_symbol}. | |
647 | @end table | |
85c165be UD |
648 | |
649 | @node The Elegant and Fast Way, , The Lame Way to Locale Data, Locale Information | |
650 | @subsection Pinpoint Access to Locale Data | |
651 | ||
5e0889da UD |
652 | When writing the X/Open Portability Guide the authors realized that the |
653 | @code{localeconv} function is not enough to provide reasonable access to | |
6dd5b57e | 654 | locale information. The information which was meant to be available |
5e0889da | 655 | in the locale (as later specified in the POSIX.1 standard) requires more |
6dd5b57e | 656 | ways to access it. Therefore the @code{nl_langinfo} function |
5e0889da | 657 | was introduced. |
85c165be UD |
658 | |
659 | @comment langinfo.h | |
660 | @comment XOPEN | |
661 | @deftypefun {char *} nl_langinfo (nl_item @var{item}) | |
662 | The @code{nl_langinfo} function can be used to access individual | |
6dd5b57e UD |
663 | elements of the locale categories. Unlike the @code{localeconv} |
664 | function, which returns all the information, @code{nl_langinfo} | |
665 | lets the caller select what information it requires. This is very | |
666 | fast and it is not a problem to call this function multiple times. | |
85c165be | 667 | |
6dd5b57e UD |
668 | A second advantage is that in addition to the numeric and monetary |
669 | formatting information, information from the | |
85c165be UD |
670 | @code{LC_TIME} and @code{LC_MESSAGES} categories is available. |
671 | ||
6dd5b57e UD |
672 | The type @code{nl_type} is defined in @file{nl_types.h}. The argument |
673 | @var{item} is a numeric value defined in the header @file{langinfo.h}. | |
674 | The X/Open standard defines the following values: | |
85c165be UD |
675 | |
676 | @vtable @code | |
677 | @item ABDAY_1 | |
678 | @itemx ABDAY_2 | |
679 | @itemx ABDAY_3 | |
680 | @itemx ABDAY_4 | |
681 | @itemx ABDAY_5 | |
682 | @itemx ABDAY_6 | |
683 | @itemx ABDAY_7 | |
684 | @code{nl_langinfo} returns the abbreviated weekday name. @code{ABDAY_1} | |
685 | corresponds to Sunday. | |
686 | @item DAY_1 | |
687 | @itemx DAY_2 | |
688 | @itemx DAY_3 | |
689 | @itemx DAY_4 | |
690 | @itemx DAY_5 | |
691 | @itemx DAY_6 | |
692 | @itemx DAY_7 | |
6dd5b57e | 693 | Similar to @code{ABDAY_1} etc., but here the return value is the |
5e0889da | 694 | unabbreviated weekday name. |
85c165be UD |
695 | @item ABMON_1 |
696 | @itemx ABMON_2 | |
697 | @itemx ABMON_3 | |
698 | @itemx ABMON_4 | |
699 | @itemx ABMON_5 | |
700 | @itemx ABMON_6 | |
701 | @itemx ABMON_7 | |
702 | @itemx ABMON_8 | |
703 | @itemx ABMON_9 | |
704 | @itemx ABMON_10 | |
705 | @itemx ABMON_11 | |
706 | @itemx ABMON_12 | |
6dd5b57e | 707 | The return value is abbreviated name of the month. @code{ABMON_1} |
85c165be UD |
708 | corresponds to January. |
709 | @item MON_1 | |
710 | @itemx MON_2 | |
711 | @itemx MON_3 | |
712 | @itemx MON_4 | |
713 | @itemx MON_5 | |
714 | @itemx MON_6 | |
715 | @itemx MON_7 | |
716 | @itemx MON_8 | |
717 | @itemx MON_9 | |
718 | @itemx MON_10 | |
719 | @itemx MON_11 | |
720 | @itemx MON_12 | |
6dd5b57e | 721 | Similar to @code{ABMON_1} etc., but here the month names are not abbreviated. |
85c165be UD |
722 | Here the first value @code{MON_1} also corresponds to January. |
723 | @item AM_STR | |
724 | @itemx PM_STR | |
6dd5b57e UD |
725 | The return values are strings which can be used in the representation of time |
726 | as an hour from 1 to 12 plus an am/pm specifier. | |
85c165be | 727 | |
6dd5b57e UD |
728 | Note that in locales which do not use this time representation |
729 | these strings might be empty, in which case the am/pm format | |
85c165be UD |
730 | cannot be used at all. |
731 | @item D_T_FMT | |
732 | The return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 733 | represent time and date in a locale-specific way. |
85c165be UD |
734 | @item D_FMT |
735 | The return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 736 | represent a date in a locale-specific way. |
85c165be UD |
737 | @item T_FMT |
738 | The return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 739 | represent time in a locale-specific way. |
85c165be UD |
740 | @item T_FMT_AMPM |
741 | The return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 742 | represent time in the am/pm format. |
85c165be | 743 | |
6dd5b57e UD |
744 | Note that if the am/pm format does not make any sense for the |
745 | selected locale, the return value might be the same as the one for | |
85c165be UD |
746 | @code{T_FMT}. |
747 | @item ERA | |
6dd5b57e UD |
748 | The return value represents the era used in the current locale. |
749 | ||
750 | Most locales do not define this value. An example of a locale which | |
751 | does define this value is the Japanese one. In Japan, the traditional | |
752 | representation of dates includes the name of the era corresponding to | |
753 | the then-emperor's reign. | |
754 | ||
755 | Normally it should not be necessary to use this value directly. | |
756 | Specifying the @code{E} modifier in their format strings causes the | |
757 | @code{strftime} functions to use this information. The format of the | |
758 | returned string is not specified, and therefore you should not assume | |
759 | knowledge of it on different systems. | |
85c165be | 760 | @item ERA_YEAR |
6dd5b57e | 761 | The return value gives the year in the relevant era of the locale. |
85c165be UD |
762 | As for @code{ERA} it should not be necessary to use this value directly. |
763 | @item ERA_D_T_FMT | |
764 | This return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 765 | represent dates and times in a locale-specific era-based way. |
85c165be UD |
766 | @item ERA_D_FMT |
767 | This return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 768 | represent a date in a locale-specific era-based way. |
85c165be UD |
769 | @item ERA_T_FMT |
770 | This return value can be used as a format string for @code{strftime} to | |
6dd5b57e | 771 | represent time in a locale-specific era-based way. |
85c165be UD |
772 | @item ALT_DIGITS |
773 | The return value is a representation of up to @math{100} values used to | |
774 | represent the values @math{0} to @math{99}. As for @code{ERA} this | |
775 | value is not intended to be used directly, but instead indirectly | |
776 | through the @code{strftime} function. When the modifier @code{O} is | |
6dd5b57e UD |
777 | used in a format which would otherwise use numerals to represent hours, |
778 | minutes, seconds, weekdays, months, or weeks, the appropriate value for | |
779 | the locale is used instead. | |
85c165be | 780 | @item INT_CURR_SYMBOL |
6dd5b57e | 781 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
782 | @code{int_curr_symbol} element of the @code{struct lconv}. |
783 | @item CURRENCY_SYMBOL | |
784 | @itemx CRNCYSTR | |
6dd5b57e | 785 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
786 | @code{currency_symbol} element of the @code{struct lconv}. |
787 | ||
6dd5b57e | 788 | @code{CRNCYSTR} is a deprecated alias still required by Unix98. |
85c165be | 789 | @item MON_DECIMAL_POINT |
6dd5b57e | 790 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
791 | @code{mon_decimal_point} element of the @code{struct lconv}. |
792 | @item MON_THOUSANDS_SEP | |
6dd5b57e | 793 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
794 | @code{mon_thousands_sep} element of the @code{struct lconv}. |
795 | @item MON_GROUPING | |
6dd5b57e | 796 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
797 | @code{mon_grouping} element of the @code{struct lconv}. |
798 | @item POSITIVE_SIGN | |
6dd5b57e | 799 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
800 | @code{positive_sign} element of the @code{struct lconv}. |
801 | @item NEGATIVE_SIGN | |
6dd5b57e | 802 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
803 | @code{negative_sign} element of the @code{struct lconv}. |
804 | @item INT_FRAC_DIGITS | |
6dd5b57e | 805 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
806 | @code{int_frac_digits} element of the @code{struct lconv}. |
807 | @item FRAC_DIGITS | |
6dd5b57e | 808 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
809 | @code{frac_digits} element of the @code{struct lconv}. |
810 | @item P_CS_PRECEDES | |
6dd5b57e | 811 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
812 | @code{p_cs_precedes} element of the @code{struct lconv}. |
813 | @item P_SEP_BY_SPACE | |
6dd5b57e | 814 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
815 | @code{p_sep_by_space} element of the @code{struct lconv}. |
816 | @item N_CS_PRECEDES | |
6dd5b57e | 817 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
818 | @code{n_cs_precedes} element of the @code{struct lconv}. |
819 | @item N_SEP_BY_SPACE | |
6dd5b57e | 820 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
821 | @code{n_sep_by_space} element of the @code{struct lconv}. |
822 | @item P_SIGN_POSN | |
6dd5b57e | 823 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
824 | @code{p_sign_posn} element of the @code{struct lconv}. |
825 | @item N_SIGN_POSN | |
6dd5b57e | 826 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
827 | @code{n_sign_posn} element of the @code{struct lconv}. |
828 | @item DECIMAL_POINT | |
829 | @itemx RADIXCHAR | |
6dd5b57e | 830 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
831 | @code{decimal_point} element of the @code{struct lconv}. |
832 | ||
833 | The name @code{RADIXCHAR} is a deprecated alias still used in Unix98. | |
834 | @item THOUSANDS_SEP | |
835 | @itemx THOUSEP | |
6dd5b57e | 836 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
837 | @code{thousands_sep} element of the @code{struct lconv}. |
838 | ||
839 | The name @code{THOUSEP} is a deprecated alias still used in Unix98. | |
840 | @item GROUPING | |
6dd5b57e | 841 | The same as the value returned by @code{localeconv} in the |
85c165be UD |
842 | @code{grouping} element of the @code{struct lconv}. |
843 | @item YESEXPR | |
844 | The return value is a regular expression which can be used with the | |
845 | @code{regex} function to recognize a positive response to a yes/no | |
846 | question. | |
847 | @item NOEXPR | |
848 | The return value is a regular expression which can be used with the | |
849 | @code{regex} function to recognize a negative response to a yes/no | |
850 | question. | |
851 | @item YESSTR | |
6dd5b57e | 852 | The return value is a locale-specific translation of the positive response |
85c165be UD |
853 | to a yes/no question. |
854 | ||
855 | Using this value is deprecated since it is a very special case of | |
6dd5b57e | 856 | message translation, and is better handled by the message |
85c165be UD |
857 | translation functions (@pxref{Message Translation}). |
858 | @item NOSTR | |
6dd5b57e | 859 | The return value is a locale-specific translation of the negative response |
85c165be UD |
860 | to a yes/no question. What is said for @code{YESSTR} is also true here. |
861 | @end vtable | |
862 | ||
863 | The file @file{langinfo.h} defines a lot more symbols but none of them | |
6dd5b57e UD |
864 | is official. Using them is not portable, and the format of the |
865 | return values might change. Therefore we recommended you not use | |
866 | them. | |
867 | ||
868 | Note that the return value for any valid argument can be used for | |
869 | in all situations (with the possible exception of the am/pm time formatting | |
870 | codes). If the user has not selected any locale for the | |
871 | appropriate category, @code{nl_langinfo} returns the information from the | |
85c165be UD |
872 | @code{"C"} locale. It is therefore possible to use this function as |
873 | shown in the example below. | |
874 | ||
6941c42a UD |
875 | If the argument @var{item} is not valid, a pointer to an empty string is |
876 | returned. | |
85c165be UD |
877 | @end deftypefun |
878 | ||
6dd5b57e UD |
879 | An example of @code{nl_langinfo} usage is a function which has to |
880 | print a given date and time in a locale-specific way. At first one | |
881 | might think that, since @code{strftime} internally uses the locale | |
882 | information, writing something like the following is enough: | |
85c165be UD |
883 | |
884 | @smallexample | |
885 | size_t | |
886 | i18n_time_n_data (char *s, size_t len, const struct tm *tp) | |
887 | @{ | |
888 | return strftime (s, len, "%X %D", tp); | |
889 | @} | |
890 | @end smallexample | |
891 | ||
892 | The format contains no weekday or month names and therefore is | |
893 | internationally usable. Wrong! The output produced is something like | |
894 | @code{"hh:mm:ss MM/DD/YY"}. This format is only recognizable in the | |
895 | USA. Other countries use different formats. Therefore the function | |
896 | should be rewritten like this: | |
897 | ||
898 | @smallexample | |
899 | size_t | |
900 | i18n_time_n_data (char *s, size_t len, const struct tm *tp) | |
901 | @{ | |
902 | return strftime (s, len, nl_langinfo (D_T_FMT), tp); | |
903 | @} | |
904 | @end smallexample | |
905 | ||
6dd5b57e UD |
906 | Now it uses the date and time format of the locale |
907 | selected when the program runs. If the user selects the locale | |
85c165be UD |
908 | correctly there should never be a misunderstanding over the time and |
909 | date format. | |
910 | ||
d01d6319 | 911 | @node Formatting Numbers, , Locale Information, Locales |
5e0889da | 912 | @section A dedicated function to format numbers |
85c165be | 913 | |
5e0889da | 914 | We have seen that the structure returned by @code{localeconv} as well as |
6dd5b57e UD |
915 | the values given to @code{nl_langinfo} allow you to retrieve the various |
916 | pieces of locale-specific information to format numbers and monetary | |
917 | amounts. We have also seen that the underlying rules are quite complex. | |
85c165be | 918 | |
6dd5b57e UD |
919 | Therefore the X/Open standards introduce a function which uses such |
920 | locale information, making it easier for the user to format | |
85c165be UD |
921 | numbers according to these rules. |
922 | ||
923 | @deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{}) | |
924 | The @code{strfmon} function is similar to the @code{strftime} function | |
6dd5b57e UD |
925 | in that it takes a buffer, its size, a format string, |
926 | and values to write into the buffer as text in a form specified | |
927 | by the format string. Like @code{strftime}, the function | |
85c165be UD |
928 | also returns the number of bytes written into the buffer. |
929 | ||
6dd5b57e UD |
930 | There are two differences: @code{strfmon} can take more than one |
931 | argument, and, of course, the format specification is different. Like | |
932 | @code{strftime}, the format string consists of normal text, which is | |
933 | output as is, and format specifiers, which are indicated by a @samp{%}. | |
934 | Immediately after the @samp{%}, you can optionally specify various flags | |
935 | and formatting information before the main formatting character, in a | |
936 | similar way to @code{printf}: | |
85c165be UD |
937 | |
938 | @itemize @bullet | |
939 | @item | |
940 | Immediately following the @samp{%} there can be one or more of the | |
941 | following flags: | |
942 | @table @asis | |
943 | @item @samp{=@var{f}} | |
944 | The single byte character @var{f} is used for this field as the numeric | |
945 | fill character. By default this character is a space character. | |
946 | Filling with this character is only performed if a left precision | |
947 | is specified. It is not just to fill to the given field width. | |
948 | @item @samp{^} | |
6dd5b57e UD |
949 | The number is printed without grouping the digits according to the rules |
950 | of the current locale. By default grouping is enabled. | |
85c165be | 951 | @item @samp{+}, @samp{(} |
6dd5b57e UD |
952 | At most one of these flags can be used. They select which format to |
953 | represent the sign of a currency amount. By default, and if | |
954 | @samp{+} is given, the locale equivalent of @math{+}/@math{-} is used. If | |
955 | @samp{(} is given, negative amounts are enclosed in parentheses. The | |
85c165be UD |
956 | exact format is determined by the values of the @code{LC_MONETARY} |
957 | category of the locale selected at program runtime. | |
958 | @item @samp{!} | |
959 | The output will not contain the currency symbol. | |
960 | @item @samp{-} | |
6dd5b57e UD |
961 | The output will be formatted left-justified instead of right-justified if |
962 | it does not fill the entire field width. | |
85c165be UD |
963 | @end table |
964 | @end itemize | |
965 | ||
6dd5b57e UD |
966 | The next part of a specification is an optional field width. If no |
967 | width is specified @math{0} is taken. During output, the function first | |
968 | determines how much space is required. If it requires at least as many | |
969 | characters as given by the field width, it is output using as much space | |
970 | as necessary. Otherwise, it is extended to use the full width by | |
971 | filling with the space character. The presence or absence of the | |
972 | @samp{-} flag determines the side at which such padding occurs. If | |
973 | present, the spaces are added at the right making the output | |
974 | left-justified, and vice versa. | |
975 | ||
976 | So far the format looks familiar, being similar to the @code{printf} and | |
977 | @code{strftime} formats. However, the next two optional fields | |
978 | introduce something new. The first one is a @samp{#} character followed | |
979 | by a decimal digit string. The value of the digit string specifies the | |
980 | number of @emph{digit} positions to the left of the decimal point (or | |
981 | equivalent). This does @emph{not} include the grouping character when | |
982 | the @samp{^} flag is not given. If the space needed to print the number | |
983 | does not fill the whole width, the field is padded at the left side with | |
984 | the fill character, which can be selected using the @samp{=} flag and by | |
985 | default is a space. For example, if the field width is selected as 6 | |
986 | and the number is @math{123}, the fill character is @samp{*} the result | |
987 | will be @samp{***123}. | |
988 | ||
989 | The second optional field starts with a @samp{.} (period) and consists | |
990 | of another decimal digit string. Its value describes the number of | |
991 | characters printed after the decimal point. The default is selected | |
992 | from the current locale (@code{frac_digits}, @code{int_frac_digits}, see | |
993 | @pxref{General Numeric}). If the exact representation needs more digits | |
994 | than given by the field width, the displayed value is rounded. If the | |
995 | number of fractional digits is selected to be zero, no decimal point is | |
996 | printed. | |
997 | ||
998 | As a GNU extension, the @code{strfmon} implementation in the GNU libc | |
999 | allows an optional @samp{L} next as a format modifier. If this modifier | |
1000 | is given, the argument is expected to be a @code{long double} instead of | |
1001 | a @code{double} value. | |
1002 | ||
1003 | Finally, the last component is a format specifier. There are three | |
1004 | specifiers defined: | |
85c165be UD |
1005 | |
1006 | @table @asis | |
1007 | @item @samp{i} | |
6dd5b57e | 1008 | Use the locale's rules for formatting an international currency value. |
85c165be | 1009 | @item @samp{n} |
6dd5b57e | 1010 | Use the locale's rules for formatting a national currency value. |
85c165be | 1011 | @item @samp{%} |
6dd5b57e | 1012 | Place a @samp{%} in the output. There must be no flag, width |
85c165be UD |
1013 | specifier or modifier given, only @samp{%%} is allowed. |
1014 | @end table | |
1015 | ||
6dd5b57e | 1016 | As for @code{printf}, the function reads the format string |
5e0889da UD |
1017 | from left to right and uses the values passed to the function following |
1018 | the format string. The values are expected to be either of type | |
1019 | @code{double} or @code{long double}, depending on the presence of the | |
85c165be UD |
1020 | modifier @samp{L}. The result is stored in the buffer pointed to by |
1021 | @var{s}. At most @var{maxsize} characters are stored. | |
1022 | ||
1023 | The return value of the function is the number of characters stored in | |
6dd5b57e UD |
1024 | @var{s}, including the terminating @code{NULL} byte. If the number of |
1025 | characters stored would exceed @var{maxsize}, the function returns | |
85c165be UD |
1026 | @math{-1} and the content of the buffer @var{s} is unspecified. In this |
1027 | case @code{errno} is set to @code{E2BIG}. | |
1028 | @end deftypefun | |
1029 | ||
6dd5b57e | 1030 | A few examples should make clear how the function works. It is |
85c165be | 1031 | assumed that all the following pieces of code are executed in a program |
6dd5b57e | 1032 | which uses the USA locale (@code{en_US}). The simplest |
85c165be UD |
1033 | form of the format is this: |
1034 | ||
1035 | @smallexample | |
1036 | strfmon (buf, 100, "@@%n@@%n@@%n@@", 123.45, -567.89, 12345.678); | |
1037 | @end smallexample | |
1038 | ||
1039 | @noindent | |
1040 | The output produced is | |
1041 | @smallexample | |
655b26bb | 1042 | "@@$123.45@@-$567.89@@$12,345.68@@" |
85c165be UD |
1043 | @end smallexample |
1044 | ||
6dd5b57e UD |
1045 | We can notice several things here. First, the widths of the output |
1046 | numbers are different. We have not specified a width in the format | |
1047 | string, and so this is no wonder. Second, the third number is printed | |
1048 | using thousands separators. The thousands separator for the | |
1049 | @code{en_US} locale is a comma. The number is also rounded. | |
1050 | @math{.678} is rounded to @math{.68} since the format does not specify a | |
1051 | precision and the default value in the locale is @math{2}. Finally, | |
1052 | note that the national currency symbol is printed since @samp{%n} was | |
1053 | used, not @samp{i}. The next example shows how we can align the output. | |
85c165be UD |
1054 | |
1055 | @smallexample | |
1056 | strfmon (buf, 100, "@@%=*11n@@%=*11n@@%=*11n@@", 123.45, -567.89, 12345.678); | |
1057 | @end smallexample | |
1058 | ||
1059 | @noindent | |
1060 | The output this time is: | |
1061 | ||
1062 | @smallexample | |
655b26bb | 1063 | "@@ $123.45@@ -$567.89@@ $12,345.68@@" |
85c165be UD |
1064 | @end smallexample |
1065 | ||
6dd5b57e | 1066 | Two things stand out. Firstly, all fields have the same width (eleven |
85c165be UD |
1067 | characters) since this is the width given in the format and since no |
1068 | number required more characters to be printed. The second important | |
1069 | point is that the fill character is not used. This is correct since the | |
6dd5b57e UD |
1070 | white space was not used to achieve a precision given by a @samp{#} |
1071 | modifier, but instead to fill to the given width. The difference | |
1072 | becomes obvious if we now add a width specification. | |
85c165be UD |
1073 | |
1074 | @smallexample | |
1075 | strfmon (buf, 100, "@@%=*11#5n@@%=*11#5n@@%=*11#5n@@", | |
1076 | 123.45, -567.89, 12345.678); | |
1077 | @end smallexample | |
1078 | ||
1079 | @noindent | |
1080 | The output is | |
1081 | ||
1082 | @smallexample | |
1083 | "@@ $***123.45@@-$***567.89@@ $12,456.68@@" | |
1084 | @end smallexample | |
1085 | ||
6dd5b57e UD |
1086 | Here we can see that all the currency symbols are now aligned, and that |
1087 | the space between the currency sign and the number is filled with the | |
1088 | selected fill character. Note that although the width is selected to be | |
1089 | @math{5} and @math{123.45} has three digits left of the decimal point, | |
1090 | the space is filled with three asterisks. This is correct since, as | |
1091 | explained above, the width does not include the positions used to store | |
1092 | thousands separators. One last example should explain the remaining | |
1093 | functionality. | |
85c165be UD |
1094 | |
1095 | @smallexample | |
1096 | strfmon (buf, 100, "@@%=0(16#5.3i@@%=0(16#5.3i@@%=0(16#5.3i@@", | |
1097 | 123.45, -567.89, 12345.678); | |
1098 | @end smallexample | |
1099 | ||
1100 | @noindent | |
1101 | This rather complex format string produces the following output: | |
1102 | ||
1103 | @smallexample | |
1104 | "@@ USD 000123,450 @@(USD 000567.890)@@ USD 12,345.678 @@" | |
1105 | @end smallexample | |
1106 | ||
6dd5b57e UD |
1107 | The most noticeable change is the alternative way of representing |
1108 | negative numbers. In financial circles this is often done using | |
1109 | parentheses, and this is what the @samp{(} flag selected. The fill | |
1110 | character is now @samp{0}. Note that this @samp{0} character is not | |
1111 | regarded as a numeric zero, and therefore the first and second numbers | |
1112 | are not printed using a thousands separator. Since we used the format | |
1113 | specifier @samp{i} instead of @samp{n}, the international form of the | |
85c165be | 1114 | currency symbol is used. This is a four letter string, in this case |
6dd5b57e UD |
1115 | @code{"USD "}. The last point is that since the precision right of the |
1116 | decimal point is selected to be three, the first and second numbers are | |
1117 | printed with an extra zero at the end and the third number is printed | |
1118 | without rounding. |