Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
General rules: see .
The function returns the nearest (that is, numerically closest) value to
$arg that is a multiple of ten to the power of minus
$precision. If two such values are equally near (e.g. if the fractional
$arg is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types
xs:integer, it is
guaranteed that if the type of
$arg is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$arg is an instance of
is less than one, then the result may
be an instance of
The first signature of this function produces the same result as the second signature
For arguments of type
If the argument is
NaN, positive or negative zero, or positive or
negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to
xs:decimal using an
implementation of xs:decimal that imposes no limits on the number of digits that
can be represented. The function is applied to this
and the resulting
xs:decimal is cast back to
xs:double as appropriate to form the function result. If the
xs:decimal value is zero, then positive or negative zero is
returned according to the sign of the original argument.
fn:round-half-to-even(3.567812e+3, 2) returns
fn:round-half-to-even(4.7564e-3, 2) returns
fn:round-half-to-even(35612.25, -2) returns
This function is typically used in financial applications where the argument is of type
xs:decimal. For arguments of type
xs:double the results may be counter-intuitive. For example, consider
round-half-to-even(xs:float(150.015), 2). The result is not 150.02 as
might be expected, but 150.01. This is because the conversion of the
xs:float value represented by the literal 150.015 to an
xs:decimal produces the
xs:decimal value 150.014999389...,
which is closer to 150.01 than to 150.02.