Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
fn:format-number( $value as xs:numeric?,$picture as xs:stringxs:stringfn:format-number( $value as xs:numeric?,$picture as xs:string,$decimal-format-name as xs:string?xs:stringThe 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
is no $decimal-format-name argument. The syntax of the picture string is
described in .
The $value argument may be of any numeric data type
(xs:double, xs:float, xs:decimal, or their
subtypes including xs:integer). Note that if an xs:decimal is
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 xs:double value
NaN.
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).
A URIQualifiedName using the syntax Q{uri}local, where
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
matches $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 "%".
The expression format-number(12345.6, '#,###.00') returns "12,345.60".
The expression format-number(12345678.9, '9,999.99') returns "12,345,678.90".
The expression format-number(123.9, '9999') returns "0124".
The expression format-number(0.14, '01%') returns "14%".
The expression format-number(-6, '000') returns "-006".
The following example assumes the existence of a decimal format named 'ch' in which
the grouping separator is ʹ and the decimal separator is
·:
The expression format-number(1234.5678, '#ʹ##0·00',
'ch') returns "1ʹ234·57".
The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':
The expression format-number(1234.5678, '00.000E0', 'fortran') returns "12.346E2".
The expression format-number(0.234, '0.0E0', 'fortran') returns "2.3E-1".
The expression format-number(0.234, '#.00E0', 'fortran') returns "0.23E0".
The expression format-number(0.234, '.00E0', 'fortran') returns ".23E0".
A dynamic error is raised if the name specified as
the $decimal-format-name argument is neither a valid lexical QName nor a
valid 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.
