strfmon man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

strfmon(3)							    strfmon(3)

NAME
       strfmon - Formats monetary strings

SYNOPSIS
       #include <monetary.h>

       ssize_t strfmon(
	       char *s,
	       size_t maxsize,
	       const char *format,
	       [,double value]...  );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       strfmon(): XSH5.0

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Contains	 the  output of the strfmon() function.	 Specifies the maximum
       number of bytes (including the  null  terminating  byte)	 that  may  be
       placed in the s parameter.  Contains characters and conversion specifi‐
       cations.	 Specifies the double data to be converted  according  to  the
       format parameter.

DESCRIPTION
       The  strfmon()  function	 converts  numeric  values to monetary strings
       according to the specifications in the format parameter.	 The  function
       converts the double-precision floating-point value parameters under the
       control of the format parameter and stores  the	result	in  the	 array
       specified by the s parameter.

       The  format  parameter is a character string that contains two types of
       objects: Literal characters, which are copied  to  the  output  stream.
       Conversion  specifications,  each of which causes zero or more items to
       be fetched from the value parameter list.

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

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

       Each conversion specification in the format parameter has the following
       syntax: A % (percent sign).  Zero or more optional flags can be	speci‐
       fied  to control the conversion. The flag characters and their meanings
       are as follows: An = (equal sign) followed by a single  character  that
       specifies  the numeric fill character. The default numeric fill charac‐
       ter is the space character. This flag does not affect field-width fill‐
       ing, which always uses the space character. This flag is ignored unless
       a left precision is specified.  The ^ (circumflex) flag suppresses  the
       grouping	 character when formatting the currency amount. The default is
       to group the digits and separate them with the  grouping	 character  if
       defined	for the current locale.	 The + (plus) character specifies that
       the locale's equivalent of + and - are used to  indicate	 positive  and
       negative	 values.   You	cannot specify both the + (plus) character and
       the ( (left-parenthesis) character. If you specify neither,  the	 style
       specified  in the locale for + is used.	The ( (left-parenthesis) char‐
       acter specifies that the	 locale's  equivalent  of  enclosing  negative
       amounts	within	parentheses  is used to indicate positive and negative
       values. See also the description of the + character.  The !   (exclama‐
       tion  mark)  character  suppresses  the currency symbol from the output
       conversion.  The - (hyphen) character specifies that the field is  left
       justified  within  the minimum field width rather than right justified.
       This flag is ignored unless a minimum field  width  is  specified.   An
       optional decimal digit string w that specifies a minimum field width in
       which the result of  the	 conversion  is	 right	justified.  If	the  -
       (hyphen)	 flag  is specified, the result is left justified. The default
       value for w is 0 (zero).	 An optional left precision consisting of a  #
       (number sign), followed by a decimal digit string n.  The decimal digit
       string specifies the maximum number of digits to be  formatted  to  the
       left of the radix character. This option causes an amount to be format‐
       ted as if it has the number of digits specified by the n digit  string.
       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. The #n option can be specified to
       keep the formatted output from multiple calls to the strfmon() function
       aligned in the same columns. The option can also be used in conjunction
       with the =f flag to fill unused positions with a special character (for
       example, $***123.45).

	      If  grouping  is defined for the current locale and has not been
	      suppressed with the ^ (circumflex) flag, grouping separators are
	      inserted	before	the fill characters (if any) are added. There‐
	      fore, grouping characters are not applied to  instances  of  the
	      fill character, even when the fill character is a digit. For the
	      following example in which the fill character  is	 zero,	assume
	      that  the locale specifies that the thousands grouping character
	      is a comma (,), that the grouping character  should  be  delimit
	      each  group of three characters to the left of the radix charac‐
	      ter, and that the radix character is the period (.):

	      strcpy(format,"%=0#10i"); monetary_value = 1.23; retval =	 strf‐
	      mon(str,STR_SIZE,format,	 monetary_value);  printf("(%s,%f)  =>
	      %s\en",format,monetary_value, str);

	      This    example	 prints	   0000000000001.23    rather	  than
	      0,000,000,001.23.	  An  optional right precision consisting of a
	      (period) followed by a decimal digit string p that specifies the
	      number  of digits after the radix character. If the value of the
	      p digit string is 0 (zero), no radix character  is  used.	 If  a
	      right  precision	is  not	 specified, a default specified by the
	      current locale is used. The amount being formatted is rounded to
	      the specified number of digits prior to formatting.  A character
	      that indicates the type of conversion to be applied: No  parame‐
	      ter  is  converted; the conversion specification %% (double per‐
	      cent sign) produces a single % in the output string.  The double
	      parameter	 is formatted according to the current locale's inter‐
	      national	currency  format;  for	example,  in  a	 U.S.  locale:
	      USD 1,234.56.   The  double  parameter is formatted according to
	      the current locale's national currency format; for example, in a
	      U.S. locale: $1,234.56.

       The  following  table  lists  the  default values used by the strfmon()
       function when there are no values defined in the locale for these  mem‐
       bers  of	 the lconv structure. These are the defaults for the POSIX (C)
       locale. For all other lconv members, such as  mon_thousands_sep,	 there
       are no defaults.

       ───────────────────────────────────────────────────────────────────────
       lconv Structure	   Explanation			Default Value
       ───────────────────────────────────────────────────────────────────────
       mon_decimal_point   Radix character		. (period)
       negative_sign	   Character to indicate neg‐	- (hyphen)
			   ative values
       int_frac_digits	   Default  right   precision	2
			   for %i
       frac_digits	   Default   right  precision	2
			   for %n
       left_parenthesis	   Characters used for ( flag	( (left parenthesis)
       right_parenthesis   Characters used for ) flag	) (right parenthesis)
       ───────────────────────────────────────────────────────────────────────

EXAMPLES
       The following table lists conversion specifications and the output.

       ─────────────────────────────────────────────────────────────────────────
       Conv. Spec.   Output  in	  a   US   Output    in	  C   Explanation
		     Locale		   Locale
       ─────────────────────────────────────────────────────────────────────────
       %n	       $100.35		     100.35	      Default  national
							      format
		     $1,225.15-		   -1225.15
       %i	       USD 100.35	     100.35	      Default  interna‐
							      tional format
		     USD 1,225.15-	   -1225.15
       %(#6.3n	      $ 9,876.543	      9876.543	      Explicit left and
							      right   precision
		     ($ 25,832.000)	   ( 25832.000)	      with  parentheses
							      for negative val‐
							      ues
       %=*#7n	      $****4,379.25	    ***4379.25	      Fill character

		     -$****4,379.25	   -***4379.25
       %=0#7n	     $0004,379.25	    0004379.25	      Zero fill

		     $0004,379.25-	   -0004379.25
       %!.0n	     3,225		    3225	      Suppress currency
							      symbol  and round
		     3,225-		   -3225	      to integer
       ─────────────────────────────────────────────────────────────────────────

RETURN VALUES
       If successful, and if the number of resulting bytes (including the ter‐
       minating	 null  byte) is not more than the number of bytes specified by
       the maxsize parameter, the strfmon() function  returns  the  number  of
       bytes  placed  into the array pointed to by the s parameter. The termi‐
       nating null byte is not included in the return count.   Otherwise,  the
       function returns -1, and the contents of the s array are indeterminate.

ERRORS
       If  one	of the following conditions occur, the strfmon() function sets
       errno to the corresponding value: Conversion stopped  due  to  lack  of
       space in the buffer.

SEE ALSO
       Functions: localeconv(3), nl_langinfo(3), scanf(3), setlocale(3), strf‐
       time(3), wscanf(3)

       Files: locale(4)

       Others: i18n_intro(5), l10n_intro(5), standards(5)

       Writing Software for the International Market

								    strfmon(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net