Technical Reference: Base Operating System and Extensions, Volume 2

strfmon Subroutine

Purpose

Formats monetary strings.

Library

Standard C Library (libc. a)

Syntax

#include <monetary.h>

ssize_t strfmon ( S, MaxSize, Format, ...) char *S; size_t MaxSize; const char *Format, ...;

Description

The strfmon subroutine converts numeric values to monetary strings according to the specifications in the Format parameter. This parameter also contains numeric values to be converted. Characters are placed into the S array, as controlled by the Format parameter. The LC_MONETARY category governs the format of the conversion.

The strfmon subroutine can be called multiple times by including additional format structures, as specified by the Format parameter.

The Format parameter specifies a character string that can contain plain characters and conversion specifications. Plain characters are copied to the output stream. Conversion specifications result in the fetching of zero or more arguments, which are converted and formatted.

If there are insufficient arguments for the Format parameter, the results are undefined. If arguments remain after the Format parameter is exhausted, the excess arguments are ignored.

A conversion specification consists of the following items in the following order: a % (percent sign), optional flags, optional field width, optional left precision, optional right precision, and a required conversion character that determines the conversion to be performed.

Parameters

S	Contains the output of the strfmon subroutine.
MaxSize	Specifies the maximum number of bytes (including the null terminating byte) that may be placed in the S parameter.
Format	Contains characters and conversion specifications.

Flags

One or more of the following flags can be specified to control the conversion:

=f	An = (equal sign) followed by a single character that specifies the numeric fill character. The default numeric fill character is the space character. This flag does not affect field-width filling, which always uses the space character. This flag is ignored unless a left precision is specified.
^	Does not use grouping characters when formatting the currency amount. The default is to insert grouping characters if defined for the current locale.
+ or (	Determines the representation of positive and negative currency amounts. Only one of these flags may be specified. The locale's equivalent of + (plus sign) and - (negative sign) are used if + is specified. The locale's equivalent of enclosing negative amounts within parentheses is used if ( (left parenthesis) is specified. If neither flag is included, a default specified by the current locale is used.
-	Left-justifies all fields (pads to the right). The default is right-justification.
!	Suppresses the currency symbol from the output conversion.

Field Width

w	The decimal-digit string w specifies the minimum field width in which the result of the conversion is right-justified. If -w is specified, the result is left-justified. The default is a value of 0.

Left Precision

A # (pound sign) followed by a decimal-digit string, n, specifies the maximum number of digits to be formatted to the left of the radix character. This option can be specified to keep formatted output from multiple calls to the strfmon subroutine aligned in the same columns. It can also be used to fill unused positions with a special character (for example, $***123.45). This option causes an amount to be formatted as if it has the number of digits specified by the n variable. If more than n digit positions are required, this option is ignored. Digit positions in excess of those required are filled with the numeric fill character set with the =f flag.

If defined for the current locale and not suppressed with the ^ flag, the subroutine inserts grouping characters before fill characters (if any). Grouping characters are not applied to fill characters, even if the fill character is a digit. In the example:

$0000001,234.56

grouping characters do not appear after the first or fourth 0 from the left.

To ensure alignment, any characters appearing before or after the number in the formatted output, such as currency or sign symbols, are padded as necessary with space characters to make their positive and negative formats equal in length.

Right Precision

A . (period) followed by a decimal digit string, p, specifies the number of digits after the radix character. If the value of the p variable is 0, no radix character is used. If a right precision is not specified, a default specified by the current locale is use. The amount being formatted is rounded to the specified number of digits prior to formatting.

Conversion Characters

i	The double argument is formatted according to the current locale's international currency format; for example, in the U.S.: `1,234.56`.
n	The double argument is formatted according to the current locale's national currency format; for example, in the U.S.: `$1,234.56`.
%	No argument is converted; the conversion specification %% is replaced by a single %.

Return Values

If successful, and if the number of resulting bytes (including the terminating null character) is not more than the number of bytes specified by the MaxSize parameter, the strfmon subroutine returns the number of bytes placed into the array pointed to by the S parameter (not including the terminating null byte). Otherwise, a value of -1 is returned and the contents of the S array are indeterminate.

Error Codes

The strfmon subroutine may fail if the following is true:

E2BIG

Conversion stopped due to lack of space in the buffer.

Related Information

The scanf (scanf, fscanf, sscanf, or wsscanf Subroutine) subroutine, strftime (strftime Subroutine) subroutine, strptime (strptime Subroutine) subroutine, wcsftime (wcsftime Subroutine) subroutine.

Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and List of Time and Monetary Formatting Subroutines in AIX 5L Version 5.2 National Language Support Guide and Reference.