Share via


format-number Function

Converts numbers into strings. The conversion is the result of formatting the number specified in the first argument (number), using the format specified in the second argument (string), and applying the rules defined in the decimal format named in the third optional argument (string). If the third argument, the decimal format name, is omitted, the default decimal format is used. This function and the <xsl:decimal-format> element are designed to be used together.

string format-number(number, string, string?)

Remarks

The first argument specifies the input value. For example, the number 5351.

The second argument specifies the format pattern. For example, the string '###.###,00'.

The third argument is an optional decimal format name. This enables any character to be used in the format pattern string; the character is assigned a role in the <xsl:decimal-format> element. A common decimal format name is european, used to reverse the role of comma and period from the default.

In the format pattern, the following characters are supported "."; ","; "#","%","0", and the Unicode per-mille character (#x2030). The "#" character is used to describe integers. The "." and "," characters are used to describe the location and type of punctuation. The "0" character is used to place a 0 before and after the "." character when the position would otherwise show no numeral, such as 00.3 or 3.00. When truncating digits to the right of the decimal points, the number is rounded. The number to the left of the decimal point is never truncated.

The input value and format pattern string must both be present or an error will be thrown. If the input value cannot be coerced to a number by using the rules in the number() function, the format-number function returns NaN. If the format pattern string is not a valid pattern string, the function returns the input value, unchanged.

The decimal format name, if present, represents the name of a decimal format as specified in an <xsl:decimal-format> element. The decimal format name must be a qualified name. If you specify a decimal format name in the function, there must be an <xsl:decimal-format> element in the style sheet with the same name.

The <xsl:decimal-format> element can override the default number formatting pattern. The <xsl:decimal-format> element follows the formatting specifier patterns of the java.text.DecimalFormat class. For examples of using the format-number function with <xsl:decimal-format>, see <xsl:decimal-format> Element.

Examples

The following XSLT lines return "24.535,20":

<xsl:decimal-format name="european" decimal-separator=',' grouping-separator='.' />
<xsl:value-of select="format-number(24535.2, '###.###,00', 'european')"/>

The following function call returns "5,351":

format-number(5351,"#,###")

The following function call returns "5351.00":

format-number(5351, "#.00")

The following function call returns "53.5100":

format-number(53.51, "#.0000")

The following function call returns "0053.5100":

format-number(53.51, "0000.0000")

The following function call returns "0053.51":

format-number(53.51, "0000.####")

The following function call returns "53.6":

format-number(53.56, "0.0")

For a complete example of applying this function to XML data using an XSLT style sheet, see Example of <xsl:decimal-format>.

See Also

Reference

XML Data Types Reference
<xsl:decimal-format> Element