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:exactly-one

Category:

Functions for sequences

Origin:

XPath 2.0

Return value:

A sequence; the input sequence in case it consists of exactly one item.

Call/Arguments:

fn:exactly-one($sequence)

$sequence:

An input sequence consisting of, in principle, any number of items which is only passed on by the function if it consists of exactly one item. In other cases (zero or more than one item), an error is reported. This corresponds to the testing of the input sequence for the cardinality »exactly one« item.

Purpose of use:

The fn:exactly-one() function enforces the output of a sequence consisting of exactly one item by rejecting all those sequences which do not cope with this constraint. In these cases, the function terminates the processing with an error message (err:FORG0005).

The function can be used wherever sequences from exactly one item (singleton sequences) are absolutely required and the processing has to be terminated if this is not the case. Whereas sequences consisting of exactly one item are passed on unchanged by the function.

Example 1 – calling with wrong item number in the input sequence:

fn:exactly-one((1, 2, 3)) or fn:exactly-one(())

result each in the error message: »fn:exactly-one called with a sequence containing zero or more than one item« ( err:FORG0005). In the first case the input sequence contains too many items, in the second case too few.

Example 2 – calling with exactly one item in the input sequence:

fn:exactly-one((1))

returns the sequence passed on (1).

Example 3 – catching the empty sequence for aggregate functions:

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

results in the abovementioned error message (see example 1), in case the input sequence $data of fn:avg() leads to the empty result sequence.

Explanation: In some cases the default behaviour of aggregate functions like fn:avg(), fn:max() or fn:min() is unwanted with regard to an empty result sequence – because they return the empty sequence. If, for example, an error message shall occur when there is no input data from which an average, a maximum or a minimum value can be calculated, a solution would be to test the return value by means of the fn:exactly-one() function. If an average value is calculated, this is passed on in a transparent manner. Whereas, in the case of the empty sequence, an error occurs.

Remark: The aggregate function fn:sum() behaves differently!
The aggregate function fn:sum() is not affected by the abovementioned problem because it returns a (also definable) zero value for an empty input sequence, but not the empty sequence.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:exactly-one($arg as item()*) as item()

   

<< back

next >>