Accumulators were introduced in XSLT 3.0 to enable data that is read during streamed processing of a document to be accumulated, processed or retained for later use. However, they may equally be used with non-streamed processing.
[Definition: An accumulator defines a series of values associated with the nodes of the tree. If an accumulator is applicable to a particular tree, then for each node in the tree, other than attribute and namespace nodes, there will be two values available, called the pre-descent and post-descent values. These two values are available via a pair of functions, accumulator-before and accumulator-after.]
There are two ways the values of an accumulator can be established for a given tree: they can be computed by evaluating the rules appearing in the xsl:accumulator declaration, or they can be copied from the corresponding nodes in a different tree. The second approach (copying the values) is available via the snapshot and copy-of functions, or by use of the xsl:copy-of instruction specifying copy-accumulators="yes". Accumulator values are also copied during the implicit invocation of the snapshot function performed by the xsl:merge instruction.
Note:
Accumulators can apply to trees rooted at any kind of node. But because they are most often applied to trees rooted at a document node, this section sometimes refers to the “document” to which an accumulator applies; use of this term should be taken to include all trees whether or not they are rooted at a document node.
Accumulators can apply to trees rooted at nodes (such as text nodes) that cannot have children, though this serves no useful purpose. In the case of a tree rooted at an attribute or namespace node, there is no way to obtain the value of the accumulator.
The following sections give first, the syntax rules for defining an accumulator; then an informal description of the semantics; then a more formal definition; and finally, examples. But to illustrate the concept intuitively, the following simple example shows how an accumulator can be used for numbering of nodes:
This example assumes document input in which figure elements can appear within chapter elements (which we assume are not nested), and the requirement is to render the figures with a caption that includes the figure number within its containing chapter.
When the document is processed using streaming, the xsl:number instruction is not available, so a solution using accumulators is needed.
The required accumulator can be defined and used like this:
<xsl:accumulator name="figNr" as="xs:integer"
initial-value="0" streamable="yes">
<xsl:accumulator-rule match="chapter" select="0"/>
<xsl:accumulator-rule match="figure" select="$value + 1"/>
</xsl:accumulator>
<xsl:mode streamable="yes"/>
<xsl:template match="figure" expand-text="yes">
<xsl:apply-templates/>
<p>Figure {accumulator-before('figNr')}</p>
</xsl:template>- Summary
Returns the post-descent value of the selected accumulator at the context node.
- Signature
fn:accumulator-after( |
$name | as (xs:string | xs:QName) | |
) as item()* |
- Properties
This function is deterministicFO, context-dependentFO, and focus-dependentFO.
- Rules
The $name argument specifies the name of the accumulator. The value of the argument must be either an xs:QName, or a string containing an EQName. If it is a lexical QName, then it is expanded as described in 5.1.1 Qualified Names (no prefix means no namespace).
The function returns the post-descent value A(N) of the selected accumulator where N is the context node, as defined in 19.4 Formal Model for Accumulators.
If the context item is a node in a streamed document, then the accumulator must be declared with streamable="yes".
Note:
The converse is not true: an accumulator declared to be streamable is available on both streamed and unstreamed nodes.
- Error Conditions
The following errors apply: [see ERR XTDE3340], [see ERR XTDE3350], [see ERR XTTE3360], [see ERR XTDE3362], [see ERR XTDE3400].
For constraints on the use of accumulator-after when streaming, see ???.For constraints on the use of accumulator-after when streaming, see 12.8.1 Streamability of the accumulator-after FunctionSG.For constraints on the use of accumulator-after when streaming, see 12.8.1 Streamability of the accumulator-after Function???SG.
- Notes
The accumulator-after function can be applied to a node whether or not the accumulator has a phase="end" rule for that node. In effect, there is a phase="end" rule for every node, where the default rule is to leave the accumulator value unchanged; the accumulator-after function delivers the value of the accumulator after processing the explicit or implicit phase="end" rule.
In XSLT 4.0, the argument can be supplied as a QName literal, for example accumulator-before( #accum ).
- Examples
Given the accumulator: |
<xsl:accumulator name="w" initial-value="0" streamable="true" as="xs:integer">
<xsl:accumulator-rule match="text()"
select="$value + count(tokenize(.))"/>
</xsl:accumulator> |
and the template rule: |
<xsl:template match="section">
<xsl:apply-templates/>
(words: <xsl:value-of select="accumulator-after('w') - accumulator-before('w')"/>)
</xsl:template> |
The stylesheet will output at the end of each section a (crude) count of the number of words in that section. |
Arrays are defined in the XDM Data Model: see [XDM 4.0] section 8.3 Array Items.
As with maps (see ???) arrays cannot contain references to streamed nodes, because all expressions, instructions, and functions that construct arrays are defined to have operand usage .As with maps (see 12.1 Maps and StreamingSG) arrays cannot contain references to streamed nodes, because all expressions, instructions, and functions that construct arrays are defined to have operand usage .As with maps (see 12.1 Maps and Streaming???SG) arrays cannot contain references to streamed nodes, because all expressions, instructions, and functions that construct arrays are defined to have operand usage .
Unlike maps, array constructors have no special rules allowing the members of the array to be constructed using multiple consuming subexpressions.