xsl:decimal-format

The <xsl:decimal-format> element is used to define the characters and symbols used when converting numbers into strings using the format-number() function.

Note that <xsl:decimal-format> applies only to the format-number() function. It has no effect on the way <xsl:number> formats numbers for display, nor on the default number-to-string conversion used by the string() function, nor on the format used when <xsl:value-of> is used to output a number as a string.

Import precedence now applies to decimal formats in a similar way as to other declarations.

Changes in 2.0

The specification of the format-number() function, which uses the <xsl:decimal-format> declaration, is substantially rewritten in XSLT 2.0, though users should notice few changes except in a few corner cases. The <xsl:decimal-format> declaration itself is unchanged.

Format

 <xsl:decimal-format   name? = qname   decimal-separator? = char   grouping-separator? = char   infinity? = string   minus-sign? = char   NaN? = string   percent? = char   per-mille? = char   zero-digit? = char   digit? = char   pattern-separator? = char />

Position

<xsl:decimal-format> is a top-level declaration. It may appear any number of times in a stylesheet, but only as an immediate child of the <xsl:stylesheet> element.

Attributes

Name	Value	Meaning
name optional	QName	The name of this decimal format. If omitted, the attributes apply to the default decimal format
decimal-separator optional	character	Character to be used to separate the integer and the fraction part of a number. Default is «. » (x2E)
grouping-separator optional	character	Character used to separate groups of digits. Default is «, » (x2C)
infinity optional	string	String used to represent the numeric value infinity. Default value is «Infinity »
minus-sign optional	character	Character used as the default minus sign. Default is «- » (x2D)
NaN optional	string	String used to represent the numeric value NaN (not a number). Default value is «NaN »
percent optional	character	Character used to represent a percentage sign. Default value is «% » (x25)
per-mille optional	character	Character used to represent a per-mille (per-thousand) sign. Default value is «% » (x2030)
zero-digit optional	character	Character used in a format pattern to indicate a place where a leading or trailing zero digit is required, even if it is not significant. Default value is «0 » (x30). This character must be one that is classified in the Unicode database as a digit character, with the numeric value zero
digit optional	character	Character used in a format pattern to indicate a place where a digit will appear, provided it is a significant digit. Default value is «# » (x23)
pattern-separator optional	character	Character used in a format pattern to separate the subpattern for positive numbers from the subpattern for negative numbers. Default value is «; » (x3B)

Content

None; the element is always empty.

Effect

If a name attribute is supplied, the <xsl:decimal-format> element defines a named decimal format; otherwise it defines attributes of the default decimal format. A named decimal format is used by the format-number() function when it is called with three arguments (the third argument is the name of a decimal format); the default decimal format is used when the format-number() function is called without a third argument.

It is an possible to have more than one <xsl:decimal-format> element for the default decimal format, or more than one for a decimal format with a given name. The effective value of a given attribute (such as zero-digit ) is taken from the declaration with the highest import precedence that specifies a value for the required attribute. It is an error if this selects more than one declaration, unless the values specified are the same.

The <xsl:decimal-format> element does not directly define the display format of a number. Rather it defines the characters and strings used to represent different logical symbols. Some of these logical symbols occur in the picture string used as an argument to the format-number() function, some of them occur in the final output number itself, and some are used in both. The actual display format of a number depends both on the picture string and on the choice of decimal format symbols.

For example, if there is a <xsl:decimal-format> element as follows :

  <xsl:decimal-format name="european"   decimal-separators","   grouping-separator="." >

then the function call:

  format-number(1234.5, '#.##0,00', 'european')

will produce the output:

  1.234,50

The use of the «. » and «, » characters in both the picture string and the output display is determined by the named <xsl:decimal-format> element, but the number of digits displayed, and the use of leading and trailing zeros, is determined solely by the picture string.

The structure of a picture string is defined in the description of the format-number() function in Chapter 7, page 558. The syntax of the picture string uses a number of special symbols: the actual characters used for these symbols are defined in the relevant <xsl:decimal-format> element. These symbols are:

 decimal-separator grouping-separator percent per-mille zero-digit digit pattern-separator

The <xsl:decimal-format> element also defines characters and strings that are used, when required, in the actual output value. Some of these are the same as characters used in the picture string, others are different. These characters and strings are:

 decimal-separator grouping-separator infinity minus-sign NaN percent per-mille zero-digit

For example, if the <xsl:decimal-format> element defines the infinity string as «*** » , then the output of «format-number(1 div 0, $format) » will be «*** » , regardless of the picture string.

Usage

The <xsl:decimal-format> element is used in conjunction with the format-number() function to output numeric information. It is designed primarily to provide localization of the format for display to human readers, but it can also be useful when you need to produce an output data file using, for example, a fixed number of leading zeroes. It is typically used for numbers in the source data or computed from the source data, whereas the <xsl:number> element, which has its own formatting capabilities, is generally used for sequence numbers.

Each <xsl:decimal-format> element defines a style of localized numbering, catering for the variations that occur in different countries and languages, and for other local preferences such as the convention in the accountancy profession whereby parentheses are used to indicate negative numbers.

Examples

The tables in the following examples illustrate some of the effects achievable using the <xsl:decimal-format> element in conjunction with different picture string.

Example 1

This decimal format is used in many Western European countries; it uses a comma as a decimal point and a period (full stop) as a thousand separator, the reverse of the custom in Britain and North America.

The left-hand column shows the number as it would be written in XSLT. The middle column shows the picture string supplied as the second argument to the format-number() function. The right-hand column shows the string value returned by the format-number() function.

The patterns used in this example use the following symbols:

«. » , which I have defined as my thousands separator
«, » , which I have defined as my decimal point
«# » , which is a position where a digit can occur, but where the digit is omitted if it is an insignificant zero
«0 » , which is a position where a digit will always occur, even if it is an insignificant zero
«% » , which indicates that the number should be expressed as a percentage
«; » , which separates the subpicture used for positive numbers from the subpicture used for negative numbers

  <xsl:decimal-format decimal-separator="," grouping-separator="."/>

Number	Picture String	Result
1234.5	#.##0,00	1.234,50
123.456	#.##0,00	123,46
1000000	#.##0,00	1.000.000,00
-59	#.##0,00	-59,00
1 div 0	#.##0,00	Infinity
1234	###0,0###	1234,0
1234.5	###0,0###	1234,5
.00035	###0,0###	0,0004
0.25	#00%	25%
0.736	#00%	74%
1	#00%	100%
-42	#00%	-4200%
-3.12	#,00;(#,00)	(3,12)
-3.12	#,00;#,00CR	3,12CR

Example 2

This example shows how digits other than the Western digits 0-9 can be used. I will use the Indic Arabic digits (that is, the Arabic digits used in many Arabic countries, as distinct from the so-called Arabic digits used in the West):

  <xsl:decimal-format zero-digit="&#x0660;"/>

Number	Format pattern	Result
12345	(x0660)	& pound ;

The digits will be output in the output XML or HTML file in the usual order (most significant digit first). Displaying the number correctly when it appears as part of text that runs from right to left is the job of the browser or other display software, and you shouldn't worry about it at the XSLT level.

Example 3

This example shows how the exceptional numeric values NaN and Infinity can be shown, for example in a statistical table.

  <xsl:decimal-format NaN="Not Applicable" infinity="Out of Range"/>

Number	Format pattern	Result
number('a')	any	Not Applicable
le0 div 0	any	Out of Range
-le0 div0	any	-Out of Range