Skip to content

Commit

Permalink
Merge branch 'master' into 1659-option-conventions-sequences-as-arrays
Browse files Browse the repository at this point in the history
  • Loading branch information
@michaelhkay
michaelhkay authored Dec 19, 2024
2 parents df8be39 + 88241c6 commit b62ed65
Show file tree
Hide file tree
Showing 6 changed files with 1,167 additions and 870 deletions.
853 changes: 487 additions & 366 deletions specifications/xpath-functions-40/src/function-catalog.xml
View file

Large diffs are not rendered by default.

528 changes: 263 additions & 265 deletions specifications/xpath-functions-40/src/xpath-functions.xml
View file

Large diffs are not rendered by default.

372 changes: 198 additions & 174 deletions specifications/xquery-40/src/expressions.xml
View file

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions specifications/xquery-40/src/query-prolog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,8 +238,8 @@
overriding any implementation-defined default.</termdef> The default collation is the
collation that is used by functions and operators that require a collation if no other
collation is specified. For example, the <code>gt</code> operator on strings is defined by a
call to the <code>fn:compare</code> function, which takes an optional collation parameter.
Since the <code>gt</code> operator does not specify a collation, the <code>fn:compare</code>
call to the <function>fn:compare</function> function, which takes an optional collation parameter.
Since the <code>gt</code> operator does not specify a collation, the <function>fn:compare</function>
function implements <code>gt</code> by using the default collation.</p>
<p>If neither the implementation nor the Prolog specifies a default collation, the Unicode
codepoint collation (<code>http://www.w3.org/2005/xpath-functions/collation/codepoint</code>)
Expand Down Expand Up @@ -269,7 +269,7 @@
resolving relative URI references.</termdef> For example, the <termref
def="dt-static-base-uri">Static Base URI</termref> property is used when resolving relative
references for <termref def="dt-module-import">module import</termref> and for the
<code>fn:doc</code> function.</p>
<function>fn:doc</function> function.</p>

<note>
<p>As discussed in the definition of <termref def="dt-static-base-uri">Static Base
Expand Down Expand Up @@ -1140,7 +1140,7 @@ return $node/xx:bing]]>
<code>eg:sequential</code>.
If the namespace URI of an annotation is not recognized by the
implementation, then the annotation has no effect, other than being available for inspection
using the <code>fn:function-annotations</code> function.</p>
using the <function>fn:function-annotations</function> function.</p>
<p>Implementations may also provide
a way for users to define their own annotations.
Implementations must not define annotations, or allow users to define annotations, in
Expand Down
227 changes: 181 additions & 46 deletions specifications/xslt-40/src/function-catalog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1161,10 +1161,11 @@
<fos:property>context-dependent</fos:property>
</fos:properties>
<fos:summary>
<p>Returns the nodes that match a supplied key value.</p>
<p>Returns the nodes within a document or subtree that match a supplied key value.</p>
</fos:summary>
<fos:rules>
<p>The <function>key</function> function does for keys what the <xfunction>element-with-id</xfunction> function does for IDs.</p>
<p>The <function>key</function> function returns the nodes within a document or subtree that
have a specified key value.</p>
<p>The <code>$key-name</code> argument specifies the name of the <termref def="dt-key">key</termref>.
The value of the argument <rfc2119>must</rfc2119> be <phrase diff="add" at="2022-01-01">either an <code>xs:QName</code>, or </phrase>
a string containing an <termref def="dt-eqname"/>. If it is
Expand All @@ -1185,11 +1186,10 @@
the function is a sequence of nodes, in document order and with duplicates
removed, comprising those nodes in the selected subtree (see below) that are
matched by an <elcode>xsl:key</elcode> declaration whose name is the same as the
supplied key name, where the result of evaluating the <termref def="dt-key-specifier">key specifier</termref> contains a value that is equal
to one of these requested key values, under the rules appropriate to the XPath
<code>eq</code> operator for the two values in question, using the
<code>collation</code> attributes of the <elcode>xsl:key</elcode> declaration
when comparing strings. No error is reported if two values are encountered that
supplied key name, where the result of evaluating the
<termref def="dt-key-specifier">key specifier</termref> contains a value that is equal
to one of these requested key values: the rules for comparing two items
are given below. No error is reported if two values are encountered that
are not comparable; they are regarded for the purposes of this function as being
not equal. </p>
<p>If the second argument is an empty sequence, the result of the function will be an
Expand All @@ -1204,44 +1204,43 @@
(see below) that are matched by an <elcode>xsl:key</elcode> declaration whose name
is the same as the supplied key name, where the result of evaluating the <termref def="dt-key-specifier">key specifier</termref> is deep-equal to the requested
key value, under the rules appropriate to the <xfunction>deep-equal</xfunction>
function applied to the two values in question, using the <code>collation</code>
attributes of the <elcode>xsl:key</elcode> declaration when comparing strings.
Note that the <xfunction>deep-equal</xfunction> function reports no error if two
values are encountered that are not comparable; they are regarded for the purposes
of this function as being not equal.</p>
function applied to the two values in question: the detailed comparison rules are
defined below.</p>
<p>If the second argument is an empty sequence, the result of the
function will be the set of nodes having an empty sequence as the value of the key
specifier.</p>
</item>
</ulist>


