<html>
<head>
<title>format-number() Function</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div id="Description">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">format-number() Function</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description">
Takes a number and formats it as a string. </td></tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Inputs</td>
</tr>
<tr>
<td colspan="2" class="description">
<p>The number to be formatted and the format pattern string are required. The third argument is the optional name of a decimal format; if the third argument is not supplied, the default decimal format is used. </p>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Output</td>
</tr>
<tr>
<td colspan="2" class="description">
<p>The number, formatted according to the rules supplied by the other arguments. The special characters used in the second argument are:</p>
<dl>
<dt>
<span class="LITERAL">
#
</span>
</dt>
<dd>
Represents a digit. Trailing or leading zeroes are not displayed. Formatting the number
<span class="LITERAL">
4.0
</span>
with the string
"
#.##
"
returns the string
"
4
"
.
<P></p>
<dt>
<span class="LITERAL">
0
</span>
</dt>
<dd>
Represents a digit. Unlike the
<span class="LITERAL">
#
</span>
character, the
<span class="LITERAL">
0
</span>
always displays a zero. Formatting the number
<span class="LITERAL">
4.1
</span>
with the string
"
#.00
"
returns the string
"
4.10
"
.
<P></p>
<dt>
<span class="LITERAL">
.
</span>
</dt>
<dd>
Represents the decimal point.
<P></p>
<dt>
<span class="LITERAL">
-
</span>
</dt>
<dd>
Represents the minus sign.
<P></p>
<dt>
<span class="LITERAL">
,
</span>
</dt>
<dd>
Is the grouping separator.
<P></p>
<dt>
<span class="LITERAL">
;
</span>
</dt>
<dd>
Separates the positive-number pattern from the negative-number pattern.
<P></p>
<dt>
<span class="LITERAL">
%
</span>
</dt>
<dd>
Indicates that a number should be displayed as a percentage. The value will be multiplied by 100, then displayed as a percentage. Formatting the number
<span class="LITERAL">
.76
</span>
with the string
"
##%
"
returns the string
"
76%
"
.
<P></p>
<dt>
<span class="LITERAL">
\u2030
</span>
</dt>
<dd>
Is the Unicode character for the per-thousand (per-mille) sign. The value will be multiplied by 1000, then displayed as a per mille. Formatting the number
<span class="LITERAL">
.768
</span>
with the string
"
###\u2030
"
returns the string
"
768
<graphic depth="23" width="18" fileref="figs/U2030.gif" align="absmiddle"/>
"
.
<P></p>
</dl>
<p>The third argument, if given, must be the name of an <span class="LITERAL">&lt;xsl:decimal-format&gt;</span> element. The <span class="LITERAL">&lt;xsl:decimal-format&gt;</span> element lets you define the character that should be used for the decimal point and the grouping separator, the string used to represent infinity, and other formatting options. See <xref linkend="decimal-format-element">&lt;xsl:decimal-format&gt;</xref> for more information.</p>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Defined in</td>
</tr>
<tr>
<td colspan="2" class="description">
<p>XSLT section 12.3, Number Formatting.</p>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="TITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">
<p>The following stylesheet uses the <span class="LITERAL">format-number()</span> function in various ways:</p>
<span class="PROGRAMLISTING"><pre>
&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt;
&lt;xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:months="Lookup table for month names"&gt;

  &lt;xsl:output method="text"/&gt;

  &lt;months:name sequence="01"&gt;January&lt;/months:name&gt;
  &lt;months:name sequence="02"&gt;February&lt;/months:name&gt;
  &lt;months:name sequence="03"&gt;March&lt;/months:name&gt;
  &lt;months:name sequence="04"&gt;April&lt;/months:name&gt;

  &lt;xsl:variable name="newline"&gt;
&lt;xsl:text&gt;
&lt;/xsl:text&gt;
  &lt;/xsl:variable&gt;

