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:sum

Category:

Aggregation

Origin:

XPath 1.0

Return value:

A value of the type of the individual values of the input sequence (of the node set) which represents their sum determined by addition. The types may be number values (number or numeric) or (only in XPath 2.0) also duration values (no date values or time values).

Call/Arguments:

fn:sum($sequence, $zeroValue?)

$sequence:

Obligatory. A sequence. The items of the input sequence must be of the same type or convertible into the same type.

$zeroValue:

(new in XPath 2.0)

Optional. A value of any atomic type. By means of the second argument that value can be determined which is returned for the empty input sequence. If no second argument is passed on, the function returns the value 0 as xs:integer. This argument is not available in XPath 1.0.

Purpose of use:

In XPath 2.0 as well as in XPath 1.0 the function determines by addition the sum of the individual values passed on in the context of a sequence or a node set. In principle, the types passed on must be supported by the + operator.

A value of the same data type as the one of the items of the input sequence after their unification (see below) is returned. The returned value is the sum of the input values.

The input sequence is unified by type conversion and type promotion which happens as follows: If the items of the input sequence are of xs:untypedAtomic type, they are converted to the xs:double number type. The xs:float type (or types derived from it by limitation) is revalued by type promotion to the xs:double type. The absolute numerical value remains unchanged. This also applies for values of the xs:decimal type or for types derived from it which are converted to xs:float or xs:double, depending on the context. As a rule, for a sequence of mixed numeric types a sum value of the xs:double type would be the result.

If no equality of types is available and it cannot be ensured by type conversion (example 3), an appropriate error is outputted: »Invalid argument type« (err:FORG0006).

If the empty sequence is passed on to the function, it returns a number of xs:integer type with the value 0 or, provided that a second argument $zeroValue was passed on, its value. An error is not reported. If, after unification, the input sequence contains items of the NaN value, the function returns the NaN value.

Sum of duration values:

If duration values shall be summed up, all items of the sequence passed on must be of xs:yearMonthDuration or xs:dayTimeDuration type.

Note: no addition of time values and duration values with each other
The + operator itself supports an additon of duration values with date or time values (xs:date, xs:dateTime, xs:time), but not in the sense of a summation. Therefore, these types cannot be used together with duration values in an input sequence within the scope of fn:sum().

Behaviour in XPath 1.0:

In XPath 1.0 the return value of the function is of number type, the sum of a series of numeric values which are determined from the string values of the nodes of a node set passed on. If the argument passed on is not a node set, an error message occurs.

The string values of the involved nodes are converted to numbers and added. If the conversion for one or more nodes is not successful, the final result is always NaN. If an empty node set was passed on, the result is 0, which means the number zero. The latter applies analogously in XPath 2.0 for an empty sequence.

The conversion of the string values is made in the same way as for the number() function. The string to be converted may start with space characters and may have a leading sign, but, apart from that, it must consist of digits (except for one permitted decimal point at the maximum). All other cases, also the empty string, result in NaN.

In XPath 1.0 with sum() only such values can be summed which really exist as string values of nodes in the document. Therefore, it is not possible to sum, by whatever means, interim results of an operation by means of sum(). For example, the total value of goods sold cannot be determined if, at first, interim results of price and number of pieces must be calculated. However, total sums of explicitly existing values are possible.

Example 1 – sum of the values of a sequence of numbers:

fn:sum( (4, 7, 5)

)

results in: 16. If the input sequence consists of numbers, they are initially converted to a uniform data type (according to the rules of the type promotion). If individual items have the NaN value, they are not taken into account for the summation. The sum value is of the type which results from the type promotion of the items of the input sequence (e.g. xs:double).

Example 2 – sum of the values of a sequence of durations:

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

xs:yearMonthDuration("P15M") )

)

results in the value: P135M (135 months) of xs:yearMonthDuration type. The items of an input sequence of duration values must all be of xs:yearMonthDuration type or of xs:dayTimeDuration type. The sum value has the type of the items of the input sequence.

Example 3 – sum of the values of a sequence of incompatible types:

fn:sum( (xs:yearMonthDuration("P20Y"), 2.5)

)

results in the error message »Invalid argument type«, because the types of the input sequence are not compatible with one another (the duration value is not convertible into a number value and vice versa).

Example 4 – empty input sequence and zero value:

fn:sum( (), 'No input value!'

)

results in the output: No input value!, because the input sequence is empty and this string was agreed as alternative value for this case.

Example 5 – sum of the values of a sequence of attribute nodes:

A book list consists of a series of books of various authors and publishers; each book has an attribute with a price indication. As long as only the total prices of books of one/several authors/publishers shall be determined, this can be done problem-free. The XML document has, for example, the following structure:

<books> 
<book author="May, Karl" publisher="KMV" price="19,80" title="Winnetou I"/> 
<book author="May, Karl" publisher="KMV" price="19,80" title="Winnetou II"/>
<book author="May, Karl" publisher="KMV" price="19,80" title="Winnetou III"/>
<book author="May, Karl" publisher="KMV" price="19,80" title="Through the desert"/>
<book author="Heisenberg" publisher="W. d. W." price="59,90" title="Uncertainty principle"/>
</books>

The sum of all book prices can be generated as follows:

<xsl:value-of select="fn:sum(//book/@price)"/>

The sum of the book prices of a particular author in the list (here 'May, Karl') can be generated by an additional predicate:

<xsl:value-of select="fn:sum(//book[@author='May, Karl']/@price)"/>

Function definition:

XPath 1.0:

sum(number)=> number

XPath 2.0:

fn:sum($arg as xs:anyAtomicType*) as xs:anyAtomicType

fn:sum($arg as xs:anyAtomicType*,

$zero as xs:anyAtomicType?) as xs:anyAtomicType?

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany