<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="expressions" page="xpath30maps" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Maps in XPath 3.0</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: Maps in XPath 3.0"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Maps in XPath 3.0</h1>
<p>The XSL Working Group has proposed extensions to XPath to handle maps. These extensions have not yet been accepted
into the XPath 3.0 working drafts, but they are implemented in Saxon 9.4.</p>
<p>A map is a new kind of XDM item (alongside nodes and atomic values). In fact, a map is a kind of function: you can think
of it as a function defined extensionally (by tabulating the value of the function for all possible arguments) rather than intensionally
(by means of an algorithm).</p>
<p>A map is a set of entries. Each entry is a key-value pair. The key is always an atomic value. The "value" is any XDM value: a sequence
of nodes, atomic values, functions, or maps.</p>
<p>Maps, like sequences, are immutable. When you add an entry to a map, you get a new map; the original is unchanged. Saxon provides
an efficient implementation of maps that achieves this without copying the whole map every time an entry is added.</p>
<p>Also like sequences, maps do not have an intrinsic type of their own, but rather have a type that can be inferred from what they
contain. A map conforms to the type <code>map(K, V)</code> if all the keys are of type K and all the values are of type V. For example
if the keys are all strings, and the values are all employee elements, then the map conforms to the type
<code>map(xs:string, element(employee))</code>.</p>
<p>There are several ways to create a map:</p>
<ul>
<li>
<p>If the number of entries is known, you can use the constructor syntax
<code>map { key := value; key := value; ... }</code>. Here the keys and values can be any "simple expression" (an expression not containing
a top-level comma). If the keys and values are all known statically, you might write: <code>map { "a" := 1; "e: := 2; "i" := 3;
"o" := 4; "u" := 5 }.</code> You can use this construct anywhere an XPath expression can be used, for example in the <code>select</code>
attribute of an <code>xsl:variable</code> element.</p>
</li>
<li>
<p>The function <code>map:new()</code> takes a number of maps as input, and combines them into a single map. This can be used
to construct a map where the number of entries is not known statically: for example
<code>for $i in 1 to 10 return map{$i := codepoints-to-string($i)}</code>.</p>
</li>
<li>
<p>A single-entry map can also be constructed using the function <code>map:entry($key, $value)</code></p>
</li>
</ul>
<p>Given a map <code>$M</code>, the value corresponding to a given key <code>$K</code> can be found either by invoking the map as
a function: <code>$M($K)</code>, or by calling <code>map:get($M, $K)</code>.</p>
<p>The full list of functions that operate on maps is as follows. The prefix <code>map</code> represents the namespace URI
<code>http://www.w3.org/2005/xpath-functions/map</code></p>
<ul>
<li>
<p>map:new($maps as map(*)) as map(*): takes a sequence of maps as input and combines them into a single map.</p>
</li>
<li>
<p>map:new($maps as map(*), $collation as xs:string
) as map(*): takes a sequence of maps as input and combines them into a single map, using the specified collation to
compare key values.</p>
</li>
<li>
<p>map:collation($map as map(*)) as xs:string: returns the collation of a map. </p>
</li>
<li>
<p>map:keys($map as map(*)) as xs:anyAtomicType*: returns the keys that are present in a map, in unpredictable order.</p>
</li>
<li>
<p>map:contains($map as map(*), $key as xs:anyAtomicType) as xs:boolean: returns true if the given key is present in the map.</p>
</li>
<li>
<p>map:get($map as map(*), $key as xs:anyAtomicType) as xs:item()*: returns the value associated with the given key if present,
or the empty sequence otherwise. Equivalent to calling <code>$map($key)</code>.</p>
</li>
<li>
<p>map:entry($key as xs:anyAtomicType, $value as item()*): creates a singleton map. Useful as an argument to <code>map:new()</code></p>
</li>
<li>
<p>map:remove($map as map(*), $key as xs:anyAtomicType) as map(*): removes an entry from a map (if it was present), returning
a new map; if not present, returns the existing map unchanged.</p>
</li>
</ul>
<table width="100%">
<tr>
<td>
<p align="right"/>
</td>
</tr>
</table>
</body>
</html>
