HELPLIB.HLB  —  CRTL  strfmon
    Converts a number of monetary values into a string. The
    conversion is controlled by a format string.

    Format

      #include  <monetary.h>

      ssize_t strfmon  (char *s, size_t maxsize, const char
                       *format, . . . );

1  –  Arguments

 s

    A pointer to the resultant string.

 maxsize

    The maximum number of bytes to be stored in the resultant string.

 format

    A pointer to a string that controls the format of the output
    string.

  . . .

    The monetary values of type double that are to be formatted for
    the output string. There should be as many values as there are
    conversion specifications in the format string pointed to by
    format. The function fails if there are insufficient values.
    Excess arguments are ignored.

2  –  Description

    The strfmon function creates a string pointed to by s, using the
    monetary values supplied. A maximum of maxsize bytes is copied to
    s.

    The format string pointed to by format consists of ordinary
    characters and conversion specifications. All ordinary characters
    are copied unchanged to the output string. A conversion
    specification defines how one of the monetary values supplied
    is formatted in the output string.

    A conversion specification consists of a percent character
    (%), followed by a number of optional characters (see Optional
    Characters in strfmon Conversion Specifications), and concluding
    with a conversion specifier (see strfmon Conversion Specifiers).

    If any of the optional characters listed in Optional Characters
    in strfmon Conversion Specifications is included in a conversion
    specification, they must appear in the order shown.

    Table REF-5 Optional Characters in strfmon Conversion
                Specifications

    Character     Meaning

                  left precision is specified. The default numeric
                  fill character is the space character. The fill
                  character must be representable as a single byte
                  in order to work with precision and width count.
                  This conversion specifier is ignored unless a
                  left precision is specified, and it does not
                  affect width filling, which always uses the space
                  character.
    ^             Do not use separator characters to format the
                  number. By default, the digits are grouped
                  according to the mon_grouping field in the LC_
                  MONETARY category of the current locale.
    +             Add the string specified by the positive_sign
                  or negative_sign fields in the current locale.
                  If p_sign_posn or n_sign_posn is set to 0, then
                  parentheses are used by default to indicate
                  negative values. Otherwise, sign strings are used
                  to indicate the sign of the value. You cannot use a
                  + and a ( in the same conversion specification.
    (             Enclose negative values within parentheses. The
                  default is taken from the p_sign_posn and n_sign_
                  posn fields in the current locale. If p_sign_
                  posn or n_sign_posn is set to 0, then parentheses
                  are used by default to indicate negative values.
                  Otherwise, sign strings are used to indicate the
                  sign of the value. You cannot use a + and ( in the
                  same conversion specification.
    !             Suppress the currency symbol. By default, the
                  currency symbol is included.
    -             Left-justify the value within the field. By
                  default, values are right-justified.
    field width   A decimal integer that specifies the minimum
                  field width in which to align the result of the
                  conversion. The default field width is the smallest
                  field that can contain the result.
    #left_        A # followed by a decimal integer specifies
    precision     the number of digits to the left of the radix
                  character. Extra positions are filled by the
                  fill character. By default the precision is the
                  smallest required for the argument. If grouping
                  is not suppressed with the ^ conversion specifier,
                  and if grouping is defined for the current locale,
                  grouping separators are inserted before any fill
                  characters are added. Grouping separators are
                  not applied to fill characters even if the fill
                  character is defined as a digit.
    .right_       A period (.) followed by a decimal integer
    precision     specifies the number of digits to the right of
                  the radix character. Extra positions are filled
                  with zeros. The amount is rounded to this number
                  of decimal places. If the right precision is zero,
                  the radix character is not included in the output.
                  By default the right precision is defined by the
                  frac_digits or int_frac_digits field of the current
                  locale.

    Table REF-6 strfmon Conversion Specifiers

    SpecifierMeaning

    i        Use the international currency symbol defined by the
             int_currency_symbol field in the current locale, unless
             the currency symbol has been suppressed.
    n        Use the local currency symbol defined by the currency_
             symbol field in the current locale, unless the currency
             symbol has been suppressed.
    %        Output a % character. The conversion specification must
             be %%; none of the optional characters is valid with
             this specifier.

3  –  Return Values

    x                  The number of bytes written to the string
                       pointed to by s, not including the null-
                       terminating character.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - A conversion specification is
                          syntactically incorrect.

                       o  E2BIG - Processing the complete format
                          string would produce more than maxsize
                          bytes.

4  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <locale.h>
        #include <monetary.h>
        #include <errno.h>

        #define MAX_BUF_SIZE 124

        main()
        {
          size_t ret;
          char buffer[MAX_BUF_SIZE];
          double amount = 102593421;

         /* Display a monetary amount using the en_US.ISO8859-1 */
         /* locale and a range of different display formats.    */

          if (setlocale(LC_ALL, "en_US.ISO8859-1") == (char *) NULL) {
              perror("setlocale");
              exit(EXIT_FAILURE);
          }
          ret = strfmon(buffer, MAX_BUF_
 SIZE, "International: %i\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %n\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %=*#10n\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:     %(n\n", -1 * amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %^!n\n", amount);
          printf(buffer);
        }

    Running the example program produces the following result:

    International: USD 102,593,421.00
    National:      $102,593,421.00
    National:      $**102,593,421.00
    National:      ($102,593,421.00)
    National:      102593421.00
Close Help