334 lines
12 KiB
HTML
334 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>strfmon</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="strfmon"></a> <a name="tag_03_728"></a><!-- strfmon -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_728_01"></a>NAME</h4>
|
|
|
|
<blockquote>strfmon - convert monetary value to a string</blockquote>
|
|
|
|
<h4><a name="tag_03_728_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/monetary.h.html">monetary.h</a>><br>
|
|
<br>
|
|
ssize_t strfmon(char *restrict</tt> <i>s</i><tt>, size_t</tt> <i>maxsize</i><tt>,<br>
|
|
const char *restrict</tt> <i>format</i><tt>, ...); <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_728_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>strfmon</i>() function shall place characters into the array pointed to by <i>s</i> as controlled by the string pointed
|
|
to by <i>format</i>. No more than <i>maxsize</i> bytes are placed into the array.</p>
|
|
|
|
<p>The format is a character string, beginning and ending in its initial state, if any, that contains two types of objects:
|
|
<i>plain characters</i>, which are simply copied to the output stream, and <i>conversion specifications</i>, each of which shall
|
|
result in the fetching of zero or more arguments which 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.</p>
|
|
|
|
<p>The application shall ensure that a conversion specification consists of the following sequence:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>A <tt>'%'</tt> character</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Optional flags</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Optional field width</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Optional left precision</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Optional right precision</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A required conversion specifier character that determines the conversion to be performed</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h5><a name="tag_03_728_03_01"></a>Flags</h5>
|
|
|
|
<p>One or more of the following optional flags can be specified to control the conversion:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>=</tt><i>f</i></dt>
|
|
|
|
<dd>An <tt>'='</tt> followed by a single character <i>f</i> which is used as the numeric fill character. In order to work with
|
|
precision or width counts, the fill character shall be a single byte character; if not, the behavior is undefined. The default
|
|
numeric fill character is the <space>. This flag does not affect field width filling which always uses the <space>.
|
|
This flag is ignored unless a left precision (see below) is specified.</dd>
|
|
|
|
<dt><tt>^</tt></dt>
|
|
|
|
<dd>Do not format the currency amount with grouping characters. The default is to insert the grouping characters if defined for the
|
|
current locale.</dd>
|
|
|
|
<dt><tt>+</tt> or <tt>(</tt></dt>
|
|
|
|
<dd>Specify the style of representing positive and negative currency amounts. Only one of <tt>'+'</tt> or <tt>'('</tt> may be
|
|
specified. If <tt>'+'</tt> is specified, the locale's equivalent of <tt>'+'</tt> and <tt>'-'</tt> are used (for example, in the
|
|
U.S., the empty string if positive and <tt>'-'</tt> if negative). If <tt>'('</tt> is specified, negative amounts are enclosed
|
|
within parentheses. If neither flag is specified, the <tt>'+'</tt> style is used.</dd>
|
|
|
|
<dt><tt>!</tt></dt>
|
|
|
|
<dd>Suppress the currency symbol from the output conversion.</dd>
|
|
|
|
<dt><tt>-</tt></dt>
|
|
|
|
<dd>Specify the alignment. If this flag is present the result of the conversion is left-justified (padded to the right) rather than
|
|
right-justified. This flag shall be ignored unless a field width (see below) is specified.</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_728_03_02"></a>Field Width</h5>
|
|
|
|
<dl compact>
|
|
<dt><i>w</i></dt>
|
|
|
|
<dd>A decimal digit string <i>w</i> specifying a minimum field width in bytes in which the result of the conversion is
|
|
right-justified (or left-justified if the flag <tt>'-'</tt> is specified). The default is 0.</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_728_03_03"></a>Left Precision</h5>
|
|
|
|
<dl compact>
|
|
<dt><tt>#</tt><i>n</i></dt>
|
|
|
|
<dd>A <tt>'#'</tt> followed by a decimal digit string <i>n</i> specifying a maximum number of digits expected to be formatted to
|
|
the left of the radix character. This option can be used to keep the formatted output from multiple calls to the <i>strfmon</i>()
|
|
function aligned in the same columns. It can also be used to fill unused positions with a special character as in
|
|
<tt>"$***123.45"</tt> . This option causes an amount to be formatted as if it has the number of digits specified by <i>n</i>. If
|
|
more than <i>n</i> digit positions are required, this conversion specification is ignored. Digit positions in excess of those
|
|
actually required are filled with the numeric fill character (see the <tt>=</tt><i>f</i> flag above).
|
|
|
|
<p>If grouping has not been suppressed with the <tt>'^'</tt> flag, and it is defined for the current locale, grouping separators
|
|
are inserted before the fill characters (if any) are added. Grouping separators are not applied to fill characters even if the fill
|
|
character is a digit.</p>
|
|
|
|
<p>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>s to make their positive and negative formats an equal length.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_728_03_04"></a>Right Precision</h5>
|
|
|
|
<dl compact>
|
|
<dt><tt>.</tt><i>p</i></dt>
|
|
|
|
<dd>A period followed by a decimal digit string <i>p</i> specifying the number of digits after the radix character. If the value of
|
|
the right precision <i>p</i> is 0, no radix character appears. If a right precision 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.</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_728_03_05"></a>Conversion Specifier Characters</h5>
|
|
|
|
<p>The conversion specifier characters and their meanings are:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>i</tt></dt>
|
|
|
|
<dd>The <b>double</b> argument is formatted according to the locale's international currency format (for example, in the U.S.: USD
|
|
1,234.56). If the argument is ±Inf or NaN, the result of the conversion is unspecified.</dd>
|
|
|
|
<dt><tt>n</tt></dt>
|
|
|
|
<dd>The <b>double</b> argument is formatted according to the locale's national currency format (for example, in the U.S.:
|
|
$1,234.56). If the argument is ±Inf or NaN, the result of the conversion is unspecified.</dd>
|
|
|
|
<dt><tt>%</tt></dt>
|
|
|
|
<dd>Convert to a <tt>'%'</tt> ; no argument is converted. The entire conversion specification shall be <tt>%%</tt> .</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_728_03_06"></a>Locale Information</h5>
|
|
|
|
<p>The <i>LC_MONETARY</i> category of the program's locale affects the behavior of this function including the monetary radix
|
|
character (which may be different from the numeric radix character affected by the <i>LC_NUMERIC</i> category), the grouping
|
|
separator, the currency symbols, and formats. The international currency symbol should be conformant with the ISO 4217:1995
|
|
standard.</p>
|
|
|
|
<p>If the value of <i>maxsize</i> is greater than {SSIZE_MAX}, the result is implementation-defined.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the total number of resulting bytes including the terminating null byte is not more than <i>maxsize</i>, <i>strfmon</i>()
|
|
shall return the number of bytes placed into the array pointed to by <i>s</i>, not including the terminating null byte. Otherwise,
|
|
-1 shall be returned, the contents of the array are unspecified, and <i>errno</i> shall be set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>strfmon</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[E2BIG]</dt>
|
|
|
|
<dd>Conversion stopped due to lack of space in the buffer.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_728_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>Given a locale for the U.S. and the values 123.45, -123.45, and 3456.781, the following output might be produced. Square
|
|
brackets ( <tt>"[]"</tt> ) are used in this example to delimit the output.</p>
|
|
|
|
<pre>
|
|
<tt>%n [$123.45] </tt> Default formatting
|
|
<tt> [-$123.45]
|
|
[$3,456.78]
|
|
<br>
|
|
%11n [ $123.45] </tt> Right align within an 11-character field
|
|
<tt> [ -$123.45]
|
|
[ $3,456.78]
|
|
<br>
|
|
%#5n [ $ 123.45] </tt> Aligned columns for values up to 99999
|
|
<tt> [-$ 123.45]
|
|
[ $ 3,456.78]
|
|
<br>
|
|
%=*#5n [ $***123.45] </tt> Specify a fill character
|
|
<tt> [-$***123.45]
|
|
[ $*3,456.78]
|
|
<br>
|
|
%=0#5n [ $000123.45] </tt> Fill characters do not use grouping
|
|
<tt> [-$000123.45] </tt> even if the fill character is a digit
|
|
<tt> [ $03,456.78]
|
|
<br>
|
|
%^#5n [ $ 123.45] </tt> Disable the grouping separator
|
|
<tt> [-$ 123.45]
|
|
[ $ 3456.78]
|
|
<br>
|
|
%^#5.0n [ $ 123] </tt> Round off to whole units
|
|
<tt> [-$ 123]
|
|
[ $ 3457]
|
|
<br>
|
|
%^#5.4n [ $ 123.4500] </tt> Increase the precision
|
|
<tt> [-$ 123.4500]
|
|
[ $ 3456.7810]
|
|
<br>
|
|
%(#5n [$ 123.45] </tt> Use an alternative pos/neg style
|
|
<tt> [($ 123.45)]
|
|
[$ 3,456.78]
|
|
<br>
|
|
%!(#5n [ 123.45] </tt> Disable the currency symbol
|
|
<tt> [( 123.45)]
|
|
[ 3,456.78]
|
|
<br>
|
|
%-14#5.4n [ $ 123.4500 ] </tt> Left-justify the output
|
|
<tt> [-$ 123.4500 ]
|
|
[ $ 3,456.7810 ]
|
|
<br>
|
|
%14#5.4n [ $ 123.4500] </tt> Corresponding right-justified output
|
|
<tt> [ -$ 123.4500]
|
|
[ $ 3,456.7810]
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>See also the EXAMPLES section in <a href="../functions/fprintf.html"><i>fprintf</i>()</a>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>Lowercase conversion characters are reserved for future standards use and uppercase for implementation-defined use.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="fprintf.html"><i>fprintf</i>()</a> , <a href="localeconv.html"><i>localeconv</i>()</a> , the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/monetary.h.html"><i><monetary.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from ENHANCED I18N to BASE.</p>
|
|
|
|
<p>The [ENOSYS] error is removed.</p>
|
|
|
|
<p>A sentence is added to the DESCRIPTION warning about values of <i>maxsize</i> that are greater than {SSIZE_MAX}.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_728_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>strfmon</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</p>
|
|
|
|
<p>The EXAMPLES section is reworked, clarifying the output format.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|