strfmon - Convert Monetary Value to String
#include <monetary.h>
int strfmon(char *s, size_t maxsize, const char *format, ...);
Description
strfmon places characters into the array pointed to by *s, as controlled
by the string pointed to by format. No more than maxsize bytes
are placed into the array.
The character string format contains two types of objects:
- Plain characters, which are copied to the output
array.
- Directives, each of which results in the fetching
of zero or more arguments that are converted and formatted.
The results are undefined if there are insufficient arguments for the format.
If the format is exhausted while arguments remain, the excess arguments
are simply ignored. If objects pointed to by s and format overlap,
the behavior is undefined.
The directive (conversion specification) consists of the following sequence.
- A % character
- Optional flags, described below: =f,
^, then +, (, then !
- Optional field width (may be preceded by -)
- Optional left precision: #n
- Optional right precision: .p
- Required conversion character to indicate what
conversion should be performed: i or n.
Each directive is replaced by the appropriate characters, as described in
the following list:
- i
The double argument is formatted according
to the locale's international currency format (for example, in USA: USD
1,234.56).
%n
The double
argument is formatted according to the locale's national currency format
(for example, in USA: $1,234.56).
- is replaced by %. No argument is converted.
You can give optional conversion specifications immediately after the initial
% of a directive in the following order:
Specifier
=f
Specifies f as the numeric fill character.
This flag is used in conjunction with the maximum digits specification #n
(see below). The default numeric fill character is the space character.
This option does not affect the other fill operations that always use a
space as the fill character.
^
Formats
the currency amount without thousands grouping characters. The default is
to insert the grouping characters if defined for the current locale.
+
| (
Specifies the style of representing positive
and negative currency amounts. You can specify only one of + or (. The +
specifies to use the locale's equivalent of + and -. For example, in USA,
the empty (null) string if positive and - if negative. The ( specifies to
use the locale's equivalent of enclosing negative amounts within parenthesis.
If this option is not included, a default specified by the current locale
is used.
!
Suppresses
the currency symbol from the output conversion.
[-]w
A decimal digit string that specifies a minimum
field width in which the result of the conversion is right-justified (or
left-justified if the - flag is specified).
#n
A decimal digit string that specifies a maximum
number of digits expected to be formatted to the left of the radix character.
You can use this option to keep the formatted output from multiple calls
to strfmon aligned in the same columns. You can also use it to fill unused
positions with a special character, as in $***123.45. This option causes
an amount to be formatted as if it has the number of digits specified by
n. If more digit positions are required than specified, this conversion
specification is ignored. Digit positions in excess of those actually required
are filled with the numeric fill character. (See the =f specification
above).
If thousands grouping is enabled, the behavior is:
- Format the number as if it is an n digit
number.
- Insertfillcharacterstotheleftoftheleftmostdigit(
forexample ,$ 0001234 . 56or$ * * * 1234 . 56 ) .
- Insert the separator character (for example,
$0,001,234.56 or $*,**1,234.56).
- If the fill character is not the digit zero,
the separators are replaced by the fill character (for example, $****1,234.56).
To ensure alignment, any characters appearing before
or after the number in the formatted output, such as currency or sign symbols,
are padded with space characters to make their positive and negative formats
an equal length.
.p
A
decimal digit string that specifies the number of digits after the radix
character. If the value of the precision p is 0, no radix character
appears. If this option is not included, a default specified by the current
locale is used. The amount being formatted is rounded to the specified number
of digits prior to formatting.
The LC_MONETARY category of the program's locale affects the behavior of
this function, including the monetary radix character (which is different
from the numeric radix character affected by the LC_NUMERIC category), the
thousands (or alternate grouping) separator, the currency symbols, and formats.
Returns
If the total number of resulting bytes including the terminating null character
is not more than maxsize, strfmon returns the number of bytes placed
into the array pointed to by s, not including the terminating null
character. Otherwise, strfmon returns -1 and the contents of the array are
indeterminate.
Example Code
This example uses strfmon to format the monetary value for money, then prints
the resulting string.
#include <monetary.h>#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
char string[100]; /* hold the string returned from strfmon() */
double money = 1234.56;
if (NULL == setlocale(LC_ALL, "en_us.ibm-850")) {
printf("Unable to setlocale().\n");
exit(EXIT_FAILURE);
}
strfmon(string, 100, "%i", money);
printf("International currency format = \"%s\"\n", string);
strfmon(string, 100, "%n", money);
printf("National currency format = \"%s\"\n", string);
return 0;
/****************************************************************************
The output should be similar to :
International currency format = "USD 1,234.56"
National currency format = "$1,234.56"
****************************************************************************/
}
Related Information