<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensions" page="functions" subpage="index"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: saxon:index()</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: saxon:index()"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>saxon:index()</h1>
<p><b>saxon:index($sequence as item()*, $expression as jt:net.sf.saxon.functions.Evaluate-PreparedExpression) ==> jt:com.saxonica.expr.IndexedSequence</b></p>
<p><b>saxon:index($sequence as item()*, $expression as jt:net.sf.saxon.functions.Evaluate-PreparedExpression, $collation as xs:string) ==> jt:com.saxonica.expr.IndexedSequence</b></p>
<p>The first argument is any sequence. Usually it will be a sequence of nodes, but this is
not essential. This is the sequence being indexed.</p>
<p>The second argument is a compiled XPath expression. Most commonly, the argument will be written as
a call to the <a class="bodylink" href="../../extensions/functions/expression.xml">saxon:expression()</a>
extension function. This expression is evaluated once for each item in the sequence being indexed, with that
item as the context node. (The context position and size reflect the position of this item in the sequence, but
this will not normally be useful.) The result of the expression is atomized. Each value in the atomized result
represents a key value: the item in the indexed sequence can be efficiently found using any of these key values.</p>
<p>If a key value is of type <code>xs:untypedAtomic</code>, it is treated as a string. If you want to treat
the value as numeric, say, then perform a conversion within the expression.</p>
<p>The optional third argument is the URI of a collation to be used when comparing strings. For example, if you
want string matching to be accent- and case-blind, specify <code>"http://saxon.sf.net/collation?strength=primary"</code>.</p>
<p>The result is an object of type <code>{http://saxon.sf.net/java-type}com.saxonica.expr.IndexedSequence</code>,
that can be supplied as input to the <code>saxon:find()</code> function.</p>
<p>For example, consider a source document of the form:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code><doc>
<town name="Amherst" state="NH"/>
<town name="Amherst" state="MA"/>
<town name="Auburn" state="MA"/>
<town name="Auburn" state="NH"/>
<town name="Auburn" state="ME"/>
<town name="Bristol" state="RI"/>
<town name="Bristol" state="ME"/>
<town name="Bristol" state="CT"/>
<town name="Bristol" state="NH"/>
<town name="Bristol" state="VT"/>
<town name="Cambridge" state="ME"/>
</doc></code>
</pre>
</div>
<p>and suppose there is a requirement to find <code>town</code> elements efficiently given the abbreviation for the
<code>state</code>. You can do this by first setting up an indexed sequence. In XQuery you can write:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>declare namespace saxon="http://saxon.sf.net/";
declare namespace java="http://saxon.sf.net/java-type";
declare variable $indexedTowns
as java:com.saxonica.expr.IndexedSequence
:= saxon:index(//town, saxon:expression("@state"));</code>
</pre>
</div>
<p>This could be a local variable (declared in a <code>let</code> clause) rather than a global variable.
The XSLT equivalent is:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code><xsl:variable name="indexedTowns"
select="saxon:index(//town, saxon:expression('@state'))"
as="java:com.saxonica.expr.IndexedSequence"/></code>
</pre>
</div>
<p>You can then find all the towns in New Hampshire using the expression:</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>saxon:find($indexedTowns, "NH")</code>
</pre>
</div>
<p>Indexed sequences are primarily useful in XQuery, where they provide functionality equivalent to the
standard <code>xsl:key</code> mechanism in XSLT. There are some cases, however, where indexed sequences
can also be useful in XSLT. One example is where there is a need for an index to span multiple documents: the
XSLT <code>key()</code> function will only search within a single document.</p>
<p>An indexed sequence can only be used in the first argument to the <code>saxon:find()</code> function.
If you want access to the sequence
that was passed as the first argument to <code>saxon:index()</code>,
you can get this by calling <code>saxon:find()</code> with a single argument.</p>
<p><i>The <code>saxon:index</code> function is available only with Saxon-EE.</i></p>
<p>See also: <a class="bodylink" href="../../extensions/functions/find.xml">saxon:find()</a>.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="in-summer-time.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
