Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.
The function formats
$value as a string using the picture string specified by the
$picture argument and the decimal-format named by the
$decimal-format-name argument, or the unnamed decimal-format, if there
$decimal-format-name argument. The syntax of the picture string is
described in .
$value argument may be of any numeric data type
xs:decimal, or their
xs:integer). Note that if an
supplied, it is not automatically promoted to an
xs:double, as such
promotion can involve a loss of precision.
If the supplied value of the
$value argument is an empty sequence, the
function behaves as if the supplied value were the
The value of
$decimal-format-name, if present and non-empty,
must be a string which after removal of leading and trailing
whitespace is in the form of an
EQName as defined in the XPath 3.0
grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
URIQualifiedName using the syntax
the URI can be zero-length to indicate a name in no namespace.
The decimal format that is used is the decimal format in the static context whose name
$decimal-format-name if supplied, or the unnamed decimal format in
the static context otherwise.
The evaluation of the
fn:format-number function takes place in two
phases, an analysis phase described in and a
formatting phase described in .
The analysis phase takes as its inputs the picture string and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ".", the grouping separator is ",", the minus-sign is "-", and the percent-sign is "%".
format-number(12345.6, '#,###.00') returns
format-number(12345678.9, '9,999.99') returns
format-number(123.9, '9999') returns
format-number(0.14, '01%') returns
format-number(-6, '000') returns
The following example assumes the existence of a decimal format named 'ch' in which
the grouping separator is
ʹ and the decimal separator is
The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':
format-number(1234.5678, '00.000E0', 'fortran') returns
format-number(0.234, '0.0E0', 'fortran') returns
format-number(0.234, '#.00E0', 'fortran') returns
format-number(0.234, '.00E0', 'fortran') returns
A dynamic error is raised if the name specified as
$decimal-format-name argument is neither a valid lexical QName nor a
URIQualifiedName, or if it uses a prefix that is not found in the
statically known namespaces, or if the static context does not contain a declaration of
a decimal-format with a matching expanded QName. If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor may optionally signal this as a static error.
A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.