### strfmon -- Convert Monetary Value to String

Format

>     #include <monetary.h>
>     int strfmon(char *s, size_t maxsize, const char *format, ...);

Language Level: XPG4
strfmon places characters into the array pointed to by s, as controlled by the string pointed to by format. No more than maxsize characters 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.

1. A % character
2. Optional flags, described below: =f, ^, then +, C, (, then !
3. Optional field width (may be preceded by -)
4. Optional left precision: #n
5. Optional right precision: .p
6. 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 | Meaning
=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.
+ | C | ( | Specifies the style of representing positive and negative currency amounts. You can specify only one of +, C, or (. The + specifies to use the locale's equivalent of + and -. C specifies to use the locale's equivalent of DB for negative and CR for positive. 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. Insert fill characters to the left of the leftmost digit (for example, $0001234.56 or $***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. The international currency symbol should be in accordance with those specified in ISO 4217 Codes for the representation of currencies and funds.

Return Value
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
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>

    #if (1 == __TOS_OS2__)
       #define LOCNAME "en_us.ibm-437"      /* OS/2 name */
    #else
       #define LOCNAME "en_us.ibm-1252"  /* Windows name */
    #endif

    int main(void)
    {
       char string[100];   /* hold the string returned from strfmon() */
       double money = 1234.56;

       if (NULL == setlocale(LC_ALL, LOCNAME)) {
          printf("Locale \"%s\" could not be loaded\n", LOCNAME);
          exit(1);
       }
       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"
       ***************************************************/
    }

strftime -- Convert to Formatted Time
<monetary.h>