<p>Different rules apply when <termref def="dt-xslt-10-behavior">XSLT 1.0 compatible behavior</termref> is enabled.</p>

<p>A key (that is, a set of <elcode>xsl:key</elcode>
declarations sharing the same key name) is processed in backwards compatible mode if (a)
at least one of the xsl:key elements in the definition of the key enables backwards
compatible behavior, and (b) the effective value of the <code>composite</code> attribute
is <code>no</code>.</p>

<p>When a key is processed in backwards compatible mode,
then:</p>

<ulist>

<item>
<p>The result of evaluating the key specifier in any <elcode>xsl:key</elcode>
declaration having this key name is converted after atomization to a sequence of
strings, by applying a cast to each item in the sequence.</p>
</item>

<item>
<p>When the first argument to the <function>key</function> function specifies this key
name, then the value of the second argument is converted after atomization to a
sequence of strings, by applying a cast to each item in the sequence. The values are
then compared as strings.</p>
</item>
</ulist>

<p>Two atomic items <var>K1</var> and <var>K2</var> are deemed equal if they satisfy
one of the following rules:</p>

<olist>
<item><p>If both <var>K1</var> and <var>K2</var> are of type
<code>xs:string</code>, <code>xs:untypedAtomic</code>,
or <code>xs:anyURI</code>, then they are deemed equal if
<code>compare(<var>K1</var>, <var>K2</var>, $collation)</code>
returns zero, where <code>$collation</code> is the collation of the key definition.</p></item>
<item><p>Otherwise, they are deemed equal if <code>atomic-equal(<var>K1</var>, <var>K2</var>)</code>
returns true.</p></item>
</olist>

<p>When <code>composite="yes"</code>, then two sequences of atomic
items <var>S1</var> and <var>S2</var> are deemed equal if <code>deep-equal(<var>S1</var>,
<var>S2</var>, {'items-equal': $F}))</code> returns true, where <code>$F</code> is the function
just described for comparing atomic items.</p>

<note>
<p>The rules for comparing items have changed in this version of the specification,
in the interests of bringing keys into line with maps. The main differences are:</p>
<ulist>
<item><p>Numeric equality is transitive. In particular, when comparing an <code>xs:double</code>
value to an <code>xs:decimal</code>, they must now be exactly numerically equal; the <code>xs:decimal</code>
was previously converted to the nearest <code>xs:double</code>.</p></item>
<item><p>The implicit timezone is no longer used when comparing date/time values with a timezone
to values without one. To be equal, the values must either both have a timezone, or both be without one.</p></item>
</ulist>
</note>


