XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (616 page)
Read XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition Online
Authors: Michael Kay
See Also
The Root Expression
/
on page 623 in Chapter 9.
round
The
round()
function returns the closest integer to the numeric value of the argument, as an instance of the same type as the argument.
For example, the expressionround(4.6)returns the
xs:decimal
value 5.0.
Changes in 2.0
The function has been generalized to accept arguments of any numeric type.
Signature
| Argument | Type | Meaning |
| value | Numeric? | The input value. If an empty sequence is supplied, an empty sequence is returned. |
| Result | Numeric? | The result of rounding the first argument to the nearest integer, but expressed as a value of the same type as the input value . |
Effect
The XPath specification is very precise about the results of
round()
. The rules are given in the tables below. The first table applies regardless of the type:
| If the argument is… | Then the result is… |
| Equal to an integer N | N |
| Between N and N+ 0.5 | N |
| Exactly N + 0.5 | N + 1 |
| Between N + 0.5 and N + 1 | N + 1 |
Note that this rounds +3.5 to +4.0, but −3.5 to −3.0.
For values of type
xs:float
and
xs:double
, there are additional rules to cover the special IEEE values. The concepts of positive and negative zero, positive and negative infinity, and NaN are explained in the section on the
xs:doubl
e
type in Chapter 5, page 198.
| If the argument is… | Then the result is… |
| Between −0.5 and zero | Negative zero |
| Positive zero | Positive zero |
| Negative zero | Negative zero |
| Positive infinity | Positive infinity |
| Negative infinity | Negative infinity |
| NaN (not-a-number) | NaN |
Examples
| Expression | Result |
| round(3.2) | xs:decimal 3.2, displayed as “3.2” |
| round(4.6e0) | xs:double 5.0e0, displayed as “5” |
| round(7.5) | xs:decimal 8.0, displayed as “8” |
| round(-7.5) | xs:decimal -7.0 , displayed as “-7” |
| round(-0.0e0) | xs:double negative zero, displayed as “0” |
Usage
The
round()
function is useful when you want the nearest integer, for example, when calculating an average, or when deciding the geometric coordinates for an object to be displayed. If you want to convert the result to a value of type
xs:integer
, use the
xs:integer()
constructor function, or the constructround($x) idiv 1.
See Also
ceiling()
on page 723
floor()
on page 779
round-half-to-even()
in the next entry
idivoperator on page 574 in Chapter 8
round-half-to-even
The
round-half-to-even()
function performs rounding to a specified number of decimal places. The rounding algorithm used is to round to the nearest value that has the required precision, choosing an even value if two values are equally close.
Signature
| Argument | Type | Meaning |
| input | Numeric? | The number to be rounded. If an empty sequence is supplied, an empty sequence is returned. |
| precision (optional) | xs:integer | If positive, the number of significant digits required after the decimal point. If negative, the number of zeroes required at the end of the integer part of the result. The default is zero. |
| Result | Numeric? | The rounded number. This will have the same type as the supplied number . |
Effect
The
precision
argument indicates the number of decimal digits required after the decimal point. More generally, the function rounds the supplied number to a multiple of 10
−
p
where
p
is the requested precision. So if the requested precision is 2, the value is rounded to a multiple of 0.01; if it is zero, the value is rounded to a multiple of 1 (in other words, to an integer), and if it is −2, the value is rounded to a multiple of 100.
If the
precision
argument is not supplied, the effect is the same as supplying the value zero, which means the value is rounded to an integer.
The value is rounded up or down to whichever value is closest: for example, if the required precision is 2, then 0.123 is rounded to 0.12 and 0.567 is rounded to 0.57. If two values are equally close then the half-to-even rule comes into play: 0.125 is rounded to 0.12, while 0.875 is rounded to 0.88.
This function is designed primarily for rounding of
xs:decimal
values, but it is also available for other numeric types. For
xs:integer
, the behavior is exactly the same as if the value were an
xs:decimal
(which, in fact, it is). For
xs:double
and
xs:float
it may not work so well. The specification states that the floating-point value is first cast to an
xs:decimal
value; the rounding is then applied to this decimal number, and the result is then converted back to the original type. This process may introduce rounding errors, and may fail completely if the implemetation supports a range of values for
xs:decimal
which is less than the range allowed for
xs:double
.