fn:sum

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

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

   

Kategorie: Aggregation

Herkunft: XPath 1.0

Rückgabewert: Ein Wert vom Typ der Einzelwerte der Eingabesequenz (des Nodesets), der deren durch Addition ermittelte Summe darstellt. Es kann sich bei den Typen um Zahlenwerte (number bzw. numeric) oder (nur XPath 2.0) auch um Zeitdauerwerte (keine Datums- oder Zeitwerte) handeln.

Aufruf/Argumente:

fn:sum($sequenz, $nullwert?)

$sequenz:
Obligatorisch. Eine Sequenz. Die Items der Eingabesequenz müssen von gleichem Typ oder in einen gemeinsa­men Typ umwandelbar sein.

$nullwert: (neu in XPath 2.0)
Optional. Ein Wert beliebigen atomaren Typs. Mittels des zweiten Arguments kann derjenige Wert festgelegt werden, der bei leerer Eingangssequenz zurückgegeben wird. Wird kein zweites Argument übergeben, so gibt die Funktion in diesem Fall den xs:integer-Wert 0 zurück. Dieses Argument steht in XPath 1.0 nicht zur Verfügung.

Verwendungszweck:

Sowohl in XPath 2.0 als auch in XPath 1.0 ermittelt die Funktion die Summe der ihr im Rahmen einer Sequenz bzw. eines Node­sets übergebenen Einzelwerte durch Addition. Grundsätzlich müssen die über­gebenen Typen also vom +-Operator unterstützt werden.

Es wird ein Wert vom gleichen Datentyp wie dem der Items der Eingabesequenz nach ihrer Vereinheitlichung (siehe unten) zurückgegeben. Der zurückgegebene Wert stellt die Summe der Eingabewerte dar.

Die Eingabesequenz wird durch Typ-Umwandlung und -Promotion vereinheitlicht, die sich wie folgt vollzieht: Sind Items der Eingabesequenz vom Typ xs:untypedAtomic, so werden sie in den Zahlentyp xs:double umgewandelt. Der Typ xs:float (oder durch Ein­schränkung von ihm abgeleitete Typen) wird durch Typ-Promotion zum Typ xs:double aufgewertet. Der absolute numerische Wert bleibt dabei unverän­dert. Dies gilt auch für Werte des Typs xs:decimal oder von diesem abgelei­tete Typen, die kontextabhängig entweder nach xs:float oder nach xs:double gewandelt werden. In der Regel wird sich bei einer Sequenz aus gemischten numerischen Typen ein Summenwert vom Typ xs:double erge­ben.

Liegt keine Typgleichheit vor und ist diese auch durch Typumwandlungen nicht zu gewährleisten (Beispiel 3), so wird ein entsprechender Feh­ler ausgegeben: »Invalid argument type« (err:FORG0006).

Wird der Funktion die leere Sequenz übergeben, so gibt sie eine Zahl vom Typ xs:integer mit dem Wert 0 zurück, oder, sofern ein zweites Argument $nullwert übergeben wurde, dessen Wert. Ein Fehler wird nicht gemeldet. Enthält die Eingabesequenz nach Vereinheitlichung Items vom Wert NaN, so gibt die Funktion den Wert NaN zurück.

Summe von Zeitdauerwerten:
Sollen Zeitdauerwerte summiert werden, so müssen alle Items der übergebe­nen Sequenz entweder vom Typ xs:yearMonthDuration oder vom Typ xs:dayTimeDuration sein.

Hinweis – Keine Addition von Zeit- und Zeitdauerwerten untereinander!
Der +-Operator selbst unterstützt zwar eine Addition von Zeitdau­erwerten mit Datums- oder Zeitwerten (xs:date, xs:dateTime, xs:time), jedoch nicht im Sinne einer Summenbildung. Daher können diese Typen nicht im Rahmen von fn:sum() gemeinsam mit Zeitdauerwerten in einer Eingabesequenz verwendet werden.

Verhalten in XPath 1.0:
In XPath 1.0 ist der Rückgabewert der Funktion vom Typ number, die Summe einer Reihe von numerischen Werten, die aus den Stringwerten der Nodes eines übergebenen Nodeset ermittelt werden. Ist das übergebene Argument kein Nodeset, so erfolgt eine Fehlermeldung.

