1STRFMON(P) POSIX Programmer's Manual STRFMON(P)
2
6 strfmon - convert monetary value to a string
7
9 #include <monetary.h>
10 ssize_t strfmon(char *restrict s, size_t maxsize,
12 const char *restrict format, ...);
13
16 The strfmon() function shall place characters into the array pointed to
17 by s as controlled by the string pointed to by format. No more than
18 maxsize bytes are placed into the array.
19 The format is a character string, beginning and ending in its initial
21 state, if any, that contains two types of objects: plain characters,
22 which are simply copied to the output stream, and conversion specifica‐
23 tions, each of which shall result in the fetching of zero or more argu‐
24 ments which are converted and formatted. The results are undefined if
25 there are insufficient arguments for the format. If the format is
26 exhausted while arguments remain, the excess arguments are simply
27 ignored.
28 The application shall ensure that a conversion specification consists
30 of the following sequence:
31 * A '%' character
33 * Optional flags
35 * Optional field width
37 * Optional left precision
39 * Optional right precision
41 * A required conversion specifier character that determines the con‐
43 version to be performed
44 Flags
46 One or more of the following optional flags can be specified to control
47 the conversion:
48 =f An '=' followed by a single character f which is used as the
50 numeric fill character. In order to work with precision or width
51 counts, the fill character shall be a single byte character; if
52 not, the behavior is undefined. The default numeric fill charac‐
53 ter is the <space>. This flag does not affect field width fill‐
54 ing which always uses the <space>. This flag is ignored unless
55 a left precision (see below) is specified.
56 ^ Do not format the currency amount with grouping characters. The
58 default is to insert the grouping characters if defined for the
59 current locale.
60 + or ( Specify the style of representing positive and negative currency
62 amounts. Only one of '+' or '(' may be specified. If '+' is
63 specified, the locale's equivalent of '+' and '-' are used (for
64 example, in the U.S., the empty string if positive and '-' if
65 negative). If '(' is specified, negative amounts are enclosed
66 within parentheses. If neither flag is specified, the '+' style
67 is used.
68 ! Suppress the currency symbol from the output conversion.
70 - Specify the alignment. If this flag is present the result of the
72 conversion is left-justified (padded to the right) rather than
73 right-justified. This flag shall be ignored unless a field width
74 (see below) is specified.
75 Field Width
78 w A decimal digit string w specifying a minimum field width in
79 bytes in which the result of the conversion is right-justified
80 (or left-justified if the flag '-' is specified). The default
81 is 0.
82 Left Precision
85 #n A '#' followed by a decimal digit string n specifying a maximum
86 number of digits expected to be formatted to the left of the
87 radix character. This option can be used to keep the formatted
88 output from multiple calls to the strfmon() function aligned in
89 the same columns. It can also be used to fill unused positions
90 with a special character as in "$***123.45" . This option causes
91 an amount to be formatted as if it has the number of digits
92 specified by n. If more than n digit positions are required,
93 this conversion specification is ignored. Digit positions in
94 excess of those actually required are filled with the numeric
95 fill character (see the =f flag above).
96 If grouping has not been suppressed with the '^' flag, and it is
98 defined for the current locale, grouping separators are inserted before
99 the fill characters (if any) are added. Grouping separators are not
100 applied to fill characters even if the fill character is a digit.
101 To ensure alignment, any characters appearing before or after the num‐
103 ber in the formatted output such as currency or sign symbols are padded
104 as necessary with <space>s to make their positive and negative formats
105 an equal length.
106 Right Precision
109 .p A period followed by a decimal digit string p specifying the
110 number of digits after the radix character. If the value of the
111 right precision p is 0, no radix character appears. If a right
112 precision is not included, a default specified by the current
113 locale is used. The amount being formatted is rounded to the
114 specified number of digits prior to formatting.
115 Conversion Specifier Characters
118 The conversion specifier characters and their meanings are:
119 i The double argument is formatted according to the locale's
121 international currency format (for example, in the U.S.: USD
122 1,234.56). If the argument is ±Inf or NaN, the result of the
123 conversion is unspecified.
124 n The double argument is formatted according to the locale's
126 national currency format (for example, in the U.S.: $1,234.56).
127 If the argument is ±Inf or NaN, the result of the conversion is
128 unspecified.
129 % Convert to a '%' ; no argument is converted. The entire conver‐
131 sion specification shall be %% .
132 Locale Information
135 The LC_MONETARY category of the program's locale affects the behavior
136 of this function including the monetary radix character (which may be
137 different from the numeric radix character affected by the LC_NUMERIC
138 category), the grouping separator, the currency symbols, and formats.
139 The international currency symbol should be conformant with the
140 ISO 4217:1995 standard.
141 If the value of maxsize is greater than {SSIZE_MAX}, the result is
143 implementation-defined.
144
146 If the total number of resulting bytes including the terminating null
147 byte is not more than maxsize, strfmon() shall return the number of
148 bytes placed into the array pointed to by s, not including the termi‐
149 nating null byte. Otherwise, -1 shall be returned, the contents of the
150 array are unspecified, and errno shall be set to indicate the error.
151
153 The strfmon() function shall fail if:
154 E2BIG Conversion stopped due to lack of space in the buffer.
156 The following sections are informative.
159
161 Given a locale for the U.S. and the values 123.45, -123.45, and
162 3456.781, the following output might be produced. Square brackets (
163 "[]" ) are used in this example to delimit the output.
164 %n [$123.45] Default formatting
167 [-$123.45]
168 [$3,456.78]
169 %11n [ $123.45] Right align within an 11-character field
172 [ -$123.45]
173 [ $3,456.78]
174 %#5n [ $ 123.45] Aligned columns for values up to 99999
177 [-$ 123.45]
178 [ $ 3,456.78]
179 %=*#5n [ $***123.45] Specify a fill character
182 [-$***123.45]
183 [ $*3,456.78]
184 %=0#5n [ $000123.45] Fill characters do not use grouping
187 [-$000123.45] even if the fill character is a digit
188 [ $03,456.78]
189 %^#5n [ $ 123.45] Disable the grouping separator
192 [-$ 123.45]
193 [ $ 3456.78]
194 %^#5.0n [ $ 123] Round off to whole units
197 [-$ 123]
198 [ $ 3457]
199 %^#5.4n [ $ 123.4500] Increase the precision
202 [-$ 123.4500]
203 [ $ 3456.7810]
204 %(#5n [$ 123.45] Use an alternative pos/neg style
207 [($ 123.45)]
208 [$ 3,456.78]
209 %!(#5n [ 123.45] Disable the currency symbol
212 [( 123.45)]
213 [ 3,456.78]
214 %-14#5.4n [ $ 123.4500 ] Left-justify the output
217 [-$ 123.4500 ]
218 [ $ 3,456.7810 ]
219 %14#5.4n [ $ 123.4500] Corresponding right-justified output
222 [ -$ 123.4500]
223 [ $ 3,456.7810]
224 See also the EXAMPLES section in fprintf().
226
228 None.
229
231 None.
232
234 Lowercase conversion characters are reserved for future standards use
235 and uppercase for implementation-defined use.
236
238 fprintf() , localeconv() , the Base Definitions volume of
239 IEEE Std 1003.1-2001, <monetary.h>
240
242 Portions of this text are reprinted and reproduced in electronic form
243 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
244 -- Portable Operating System Interface (POSIX), The Open Group Base
245 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
246 Electrical and Electronics Engineers, Inc and The Open Group. In the
247 event of any discrepancy between this version and the original IEEE and
248 The Open Group Standard, the original IEEE and The Open Group Standard
249 is the referee document. The original Standard can be obtained online
250 at http://www.opengroup.org/unix/online.html .
251IEEE/The Open Group 2003 STRFMON(P)