Merge pull request #1087 from michaelhkay/1086-array-values

1086 Editorial changes to array:values
qt4cg · Apr 30, 2024 · 22339f0 · 22339f0
2 parents 3e9fea2 + 95dce8a
commit 22339f0
Showing 1 changed file with 24 additions and 6 deletions.
diff --git a/specifications/xpath-functions-40/src/function-catalog.xml b/specifications/xpath-functions-40/src/function-catalog.xml
@@ -27219,20 +27219,38 @@ declare function flatten(
          <fos:property>focus-independent</fos:property>
       </fos:properties>
       <fos:summary>
-         <p>Returns a sequence with the members of an array.</p>
+         <p>Returns the sequence-concatenation of the members of an array.</p>
       </fos:summary>
       <fos:rules>
-         <p>The function concatenates the members of <code>$array</code> and returns them as
-           a sequence. The values are returned in their original order.
-           Arrays contained within members are returned unchanged.</p>
-         <p>The effect of the function is equivalent to <code>$array?*</code>.</p>
+         <p>The function returns the sequence-concatenation of the members of 
+            <code>$array</code>, retaining order.</p>
+         <p>More formally, it returns the result of <code>array:members($array)?value</code>.</p>
+
       </fos:rules>
+      <fos:notes>
+         <p>Unlike <code>array:flatten</code>, the function does not apply recursively
+         to nested arrays.</p>
+         <p>If <code>$A</code> is a single array item, then <code>array:values($A)</code>
+         returns the same result as <code>$A?*</code>.</p>
+      </fos:notes>
       <fos:examples>
          <fos:example>
             <fos:test>
-               <fos:expression>array:values(array { "one", "two", "three" })</fos:expression>
+               <fos:expression>array:values(["one", "two", "three"])</fos:expression>
+               <fos:result>("one", "two", "three")</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>array:values(["one", ("two", "three")])</fos:expression>
                <fos:result>("one", "two", "three")</fos:result>
             </fos:test>
+            <fos:test>
+               <fos:expression>array:values(["one", ("two", "three"), ()])</fos:expression>
+               <fos:result>("one", "two", "three")</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>array:values(["one", ["two", "three"]])</fos:expression>
+               <fos:result>("one", ["two", "three"])</fos:result>
+            </fos:test>
             <fos:test>
                <fos:expression>array:values([ (), 1, (2 to 4), [ 5 ] ])</fos:expression>
                <fos:result>(1, 2, 3, 4, [ 5 ])</fos:result>