Die Stringwerte der beteiligten Nodes werden in Zahlen umgewandelt und addiert. Ist eine Umwandlung bei einem oder mehreren Nodes nicht erfolg­reich, so ist das Endergebnis stets NaN. Falls ein leerer Nodeset übergeben wurde, ist das Ergebnis 0, also die Zahl Null. Letzteres gilt in XPath 2.0 analog für eine leere Sequenz.

Die Umwandlung der Stringwerte erfolgt auf die gleiche Weise wie bei der Funktion number() – der umzuwandelnde String darf also mit Leerzeichen beginnen und ein Vorzeichen besitzen, muss aber ansonsten (außer maximal einem erlaubten Dezimalpunkt) aus Ziffern bestehen. Alle anderen Fälle, also auch der leere String, ergeben NaN.

Es können in XPath 1.0 mit sum() nur solche Werte summiert werden, die sich auch tatsäch­lich als Stringwerte von Nodes im Dokument befinden. Es ist daher nicht mög­lich, auf irgendeinem Weg Zwischenergebnisse einer Operation mittels sum() zu summieren. So kann man z.B. nicht den Gesamtwert von verkauften Waren ermitteln, wenn erst Zwischenergebnisse aus Preis und Stückzahl berechnet werden müssen. Gesamtsummen von explizit vorhandenen Werten sind aller­dings möglich.

Beispiele:

Beispiel 1 – Summe der Werte einer Sequenz aus Zahlen:

fn:sum( (4, 7, 5)
  )

ergibt 16. Besteht die Eingabesequenz aus Zahlen, so werden diese zunächst in einen gleichmäßigen Datentyp (nach den Regeln der Typ-Promotion) umge­wandelt. Haben einzelne Items den Wert NaN, so werden sie bei der Summen­bildung nicht berücksichtigt. Der Summenwert besitzt den Typ, der sich aus der Typ-Promotion der Items der Eingabesequenz ergibt (z.B. xs:double).

Beispiel 2 – Summe der Werte einer Sequenz aus Zeitdauern:

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

ergibt den Wert P135M (135 Monate) vom Typ xs:yearMonthDuration. Die Items einer Eingabesequenz aus Zeitdauerwerten müssen entweder alle vom Typ xs:yearMonthDuration oder vom Typ xs:dayTimeDuration sein. Der Summenwert besitzt den Typ der Items der Eingabesequenz.

Beispiel 3 – Summe der Werte einer Sequenz inkompatibler Typen:

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

ergibt die Fehlermeldung »Invalid argument type«, da die Typen der Eingabesequenz nicht zueinander kompatibel sind (der Zeitdauer­wert ist nicht in einen Zahlenwert umwandelbar und umgekehrt).

Beispiel 4 – Leere Eingangssequenz und Nullwert:

fn:sum( (), 'Kein Eingangswert!'
  )

ergibt die Ausgabe Kein Eingangswert!, da die Eingabesequenz leer ist und dieser String für diesen Fall als alternativer Wert vereinbart wurde.

Beispiel 5 – Summe der Werte einer Sequenz aus Attributknoten:

Eine Buchliste besteht aus einer Reihe von Büchern verschiedener Autoren und Verlage; jedes Buch besitzt ein Attribut mit einer Preisangabe. Solange nur die Gesamtpreise von Büchern eines/mehrerer Autoren/Verlage ermittelt werden sollen, ist dies problemlos möglich. Das XML-Dokument hat beispielsweise fol­gende Struktur:

<buecher> 
  <buch autor="May, Karl" verlag="KMV" preis="19.80" titel="Winnetou I"/> 
  <buch autor="May, Karl" verlag="KMV" preis="19.80" titel="Winnetou II"/>
  <buch autor="May, Karl" verlag="KMV" preis="19.80" titel="Winnetou III"/>
  <buch autor="May, Karl" verlag="KMV" preis="19.80" titel="Durch die Wüste"/>
  <buch autor="Heisenberg" verlag="W. d. W." preis="59.90" titel="Unschärferelation"/>
</buecher>

Die Summe der Preise aller Bücher erhält man folgendermaßen:

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

Die Summe der Preise der Bücher eines speziellen Autors in der Liste (hier 'May, Karl') erhält man durch ein zusätzliches Predicate:

<xsl:value-of select="fn:sum(//buch[@autor='May, Karl']/@preis)"/>

Funktionsdefinition:

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?

   

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Galileo Press, Rheinwerkallee 4, 53227 Bonn