XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

format-number

Category:

Type conversion and output formatting

Origin:

XSLT 1.0

Return value:

A xs:string string; the input number formatted according to the default rules or a named xsl:decimal-format declaration.

Call/Arguments:

format-number($inputNumber, $formattingPattern, $formatDefinition?)

$inputNumber:

Obligatory. The first argument determines the number to be formatted. In XPath 2.0 this number must be of xs:double type. (In XPath 1.0 the input argument is converted to a number according to the rules of the number() function.)

$formattingPattern:

Obligatory. The second argument determines the pattern (picture string) which shall be used for the formatting of the number passed on. In essence, the number of digits of decimal numbers as well as the number of leading and trailing zeros is defined.

Per default, the digit 0 is used as a wildcard for leading and trailing zeros to be outputted (zero-digit-sign) and the hash character # is used as a wildcard for any digits at positions where their output can be omitted (digit-sign). If required, also other characters can be determined for these tasks by xsl:decimal-format in the format declaration.

$formatDefinition:

Optional. The third argument consists of the QName of a format definition declared by xsl:decimal-format. In such a definition, the characters to be used in the string output for decimal separators, thousands separator as well as NaN and others are determined. The format definition by xsl:decimal-format has no influence on the form of the second argument to be passed on as formatting rule, but it determines the character symbols to be useable there.

Purpose of use:

A formatting pattern (picture string) consists of an optional prefix, the formatting string and an optional suffix.

The formatting string of the formatting pattern:

The formatting string consists of the wildcards for digits of the pre-decimal places with possible grouping symbols, the decimal separator symbol and further wildcards for decimal places. The characters usable here can be determined in the appropriate attributes of the declaration – otherwise the respective default values apply.

'###,###,000.0###'

Default values are, according to the American number formatting, the comma as grouping character as well as the dot as decimal separator. Therefore, for the formatting of numbers according to the West European convention, a xsl:decimal-format declaration must be used which makes an appropriate transposition:

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

In the format pattern the digit 0 or the character defined in the zero-digit attribute serves as a wildcard for places which shall be filled up with zeros in the output string in case a digit greater than 0 cannot be assigned to them. In this way, leading as well as trailing zeros can be equally enforced.

The # character or the character defined in the digit attribute serves as a wildcard for places which can be omitted in the output string in case a digit greater than 0 cannot be assigned to them.

Under no circumstances, more decimal places are outputted as provided in the formatting string. Excess places are omitted, the last outputted place is rounded accordingly.

Prefix and suffix of the formatting pattern:

For the prefix and the suffix of the formatting string any characters (also space characters are significant!) may be used, but not those agreed for the formatting string. During the formatting, the prefix and the suffix are adopted unchanged into the result string and put in front of or back the formatted number. A normalisation does not take place, i.e. also leading space characters get to the output string.

'My prefix: ##00.0### my suffix'

For the formatting of a negative number, the leading sign agreed in the minus-sign attribute is put in front of the number. Otherwise, the string conversion takes place by means of the formatting pattern.

Alternatively, within the formatting string two subformatting patterns can be defined from whom the second one is used for the formatting of negative numbers. The semicolon is used as separator symbol between the subpatterns, unless another character is agreed in the pattern-separator attribute of a linked format declaration:

'##.00;minus ##.00'

If a subpattern is available for negative numbers, the leading sign in the output string is not used (unless it is explicitly provided in the subpattern).

Subpatterns can have prefixes and suffixes, too. The (involuntary and purely optically meant) separation of the subgroups by space characters is buggy, since in this case space characters are also significant:

-5 with '##.00;minus ##.00' results in: minus 5.00

In this example, a space character has slipped in the formatting string:

-5 with '##.00; minus ##.00' results in: _minus 5.00

The unintentionally outputted space character is symbolised by the underscore. Here too, a normalisation does not take place.

Example 1 – enforcing two pre-decimal places and one decimal place:

<xsl:value-of select="format-number($number,'##00.0###')"/>
Input value Output value
-5 -05.0
-3.895 -03.895
1.63 01.63
467.531 467.531

Table: formatting with format string '##00.0###'

Example 2 – restriction to two decimal places (with rounding)

<xsl:value-of select="format-number($number,'##.##')"/>
Input value Output value
-5 -5
-3.895 -3.9
1.63 1.63
467.531 467.53

Table: formatting with format string '##.##'

Example 3 – enforcing two decimal places after the comma:

<xsl:value-of select="format-number($number,'##.00')"/>
Input value Output value
-5 -5.00
-3.895 -3.90
1.63 1.63
467.531 467.53

Table: formatting with format string '##.00'

Example 4 – using subpatterns for negative numbers:

<xsl:value-of select="format-number($number,'##.00;minus ##.00')"/>
Input value Output value
-5 minus 5.00
-3.895 minus 3.90
1.63 1.63
467.531 467.53

Table: formatting with format string '##.00;minus ##.00'

Remark: Due to the subpattern, there is no output of the minus sign for negative input values.

Example 5 – using a suffix (here in the form of a unit of measurement):

<xsl:value-of select="format-number($number,'##.00 cm')"/>
Input value Output value
-5 -5.00 cm
-3.895 -3.90 cm
1.63 1.63 cm
467.531 467.53 cm

Table: formatting with format string '##.00 cm'

Example 6 – using prefix, suffix and subpatterns:

<xsl:value-of select="format-number($number,'Profit: ##.00 Euro;Loss: ##.00 Euro')"/>
Input value Output value
-5 Loss: 5.00 Euro
-3.895 Loss: 3.90 Euro
1.63 Profit: 1.63 Euro
467.531 Profit: 467.53 Euro

Table: formatting with format string 'Profit: ##.00 Euro;Loss: ##.00 Euro'

Function definition:

XSLT 1.0:

format-number(inputNumber,

formattingPattern,

formatDefinition?) => string

XSLT 2.0:

format-number(inputNumber as xs:double,

formattingPattern as xs:string,

formatDefinition? as xs:string) as string

Possible compatibility problems XSLT 2.0 to XSLT 1.0:

Minor. When indicating a xsl:decimal-format format declaration under XSLT 2.0, the function requires its actual presence; furthermore, the identifier must (lexically) be a valid QName. An error leads to the ignoring of the appropriate argument. The xsl:decimal-format declaration was extended under XSLT 2.0 with regard to language-specific presentation and other details. This applies, for example, also to the position of a leading sign for a prefix string to be outputted simultaneously (leading sign in XSLT 1.0 after the prefix, in XSLT 2.0 before it.)

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany