round-half-to-even function

The fn:round-half-to-even function returns the numeric value with a specified precision that is closest to a specific numeric value.

Syntax

Read syntax diagramSkip visual syntax diagramfn:round-half-to-even( numeric-value, precision)
numeric-value
An atomic value or an empty sequence.
If numeric-value is an atomic value, it has one of the following types:
  • xs:float
  • xs:double
  • xs:decimal
  • xs:integer
  • xdt:untypedAtomic
  • A type that is derived from any of the previously listed types

If numeric-value has the xdt:untypedAtomic data type, it is converted to an xs:double value.

precision
The number of digits to the right of the decimal point to which numeric-value is to be rounded. precision is an xs:integer value. The default value for precision is 0.

Returned value

If numeric-value is not the empty sequence, and precision is 0 or not specified, the returned value is the integer that is closest to numeric-value. If numeric-value is equally close to two integers, the returned value is the even integer.

If numeric-value is not the empty sequence, and precision is not 0, the returned value is a numeric value that has precision digits to the right of the decimal point and is closest to numeric-value. If numeric-value is equally close to two values, the returned value is the value whose least significant digit is even.

The data type of the returned value depends on the data type of numeric-value:
  • If numeric-value is xs:float, xs:double, xs:decimal, or xs:integer, the value that is returned has the same type as numeric-value.
  • If numeric-value has a data type that is derived from xs:float, xs:double, xs:decimal, or xs:integer, the value that is returned has the direct parent data type of numeric-value.

If numeric-value is the empty sequence, the returned value is the empty sequence.

Examples

Example without a precision argument: The following function returns the rounded value of 0.5:
fn:round-half-to-even(0.5)

The returned value is 0.

Example with a non-zero precision argument: The following function returns 1.5432, rounded to two decimal places.
fn:round-half-to-even(1.5432,2)

The returned value is 1.54.

Example with negative precision: The following function returns 35600.
fn:round-half-to-even(35612.25, -2)