<p>The third argument is used to identify the selected subtree. If the argument is present,
Expand Down Expand Up @@ -1271,27 +1270,53 @@
<elcode>xsl:key</elcode> declaration is evaluated with a <termref def="dt-singleton-focus">singleton focus</termref> based on <var>$N</var>, the
<termref def="dt-atomization">atomized</termref> value of the resulting
sequence includes a value that compares equal to at least one item in the atomized
value of the sequence supplied as <code>$key-value</code>, under the rules of the
<code>eq</code> operator with the collation selected as described above.</p>
value of the sequence supplied as <code>$key-value</code>, using the equality
comparison defined above.</p>

<p>When <code>composite="yes"</code>, and the
<termref def="dt-key-specifier">key specifier</termref> of that
<elcode>xsl:key</elcode> declaration is evaluated with a <termref def="dt-singleton-focus">singleton focus</termref> based on <var>$N</var>, the
<termref def="dt-atomization">atomized</termref> value of the resulting
sequence compares equal to the atomized value of the sequence supplied as
<code>$key-value</code>, under the rules of the
<xfunction>deep-equal</xfunction> function with the collation selected as
described above.</p>
<xfunction>deep-equal</xfunction> function as described above.</p>
</item>
</ulist>
<p>The sequence returned by the <function>key</function> function will be in document
order, with duplicates (that is, nodes having the same identity) removed. </p>

<p>Different rules apply when <termref def="dt-xslt-10-behavior">XSLT 1.0 compatible behavior</termref> is enabled.</p>

<p>A key (that is, a set of <elcode>xsl:key</elcode>
declarations sharing the same key name) is processed in backwards compatible mode if (a)
at least one of the <elcode>xsl:key</elcode> elements in the definition of the key enables backwards
compatible behavior, and (b) the effective value of the <code>composite</code> attribute
is <code>no</code>.</p>

<p>When a key is processed in backwards compatible mode,
then:</p>

<ulist>

<item>
<p>The result of evaluating the key specifier in any <elcode>xsl:key</elcode>
declaration having this key name is converted after atomization to a sequence of
strings, by applying a cast to each item in the sequence.</p>
</item>

<item>
<p>When the first argument to the <function>key</function> function specifies this key
name, then the value of the second argument is converted after atomization to a
sequence of strings, by applying a cast to each item in the sequence. The values are
then compared as strings.</p>
</item>
</ulist>
</fos:rules>
<fos:errors>
<p>
<error spec="XT" type="dynamic" class="DE" code="1260">
<p>It is a <termref def="dt-dynamic-error"> dynamic error</termref> if the value
<error.extra>of the first argument to the <function>key</function>
function</error.extra> is not a valid QName, or if there is no namespace
of <code>$key-name</code> is not a valid QName, or if there is no namespace
declaration in scope for the prefix of the QName, or if the name obtained by
expanding the QName is not the same as the expanded name of any
<elcode>xsl:key</elcode> declaration in the containing <termref def="dt-package">package</termref>. If the
Expand Down Expand Up @@ -1419,8 +1444,118 @@
</fos:example>

</fos:examples>
<fos:changes>
<fos:change issue="1619" PR="1622" date="2024-11-29">
<p>The rules for equality comparison have changed to bring keys into line with maps.</p>
</fos:change>
</fos:changes>
</fos:function>

<fos:function name="map-for-key" prefix="fn">
<fos:signatures>
<fos:proto name="map-for-key" return-type="map(xs:anyAtomicType, node()*)">
<fos:arg name="key-name" type="(xs:string | xs:QName)"/>
<fos:arg name="top" type="(document-node() | element())" default="/" usage="navigation"/>
</fos:proto>
</fos:signatures>
<fos:properties>
<fos:property>deterministic</fos:property>
<fos:property>focus-independent</fos:property>
</fos:properties>
<fos:summary>
<p>Delivers the content of a key, for a specific document or subtree, as a map.</p>
</fos:summary>
<fos:rules>
<p>The effect of the function is to return a map <code>$M</code> such that
<code>map:get($M, $key)</code> returns the same result as <code>key($key-name, $key, $top)</code>.</p>
<p>The function is defined only for maps that satisfy the following constraints:</p>
<olist>
<item><p>The key's collation must be the Unicode Codepoint Collation.</p></item>
<item><p>The key must not specify <code>composite=yes</code>.</p></item>
</olist>