<!--<?troff .Nd 10?>-->
  &lt;xsl:decimal-format name="f1"
    decimal-separator=":"
    grouping-separator="/"/&gt;

  &lt;xsl:decimal-format name="f2"
    infinity="Really, really big"
    NaN="[not a number]"/&gt;

  &lt;xsl:template match="/"&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;Tests of the format-number() function:&lt;/xsl:text&gt;

    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(528.3, '#.#;-#.#')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(528.3, '#.#;-#.#')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(528.3, '0,000.00;-0,000.00')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(528.3, '0,000.00;-0,000.00')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(-23528.3, '$#,###.00;($#,###.00)')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(-23528.3, '$#,###.00;($#,###.00)')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(1528.3, '#/###:00', 'f1')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(1528.3, '#/###:00;-#/###:00', 'f1')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(1 div 0, '###,###.00', 'f2')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(1 div 0, '###,###.00', 'f2')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:text&gt;   format-number(blue div orange, '#.##', 'f2')=&lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(blue div orange, '#.##', 'f2')"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:value-of select="$newline"/&gt;
    &lt;xsl:for-each select="report/month"&gt;
      &lt;xsl:text&gt;   &lt;/xsl:text&gt;
      &lt;xsl:value-of 
        select="document('')/*/months:name[@sequence=current()/@sequence]"/&gt;
      &lt;xsl:text&gt; - &lt;/xsl:text&gt;
      &lt;xsl:value-of select="format-number(miles-flown, '##,###')"/&gt;
      &lt;xsl:text&gt; miles flown, &lt;/xsl:text&gt;
      &lt;xsl:value-of select="format-number(miles-earned, '##,###')"/&gt;
      &lt;xsl:text&gt; miles earned.&lt;/xsl:text&gt;
      &lt;xsl:value-of select="$newline"/&gt;
      &lt;xsl:text&gt;     (&lt;/xsl:text&gt;
      &lt;xsl:value-of 
        select="format-number(miles-flown div sum(//miles-flown), '##%')"/&gt;
      &lt;xsl:text&gt; of all miles flown, &lt;/xsl:text&gt;
      &lt;xsl:value-of 
        select="format-number(miles-earned div sum(//miles-earned), '##%')"/&gt;
      &lt;xsl:text&gt; of all miles earned.)&lt;/xsl:text&gt;
      &lt;xsl:value-of select="$newline"/&gt;
      &lt;xsl:value-of select="$newline"/&gt;
    &lt;/xsl:for-each&gt; 
    &lt;xsl:text&gt;   Total miles flown: &lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(sum(//miles-flown), '##,###')"/&gt;
    &lt;xsl:text&gt;, total miles earned: &lt;/xsl:text&gt;
    &lt;xsl:value-of select="format-number(sum(//miles-earned), '##,###')"/&gt;
  &lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;</pre></span>
<p>We'll use this XML document with our stylesheet:</p>
<span class="PROGRAMLISTING"><pre>
&lt;?xml version="1.0"?&gt;
&lt;report&gt;
  &lt;title&gt;Miles Flown in 2001&lt;/title&gt;
  &lt;month sequence="01"&gt;
    &lt;miles-flown&gt;12379&lt;/miles-flown&gt;
    &lt;miles-earned&gt;35215&lt;/miles-earned&gt;
  &lt;/month&gt;
  &lt;month sequence="02"&gt;
    &lt;miles-flown&gt;32857&lt;/miles-flown&gt;
    &lt;miles-earned&gt;92731&lt;/miles-earned&gt;
  &lt;/month&gt;
  &lt;month sequence="03"&gt;
    &lt;miles-flown&gt;19920&lt;/miles-flown&gt;
    &lt;miles-earned&gt;76725&lt;/miles-earned&gt;
  &lt;/month&gt;
  &lt;month sequence="04"&gt;
    &lt;miles-flown&gt;18903&lt;/miles-flown&gt;
    &lt;miles-earned&gt;31781&lt;/miles-earned&gt;
  &lt;/month&gt;
&lt;/report&gt;</pre></span>
<p>When we run this stylesheet, here are the results:</p>
<span class="PROGRAMLISTING"><pre>

Tests of the format-number() function:

   format-number(528.3, '#.#;-#.#')=528.3
   format-number(528.3, '0,000.00;-0,000.00')=0,528.30
   format-number(-23528.3, '$#,###.00;($#,###.00)')=($23,528.30)
   format-number(1528.3, '#/###:00', 'f1')=1/528:30
   format-number(1 div 0, '###,###.00', 'f2')=Really, really big
   format-number(blue div orange, '#.##', 'f2')=[not a number]

   January - 12,379 miles flown, 35,215 miles earned.
     (15% of all miles flown, 15% of all miles earned.)

   February - 32,857 miles flown, 92,731 miles earned.
     (39% of all miles flown, 39% of all miles earned.)

   March - 19,920 miles flown, 76,725 miles earned.
     (24% of all miles flown, 32% of all miles earned.)

   April - 18,903 miles flown, 31,781 miles earned.
     (22% of all miles flown, 13% of all miles earned.)

   Total miles flown: 84,059, total miles earned: 236,452</pre></span>
<p>The first few examples illustrate some of the more complicated formatting options available, along with references to the <span class="LITERAL">&lt;xsl:decimal-format&gt;</span> elements in the stylesheet. The last section is a more typical use of the <span class="LITERAL">format-number</span> function: formatting values selected or calculated from an XML document. </p>
</td>
</tr>
</table>
</div>
</body>
</html>