<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensions" page="map" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: The Map Extension</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: The Map Extension"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>The Map Extension</h1>
<p>This is a family of extension functions, <code>map:new()</code>, <code>map:put()</code>, <code>map:get()</code>,
and <code>map:keys()</code> that can be used to maintain a general purpose map from atomic values to arbitrary
XDM sequences. The functions are in namespace <code>http://ns.saxonica.com/map</code>, and are available in
Saxon-PE and Saxon-EE only.</p>
<p>The map itself is an object of type <a class="bodylink" href="../javadoc/com/saxonica/functions/map/ImmutableMap.html"><code>javatype:com.saxonica.functions.map.ImmutableMap</code></a>, where the
prefix <code>javatype</code> corresponds to the namespace URI <code>http://saxon.sf.net/java-type</code>.</p>
<p>The map is immutable: adding an entry to a map creates a new map, leaving the original map unchanged. These
are therefore pure functions. Under the hood, the implementation avoids copying data whereever possible to
minimise the use of memory when a map is built incrementally.</p>
<p>The individual methods are described below:</p>
<ul/>
<p class="subhead">Creating a new map</p>
<p><b>map:new() ==> javatype:com.saxonica.functions.map.ImmutableMap</b></p>
<p>This method creates a new empty map</p>
<p class="subhead">Adding a value to the map</p>
<p><b>map:put(javatype:com.saxonica.functions.map.ImmutableMap, xs:anyAtomicType key, item()* value)
==> javatype:com.saxonica.functions.map.ImmutableMap</b></p>
<p>This method creates and returns a new map that differs from the supplied map by adding or replacing
a single entry. The key for the new entry is an atomic value supplied as <code>$key</code>, the
value is supplied as <code>$value</code>. The new entry is added to the map, replacing any
existing entry for the same key. Adding an entry whose value is the empty sequence is equivalent
to removing the entry from the map.</p>
<p class="subhead">Getting a value from the map</p>
<p><b>map:get(javatype:javatype:com.saxonica.functions.map.ImmutableMap, xs:anyAtomicType key)
==> item()*</b></p>
<p>This method locates the entry in the map for the given key, if there is one, and returns it.
If there is no entry, it returns the empty sequence. Keys are compared using the XPath <code>eq</code>
operator, except that no error occurs in the case of incomparable types; the collation used is
the Unicode codepoint collation.</p>
<p class="subhead">Example</p>
<p>This example creates a map reflecting the contents of an input file, and then uses
it to perform a look-up.</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
<xsl:stylesheet ... xmlns:map="http://ns.saxonica.com/map">
<xsl:variable name="transaction-map" as="javatype:com.saxonica.functions.map.ImmutableMap"
xmlns:javatype="http://saxon.sf.net/java-type">
<xsl:param name="transactions" as="element(transaction)*"/>
<xsl:iterate select="doc('transactions.xml')/*/transaction">
<xsl:param name="map" select="map:new()"/>
<xsl:next-iteration>
<xsl:with-param name="map" select="map:put($map, @date, @value)"/>
</xsl:next-iteration>
<xsl:on-completion>
<xsl:sequence select="$map"/>
</xsl:on-completion>
</xsl:iterate>
</xsl:variable>
<xsl:variable name="latest-transaction" select="map:get($transaction-map, string(current-date()))"/>
</xsl:stylesheet> </code>
</pre>
</div>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="instructions.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