<p>The <code>$key-name</code> argument specifies the name of the <termref def="dt-key">key</termref>.
The value of the argument <rfc2119>must</rfc2119> be either an <code>xs:QName</code>, or
a string containing an <termref def="dt-eqname"/>. If it is
a <termref def="dt-lexical-qname">lexical QName</termref>, then it is expanded as
described in <specref ref="qname"/> (no prefix means no namespace).</p>

<p>The <code>$top</code> argument is used to identify the selected subtree. If the argument is present,
the selected subtree is the set of nodes that have <code>$top</code> as an
ancestor-or-self node. If the argument is omitted, the selected subtree is the document
containing the context node. This means that the third argument effectively defaults to
<code>/</code>.</p>

<p>The returned map contains one entry (<var>K</var>, <var>V</var>) for every atomic item <var>K</var>
where the result of <code>key($key-name, <var>K</var>, $top)</code> is not empty, with <var>V</var>
set to the result of <code>key($key-name, <var>K</var>, $top)</code>.</p>
</fos:rules>
<fos:errors>
<p>It is a <termref def="dt-dynamic-error"> dynamic error</termref> if the value
<error.extra>of the first argument to the <function>map-for-key</function>
function</error.extra> is not a valid QName, or if there is no namespace
declaration in scope for the prefix of the QName, or if the name obtained by
expanding the QName is not the same as the expanded name of any
<elcode>xsl:key</elcode> declaration in the containing <termref def="dt-package">package</termref>. If the
processor is able to detect the error statically (for example, when the argument
is supplied as a string literal), then the processor <rfc2119>may</rfc2119>
optionally raise this as a <termref def="dt-static-error">static
error</termref> <errorref class="DE" code="1260"/>.
</p>
<p>
<error spec="XT" type="dynamic" class="DE" code="1262">
<p>It is a <termref def="dt-dynamic-error">dynamic
error</termref> if the key identified in a call to the function <function>map-for-key</function>
is unsuitable because it uses a collation other than the Unicode Codepoint Collation, or because
it is defined with <code>composite=yes</code>.</p>
</error>
</p>
<p>
It is a <termref def="dt-dynamic-error">dynamic
error</termref> to call the <function>key</function> function with
two arguments if there is no <termref def="dt-context-node">context
node</termref>, or if the root of the tree containing the context node is not a
document node; or to call the function with three arguments if the root of the
tree containing the node supplied in the third argument is not a document
node <errorref class="DE" code="1270"/>.
</p>
</fos:errors>
<fos:notes>
<p>The function has two main uses:</p>
<ulist>
<item><p>It enables the key values present in a key to be enumerated.</p></item>
<item><p>It enables the keys for multiple documents to be combined into a single map, for example
by using <xfunction>map:merge</xfunction>.</p></item>
</ulist>
</fos:notes>
<fos:examples>
<fos:example>
<example>
<head>Finding keys that are present in one document but absent in another</head>
<p>This example uses a key identifying employees in an employee file by their social security
number.</p>
<p>The key might be defined like this:</p>
<eg><![CDATA[
<xsl:key name="emp-name-key"
match="employee"
use="SSN"/>
]]></eg>
<p>Given two documents <code>$doc1</code> and <code>$doc2</code>, the following expression
returns a map representing the employees who are present in the first document
but not the second:</p>
<eg><![CDATA[map-for-key('emp-name-key', $doc1)
=> map:remove(map-for-key('emp-name-key', $doc2) => map:keys())]]></eg>
</example>
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="1619" PR="1622" date="2024-11-29">
<p>New in 4.0.</p>
</fos:change>
</fos:changes>
</fos:function>


<fos:function name="character-map" prefix="fn">
<fos:signatures>
<fos:proto name="character-map" return-type="map(xs:string, xs:string)?">
Expand Down
Loading

0 comments on commit b62ed65

Please sign in to comment.