XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

fn:avg

Category:

Aggregation

Origin:

XPath 2.0

Return value:

The average value of the items of an input sequence (sum divided by number). The type of the result corresponds to the type of the input values.

Call/Arguments:

fn:avg($inputSequence)

$inputSequence:

The items of the input sequence have to be of the same type (or subtype of the same type) and to this type the numeric addition and the subsequent integer division have to be applicable. Therefore, it may be (after an appropriate, automatic type promotion) similar number values or duration values (xs:yearMonthDuration or xs:dayTimeDuration). A passed on, untyped atomic type xs:untypedAtomic is cast to the xs:double number type. If the values passed on are not compatible to each other after the type promotion, the error message »Invalid argument type« (err:FORG0006) occurs.

Purpose of use:

The function calculates an average value from the items of a sequence passed on, according to their sum divided by the number of items. If the input sequence is empty, the empty sequence is returned.

The calculation is made analoglous to

sum($inputSequence) div count($inputSequence)

Number values of different types are transformed into same types according to the rules for type promotion. If the input sequence contains one or more NaN values, the return value of the function is NaN.

If the sequence consists of values of the duration type, all items have to be of xs:yearMonthDuration or of xs:dayTimeDuration type.

Within the input sequence, values of xs:untypedAtomic type may be contained which, in this case, are adjusted to the type of the rest of the items. If all values are of xs:untypedAtomic type, they are cast to xs:double.

Example 1 - average from a sequence of xs:integer integers:

fn:avg(4, 5, 6)

Results in: 5.

In this simple case, the values are added and divided by the number of contained items.

Example 2 - average from a sequence of duration values:

fn:avg( xs:yearMonthDuration("P10Y"),

xs:yearMonthDuration("P20M")

)

Results in: xs:yearMonthDuration("P70M").

When calculating averages from duration values of different units, they will be added after conversion into the smallest unit and divided by the number of values. Here, a sum of 140 months and thus an average value of 70 months is the result of the first value P10Y (10 years, accordingly 120 months) and the second value P20M (20 months).

Example 3 - non-permitted operation:

fn:avg(xs:yearMonthDuration("P10Y"), 4, 5, 6)

results in the error message »Invalid argument type« (err:FORG0006). In the sequence a conversion of the types xs:yearMonthDuration and xs:integer into one another is not possible – the error message occurs because of this non-compatibility.

Example 4 - interception of an empty sequence with fn:exactly-one:

In some cases, the behaviour of fn:avg() with regard to an empty input sequence is unwanted. If, for example, an error message shall occur when no input data exist from which an average shall be calculated, a solution would be to check the return value by using the fn:exactly-one() function. If a (per definition single) average value is returned, it will be passed on in a transparent way; in the case of the empty result sequence, however, an error is reported.

fn:exactly-one( fn:avg($data)

)

results in the error message »fn:exactly-one called with a sequence containing zero or more than one item« (err:FORG0005), in case the $data input expression of fn:avg() is the empty sequence and, therefore, the function also returns the empty sequence instead of the desired average value.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:avg($srcval as xs:anyAtomicType*) as xs:anyAtomicType?

   

<< back

next >>