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:distinct-values

Category:

Functions for sequences

Origin:

XPath 2.0

Return value:

A sequence generated from an input sequence consisting of items of atomic type by removing duplicates of the same value.

Call/Arguments:

fn:distinct-values($inputSequence, $collation-URI?)

$inputSequence:

The input argument has to be a sequence consisting of items of atomic type from which duplicate values shall be removed. If the input sequence is empty, the function returns the empty sequence.

$collation-URI:

Optional. The second argument consists of a xs:string string which names the URI string of the collation to be used. The value has to lexically correspond to the xs:anyURI type. If this is not the case, an error message (»Invalid collationURI«) is outputted. If no second argument is passed on, the default collation is used for comparisons of string values. If no items of xs:string type are contained in the sequences to be compared, the collation argument will be ignored.

Purpose of use:

From the input sequence all duplicates, except for one, of those values are removed which were recognised as equal because of the application of the eq operator. The remaining values appear in the original order (sequence order) in the output sequence. If the input sequence is empty, the output sequence ist empty, too.

The values of the input sequence must be available in a form (referred to as total order) which ensures their comparability. This basically means that it must be possible to determine which of both factors recognised as unequal is greater or less than the other. A basic requirement is the type equality of all values, whereby also subtypes (derived types) of the appropriate types are permitted.

Comparison of untyped atomic values:

Untyped atomic values of xs:untypedAtomic type are compared as if they were of xs:string type.

Comparsion of numerical values:

Where required, the type equality of numerical values is created by type promotion (transformation into a superordinated numeric type). For sequences of values of xs:float and xs:double type, NaN values are regarded as equal (which is contrary to the other conventions!). If, as a consequence, in the input sequence several NaN values are contained, only one of them will be returned. Similarly, in this context the values +0.0 (positive zero) and -0.0 (negative zero) are considered as equal. To be exact, there is basically no possibility in XPath to differentiate between »+0« and »-0«!

Comparison of date and time values:

The comparability of values of the types xs:dateTime, xs:date or xs:time requires the fundamental presence or absence of a timezone indication. If such a value does not have an appropriate indication, the implicit timezone indication is added resulting from the evaluation context. The date or time value is – if required – normalised on this basis and used for the comparisons in this form. If two values only differ with regard to their timezone indication, it is left to the implementation which of both values will be preserved.

Comparison of character strings:

The equality of xs:string character strings is determined by means of a collation. For this purpose, the default collation or the collation determined by the second function argument is used. If a collation was indicated and the items of the input sequence are not of xs:string type, the indication of the collation will be ignored.

Example 1 – duplication of a number in a sequence:

fn:distinct-values((1, 2.0, 3, 2))

results in: (1, 2, 3).

Remark: Other applications may output different result orders, such as (1, 3, 2.0).

Example 2 – duplication of a string value in a sequence:

fn:distinct-values(('abc','bcd','def','abc','efg'))

results in: ('abc', 'bcd', 'def', 'efg').

Example 3 – positive and negative zero in the input sequence:

fn:distinct-values((+0.0, -0.0))

results in: 0 (which means the zero values are regarded as equal).

Remark: In this case, the specification does not determine the behaviour.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:distinct-values($arg as xs:anyAtomicType*)

as xs:anyAtomicType*

fn:distinct-values($arg as xs:anyAtomicType*,

$collationLiteral as xs:string)

as xs:anyAtomicType*

   

<< back

next >>