format-number

The format-number() function is used to convert numbers into strings for display to a human user . It is also useful when converting to legacy formats that require a number to occupy a fixed number of character positions . The format of the result is controlled using the <xsl: decimal-format> declaration.

For example, the expression «format-number (12.5, '$#0.00') » returns the string «$12.50 » .

Changes in 2.0

In XSLT 1.0, the effect of the function was defined by reference to the Java JDK 1.1 specifications. This created problems because the JDK 1.1 description left many details underspecified, and later versions of the JDK not only clarified the specification, but also added new features. It was therefore decided in XSLT 2.0 to provide a freestanding definition of this function. This is largely compatible with the old JDK 1.1 specification, but the rules are now much more precise, and in corner cases they will not necessarily give the same results as implementations based on the JDK, let alone nonjava implementations . For example, the JDK 1.1 specification did not say how rounding was done. The actual JDK 1.1 implementation used the rule of rounding a final 5 to the nearest even number, and this is the rule that XSLT 2.0 has adopted, but XSLT 1.0 processors might well do rounding differently.

Signature

Argument	Data type	Meaning
value	xs:double?	The number to be formatted
picture	xs:string	A picture string identifying the way in which the number is to be formatted
format (optional)	xs:string	A string in the form of a lexical QName, that identifies an <xsl:decimal-format> declaration in the stylesheet, giving further information about the required formatting options
Result	xs:string?	The formatted number

Effect

The function returns a string value; this is the result of formatting the given value using the format picture supplied in picture , while applying the rules defined in the decimal format named in format if present, or using the default decimal format otherwise .

Although the function signature says that value must be an xs:double , the function calling rules ensure that a value of type xs:float , xs:decimal or xs:integer is equally acceptable.

The decimal-format Name

The format argument, if it is present, must take the form of a lexical QName ; that is, an XML name optionally prefixed with a namespace prefix that corresponds to a namespace declaration that is in scope at the point in the stylesheet where the format-number() function is called. There must be an <xsl:decimal-format> element in the stylesheet with the same expanded name, using the namespace URIs rather than prefixes in the comparison.

If the format argument is omitted, the default decimal format is used. A default decimal format can be established for a stylesheet by including an <xsl:decimal-format> element with no name. If there is no unnamed <xsl:decimal-format> element in the stylesheet, the system uses a built-in default format, which is the same as specifying an <xsl:decimal-format> with no attributes.

The Picture String

The structure of the picture string is as follows. Here, and in the text that follows , I will use the default characters for each role: for example «; » as the pattern separator, «. » as the decimal point, «0 » as the zero digit, «# » as the optional digit placemarker, and so on. Remember, though, that you can change the characters that are used in each of these roles using the <xsl:decimal-format> declaration.

picture	subpicture ( «; »subpicture)?
subpicture	prefix? integer ( «. » fraction)? suffix?
prefix	any characters except special characters
suffix	any characters except special characters
integer	«# »* «0 »* (but also allowing «, » to appear)
fraction	«0 »* «# »* (but also allowing «, » to appear)

The first subpicture is used for formatting positive numbers. The second (optional) subpicture is used for negative numbers. If only one subpicture is specified, then the subpicture used for negative numbers is the same as the positive subpicture, but with a minus sign added before the prefix. The actual character used for the minus sign depends on the <xsl:decimal-format> declaration.

The prefix and suffix are just literal characters that are output at the start and end of the number. The only real reason to use them, other than simple convenience, is when they are different for positive and negative numbers. For example, you can use this mechanism to implement the accounting convention of displaying negative numbers in parentheses.

If the prefix or suffix includes a «% » sign, the percent sign will be displayed in the place where it appears in the prefix or suffix, and the number will be multiplied by 100. Similarly, you can also use a per-mille sign «% » in which case the number will be multipled by 1,000.

If the number is one of the special values positive or negative infinity or NaN, then it is displayed using the representation defined in the <xsl:decimal-format> declaration, together with the prefix and suffix. The positive subpicture is used for displaying positive zero and positive infinity, while the negative subpicture is used for negative zero and negative infinity.

The special characters used are as follows.

