Skip to content

Commit

Permalink
Ordered Maps
Browse files Browse the repository at this point in the history
  • Loading branch information
@michaelhkay
michaelhkay committed Nov 25, 2024
1 parent 7604122 commit e9dca57
Show file tree
Hide file tree
Showing 7 changed files with 657 additions and 69 deletions.
68 changes: 60 additions & 8 deletions specifications/xpath-datamodel-40/src/xpath-datamodel.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1511,18 +1511,36 @@ must equal the function’s arity.
<changes>
<change issue="1335" date="2024-07-20">Constructors are added, and the single accessor function
is now an iterator over the key/value pairs in the map.</change>
<change issue="564" date="2024-11-25">Ordered maps are introduced.</change>
</changes>

<p><termdef term="map item" id="dt-map-item">A <term>map item</term>
is a value that represents a map (in other languages this is sometimes
called a hash, dictionary, or associative array).</termdef>
A map is logically a collection of
A map is logically a sequence of
key/value pairs. Each key in the map is unique (there is no other key
to which it is equal) and has associated with it a value that is a sequence
of zero or more items. There is no uniqueness constraint on
values. The semantics of equality are described in
values, only on keys. The semantics of equality when comparing keys are described in
<xspecref spec="FO40" ref="func-atomic-equal"/>.</p>

<p><termdef term="ordering" id="dt-map-ordering">A <termref def="dt-map-item"/> has
a property called its <term>ordering</term>, which takes one of the three values
<code>random</code>, <code>sorted</code>, or <code>fifo</code>.</termdef></p>

<ulist>
<item><p><term>Random</term> ordering means that the order of entries
in the map is <termref def="dt-implementation-dependent"/>.</p></item>
<item><p><term>Sorted</term> ordering means that the keys in the map
are considered to be sorted, and entries are retrieved in order of their keys.</p></item>
<item><p><term>Fifo</term> (first-in, first-out) order means that the map
maintains an ordering of entries based on the order in which entries were added,
with new entries being added at the end, after existing entries.</p></item>
</ulist>

<p><termdef id="dt-entry-order" term="entry order">The order of entries in a map
(which is dependent on its <termref def="dt-map-ordering">ordering</termref>
property) is referred to as <term>entry order</term>.</termdef></p>


<note>
Expand All @@ -1538,13 +1556,20 @@ values. The semantics of equality are described in
<div4 id="dm-empty-map">
<head><code>empty-map</code> Constructor</head>
<example role="signature">
<proto class="dm" name="empty-map" return-type="map(*)" returnSeq="no"/>
<proto class="dm" name="empty-map" return-type="map(*)" returnSeq="no">
<arg name="ordering" type="enum('random', 'sorted', 'fifo')"/>
</proto>
</example>

<p>The <code>dm:empty-map</code> constructor returns a map containing no key/value pairs.</p>

<p>The function is exposed in XPath as an empty map constructor, which may be written <code>{}</code>
or <code>map {}</code>.</p>
<p>The <termref def="dt-map-ordering">ordering</termref> property of the map is based on the
value of the <code>$ordering</code> argument.</p>

<p>In XPath an empty map constructor, written as <code>{}</code>
or <code>map {}</code>, creates a map with <code>ordering=random</code>. An empty map with
ordering <code>sorted</code> or <code>fifo</code> can be constructed using functions such as
<code>map:build</code>, <code>map:merge</code>, or <code>map:of-pairs</code>.</p>
</div4>

<div4 id="dm-map-put">
Expand All @@ -1565,6 +1590,32 @@ values. The semantics of equality are described in
<item><p>One key/value pair whose key is <code>$key</code> and whose associated value is <code>$value</code>.</p></item>
</ulist>

<p>The <termref def="dt-map-ordering">ordering</termref> property of the returned map is the same
as the <termref def="dt-map-ordering">ordering</termref> of the supplied <code>$map</code>.</p>

<p>The detailed effect of the function depends on the ordering property, as follows:</p>

<ulist>
<item><p>If the ordering is <code>random</code>, the order of entries in the returned
map is <termref def="dt-implementation-dependent"/>, and bears no necessary relationship
to the ordering of entries in the supplied <code>$map</code>.</p></item>
<item><p>If the ordering is <code>sorted</code>, the key of the new entry must be
<termref def="dt-strictly-comparable"/> with the keys of existing entries (a dynamic error occurs if this is not
the case), and the ordering of entries in the returned map is such that an entry with key <var>K1</var>
precedes an entry with key <var>K2</var> if and only
if <code>fn:compare(<var>K1</var>, <var>K2</var>, $CC) lt 0</code>,
where <code>$CC</code> is the Unicode codepoint collation.</p>
<p><termdef id="dt-strictly-comparable" term="strictly comparable">Two atomic items
<var>K1</var> and <var>K2</var> are <term>strictly comparable</term> if
(a) the function call <code>fn:compare(<var>K1</var>, <var>K2</var>, $CC)</code> (where <code>$CC</code>
is the Unicode codepoint collation) does not fail with a type error, and (b) if one of the values
has a timezone component, then the other also has a timezone component.</termdef></p></item>
<item><p>If the ordering is <code>fifo</code>, then the order of entries in the returned
map reflects the order of entries in the supplied <code>$map</code>. If the key of
the new entry was present in <code>$map</code> then the new entry replaces that entry retaining
its current position; otherwise, the new entry is added after all existing entries.</p></item>
</ulist>

<p>The function is exposed in XPath through the function <code>map:put</code>.</p>
</div4>

Expand All @@ -1578,9 +1629,10 @@ values. The semantics of equality are described in
</proto>
</example>

<p>The <function>dm:iterate-map</function> accessor calls the supplied <code>$action</code>
function once for each key/value pair in <code>$map</code>, in implementation-dependent order,
and returns the sequence concenation of the results.</p>
<p>The <code>dm:iterate-map</code> accessor calls the supplied <code>$action</code>
function once for each key/value pair in <code>$map</code>, in order,
and returns the sequence concenation of the results. The order in which entries
are processed reflects the <termref def="dt-map-ordering"/> property of the map.</p>

<p>The function is exposed in XPath most directly through the function <code>map:for-each</code>, but
it also underpins all other functions giving access to maps, such as <code>map:size</code>,
Expand Down
Loading

0 comments on commit e9dca57

Please sign in to comment.