xsl:iterate

Used to iterate over a sequence, with the option to set parameters for use in the next iteration.

Category: instruction
Content: ( xsl:param* , xsl:on-completion? , sequence-constructor )
Permitted parent elements: any XSLT element whose content model is sequence-constructor; any literal result element

Attributes

select

expression

Input sequence over which the iteration is processed.

Saxon availability

Available in XSLT 3.0 and later versions. From Saxon 9.8, available in all editions. Implemented in Saxon-PE and Saxon-EE since Saxon 9.6. Available for all platforms.

Notes on the Saxon implementation

For xsl:iterate to be streamable, the W3C rules require that the select expression must be "striding", which essentially means that it may use the child axis but not the descendant axis (to ensure that selected nodes do not overlap each other). In many cases the restriction can be circumvented by using the outermost function, for example the expression outermost(//title) is striding even though it uses the descendant axis.

Details

The xsl:iterate instruction is new in XSLT 3.0. It is similar to xsl:for-each, except that the items in the input sequence are processed sequentially, and after processing each item in the input sequence it is possible to set parameters for use in the next iteration. It can therefore be used to solve problems that in XSLT 2.0 require recursive functions or templates.

The xsl:iterate instruction is motivated by use-cases for streaming, but it can also be used profitably in non-streaming situations. For more information see Streaming with xsl:iterate.

The instruction allows a child element xsl:on-completion which defines processing to be carried out when the input sequence is exhausted. The instructions within xsl:on-completion have access to the final values of the parameters declared in the xsl:next-iteration instruction set while processing the last item in the sequence. An xsl:break element may be used within the enclosed sequence constructor of an xsl:iterate instruction, which causes premature completion before the entire input sequence has been processed.

Examples

Example 1

Computes the running balance of a sequence of financial transactions:

<xsl:iterate select="transactions/transaction"> <xsl:param name="balance" select="0.00" as="xs:decimal"/> <xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/> <balance date="{@date}" value="{$newBalance}"/> <xsl:next-iteration> <xsl:with-param name="balance" select="$newBalance"/> </xsl:next-iteration> </xsl:iterate>

Example 2

Copies the input sequence up to the first <br> element:

<xsl:iterate select="*"> <xsl:choose> <xsl:when test="self::br"> <xsl:break/> </xsl:when> <xsl:otherwise> <xsl:copy-of select="."/> </xsl:otherwise> </xsl:choose> </xsl:iterate>

Links to W3C specifications

XSLT 3.0 Specification

XSLT 4.0 Specification