Special Character	Meaning
zero-digit (default «0 » )	A digit will always appear at this point in the result string
digit (default «# » )	A digit will appear at this point in the result string unless it is a redundant leading or trailing zero
decimal-point (default «. » )	Separates the integer and the fraction part of the number
grouping-separator (default «, » )	Separates groups of digits
pattern-separator (default «; » )	Separates the positive and negative subpictures
minus-sign (default «- » )	Minus sign
percent-sign (default «% » )	Multiplies the number by 100 and shows it as a percentage
per-mille (default «% » )	Multiplies by 1,000 and shows it as per-mille

The original JDK 1.1 implementation had the feature (I use the term politely) that if there was an explicit negative subpicture, it served to specify the negative prefix and suffix only; the number of digits, grouping separators, and other characteristics were all taken from the positive subpicture, and any specification to the contrary in the negative subpicture was ignored. This curiosity was not actually documented in the JDK 1.1 specification, though it was retained (and documented) in JDK 1.2. Since XSLT 1.0 referred explicitly to the JDK 1.1 specification (but not to the JDK 1.1 implementation), it's likely that some XSLT 1.0 processors share this behavior and others do not. XSLT 2.0 does away with it: all aspects of formatting for a negative number depend on the negative subpicture alone.

In the fractional part of the number, a «0 » means you will get a digit in that position whatever be its value, while a «# » means you will get a digit only if it is non-zero . You will never get more digits displayed than there are «0 » and «# » signs. For example, «.00## » displays a minimum of two and a maximum of four digits after the decimal point. If there are more significant digits in the number than you have asked to be displayed, then the number is rounded. It is rounded to the nearest value that can be displayed, and if it is midway between two such values, it is rounded to the one whose last digit is even. For example, with a picture of «0.00 » , the value 0.125 is shown as «0.12 » , while 0.875 is shown as «0.88 » . This is different from the rounding rule that many of us were taught at school, which always rounds 0.5 upwards, but it is preferred by many statisticians and accountants because it means that numbers are equally likely to be rounded up or down, which avoids introducing bias. If you prefer a different rounding rule, you can always round the number yourself before formatting it.

In the integer part of the picture, that is, on the left of the decimal point if there is one, the rules are slightly different. If there is at least one «# » sign in this part, then the number will be displayed with as many digits as necessary to accommodate its value (but with at least as many digits as there are «0 » digits in the picture). If there is no «# » sign in the integer part of the picture, then an error occurs if the number is too big to be displayed: for example, displaying the number 218.5 with a picture of «00.0 » is an error. The system is allowed to treat this as a fatal error, but it is also allowed to recover, which it can do by simply ignoring the picture and outputting the value using as many digit positions as it needs.

The format-number() function doesn't provide any direct way of space-padding the number so that numbers can be vertically aligned in a column. The simplest way to achieve this effect, though it is rather clumsy, is to format the number, use the string-length () function to determine the length of the result, and then add the requisite number of spaces to the front.

The grouping separator ( «, » by default) is commonly used for thousands, but in some countries for ten thousands. You can specify grouping separators either at regular intervals or at irregular intervals, and they can appear in either the integer part or the fractional part of the number. For example, if you write «#, # # 0.0 0 » then you will get a grouping separator every three digits to the left of the decimal point, while if you specify «#,##,###,###0.00 » then you will get separators at the specified positions only. The rule is that if all your explicit grouping separators are regularly spaced , then the system will add implicit grouping separators when it extends the picture on the left, but if the explicit separators are at irregular intervals, then no implicit separators will be added.

If the picture string is invalid, then the implementation is free either to report an error or to display the number in some fallback representation.

Usage

Note that this facility for formatting numbers is completely separate from the facilities available through the <xsl:number> element. There is some overlapping functionality, but the syntax of the pictures is quite unrelated. The format-number() function formats a single number, which need not be an integer. <xsl:number> is primarily designed to format a list of positive integers. For formatting a single positive integer, either facility can be used.

Examples

The following example shows the result of format-number() using the default decimal format. Examples with non-default decimal formats are shown under the <xsl:decimal-format> element in Chapter 5, page 251.

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
.00025	###0.0###	0.0004
.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