Add cross-references to map:build

michaelhkay · Nov 9, 2024 · 9da7d5b · 9da7d5b
1 parent 72a15a9
commit 9da7d5b
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 6 deletions.
diff --git a/specifications/xquery-40/src/expressions.xml b/specifications/xquery-40/src/expressions.xml
@@ -18325,6 +18325,12 @@ return $product/@code</eg>
                <p>Note however that the <code>fn:collation-key</code> function might not work
                   for all collations.</p>
             </note>
+
+            <note>
+            <p>Grouping can also be achieved by constructing a map. For example, 
+            the function call <code>map:build(//employee, fn{department})</code> constructs a map
+            in which employees are grouped by department.</p>
+         </note>
          </div3>
          <div3 id="id-order-by-clause" role="xquery">
             <head>Order By Clause</head>
@@ -19136,7 +19142,7 @@ processing with JSON processing.</p>
                   </change>
                </changes>
 
-               <p>A Map is created using a <nt def="MapConstructor">MapConstructor</nt>.</p>
+               <p>A map can be created using a <nt def="MapConstructor">MapConstructor</nt>.</p>
 
                <scrap>
                   <head/>
@@ -19251,9 +19257,8 @@ processing with JSON processing.</p>
 
     </p>
 
-
-
-               <p>Example:</p>
+      <example>
+         <head>Constructing a fixed map</head>
 
                <p>The following expression constructs a map with seven entries:</p>
                <eg id="map-weekdays"><![CDATA[
@@ -19267,7 +19272,10 @@ processing with JSON processing.</p>
   "Sa" : "Saturday"
 }]]></eg>
 
-
+      </example>
+      <example>
+         <head>Constructing nested maps</head>
+
 
                <p>Maps can nest, and can contain any XDM value. Here is an example of a nested map with values that can be string values, numeric values, or arrays:</p>
 
@@ -19303,7 +19311,34 @@ processing with JSON processing.</p>
                and <code>null</code>, and backslash-escaped characters such as <code>"\n"</code>
                in string literals. In an &language; map constructor, of course, any literal 
                value can be replaced with an expression.</p></note>
-
+      </example>
+
+               <p>Both the keys and the values in a map constructor can be supplied as expressions
+               rather than as constants; the number of entries in the map, however, is fixed.
+               There are several functions that can be used to construct maps with a variable
+               number of entries:</p>
+
+               <ulist>
+                  <item><p><function>map:build</function> takes any sequence as input, and for each
+                  item in the sequence, it computes a key and a value, by calling user-supplied functions.</p></item>
+                  <item><p><function>map:merge</function> takes a sequence of maps (often but not necessarily
+                  single-entry maps) and merges them into a single map.</p></item>
+                  <item><p><function>map:of-pairs</function> takes a sequence of 
+                     <xtermref spec="FO40" ref="dt-key-value-pair-map">key-value pair maps</xtermref>
+                     and merges them into a single map.</p></item>
+               </ulist>
+
+               <p>Any of these functions can be used to build an index of employee
+                  elements using the value of the <code>@id</code> attribute as a key:</p>
+               <ulist>
+                  <item><p><code>map:build(//employee, fn{@id})</code></p></item>
+                  <item><p><code>map:merge(//employee ! {@id, .})</code></p></item>
+                  <item><p><code>map:of-pairs(//employee ! {'key':@id, 'value':.})</code></p></item>
+               </ulist>
+
+               <p>All three functions also provide control over how duplicate keys are handled,
+               allowing them to be used to create a map in which items are grouped according
+               to the value of a grouping key.</p>
 
             </div4>
             <div4 id="id-map-lookup">

diff --git a/specifications/xslt-40/src/xslt.xml b/specifications/xslt-40/src/xslt.xml
@@ -23384,6 +23384,12 @@ return if ($i le count($S))
             from among the distinct groups selected, further sub-grouping of distinct items in the
             current group can be done. </p>
          <p>It is also possible for one item to participate in more than one group.</p>
+
+         <note>
+            <p>Grouping can also be achieved by constructing a map. For example, 
+            the function call <code>map:build(//employee, fn{department})</code> constructs a map
+            in which employees are grouped by department.</p>
+         </note>
 
          <div2 id="xsl-for-each-group">
             <head>The <code>xsl:for-each-group</code> Element</head>