<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensions" page="instructions" subpage="iterate"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: saxon:iterate</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: saxon:iterate"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>saxon:iterate</h1>
<p>The <code>saxon:iterate</code> element is used to iterate over a sequence. In simple cases the effect is exactly
the same as <code>xsl:for-each</code>. However, <code>saxon:iterate</code> offers a guarantee that the evaluation
will be sequential. It allows each iteration to set parameters which will be available during the next iteration, and it allows
early exit from the loop when some condition is true.</p>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">This extension was new in Saxon 9.1. Some changes have been made in 9.2, and it should still be
regarded as experimental. The primary motivation for introducing it
is to enable streamed processing of input files where there is a need to "remember" data read at the beginning of the document
for use when processing elements encountered later. Streaming is available only in Saxon-EE, but the basic functionality
of <code>saxon:iterate</code> is also available in Saxon-B</div>
<p>The following example shows how a shopping basket may be displayed with the cumulative values of the items:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
<saxon:iterate select="//ITEM" xmlns:saxon="http://saxon.sf.net/" xsl:extension-element-prefixes="saxon">
<xsl:param name="basketCost" as="xs:decimal" select="0"/>
<item cost="{$basketCost}"><xsl:copy-of select="TITLE"/></item>
<saxon:continue>
<xsl:with-param name="basketCost" select="$basketCost + (xs:decimal(PRICE), 0)[1]"/>
</saxon:continue>
</saxon:iterate>
</code>
</pre>
</div>
<p>The initial values of the parameters are taken from the <code>select</code> attribute of the <code>xsl:param</code> elements;
values for subsequent iterations are taken from the <code>xsl:with-param</code> in the <code>saxon:continue</code> instruction.
If any declared parameters are not given a value in the <code>saxon:continue</code> instruction, they retain their values from
the previous iteration.</p>
<p>The following example shows early exit from the loop when the cumulative value reaches 25.00:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
<saxon:iterate select="//ITEM" xmlns:saxon="http://saxon.sf.net/" xsl:extension-element-prefixes="saxon">
<xsl:param name="basketCost" as="xs:decimal" select="0"/>
<xsl:choose>
<xsl:when test="$basketCost gt 25.00">
<saxon:break/>
</xsl:when>
<xsl:otherwise>
<item cost="{$basketCost}"><xsl:copy-of select="TITLE"/></item>
<saxon:continue>
<xsl:with-param name="basketCost" select="$basketCost + (xs:decimal(PRICE), 0)[1]"/>
</saxon:continue>
</xsl:otherwise>
</xsl:choose>
</saxon:iterate>
</code>
</pre>
</div>
<p>The instructions <code>saxon:continue</code> and <code>saxon:break</code> must be lexically within the
<code>saxon:iterate</code> instruction and must not be followed by further instructions other than <code>xsl:fallback</code>.
They may appear within <code>xsl:if</code> or <code>xsl:choose</code> (nested to any depth) so long as none of the
intermediate instructions have a following sibling instruction. They must not appear with a nested <code>xsl:for-each</code>, a nested
literal result element, or nested inside any other instruction.</p>
<p>Within the body of the instruction, the context item, position, and size are available just as in <code>xsl:for-each</code>. The
value of <code>last()</code> reflects the size of the input sequence, which may be greater than the number of iterations if
<code>saxon:break</code> is used for early exit.</p>
<p>A <code>saxon:finally</code> instruction may be included as the last child of <code>saxon:iterate</code>; it is executed when
the end of the input sequence is reached. It is <b>not</b> evaluated if the loop is terminated using <code>saxon:break</code>. The focus
(context node, position, and size) for this instruction is undefined; however, variables
declared within the loop including the loop parameters are available for reference. The loop parameters have
their values as set by the <code>saxon:continue</code> instruction that ended the last normal iteration.</p>
<p><i>This instruction is similar in form to a tail-recursive function, but many users may find it easier to code. It is also easier to optimize.
The main difference from a tail-recursive function is that the context item is available to refer to the the item being processed in each
iteration, and there is no need to explicitly find the tail of the sequence when evaluating parameters for the next iteration, nor to test
whether the sequence is empty in order to terminate the iteration.</i></p>
<p><i>This instruction is available in Saxon-EE only</i></p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="mode.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
