150bis revised proposal for fn:ranks

specifications/xpath-functions-40/src/function-catalog.xml

@@ -19783,7 +19783,7 @@ else let $rel = op:simple-compare(head($a), head($b), $C)
      return if ($rel eq 0)
             then op:lexicographic-compare(tail($a), tail($b), $C)
             else $rel</eg></item>
-                  <item><p>Here <code>op:simple-compare($k1, $k2)</code> is defined as follows:</p>
+                  <item><p>Here <code>op:simple-compare($k1, $k2, $C)</code> is defined as follows:</p>
                      <eg>if ($k1 instance of union(xs:string, xs:anyURI, xs:untypedAtomic)
     and $k2 instance of union(xs:string, xs:anyURI, xs:untypedAtomic))
 then compare($k1, $k2, $C)
@@ -30215,6 +30215,160 @@ path with an explicit <code>file:</code> scheme.</p>
          <fos:version version="4.0">Proposed for 4.0</fos:version>
       </fos:history>
    </fos:function>
+
+   <fos:function name="ranks" prefix="fn">
+       <fos:signatures>
+         <fos:proto name="ranks" return-type="array(item())*"> 
+            <fos:arg name="input" type="item()*" usage="navigation"/>
+            <fos:arg name="collations" type="xs:string*" usage="absorption" default="fn:default-collation()"/>
+            <fos:arg name="keys" type="(function(item()) as xs:anyAtomicType*)*" usage="inspection" default="fn:data#1"/>
+            <fos:arg name="orders" type="enum('ascending', 'descending')*" usage="absorption" default="'ascending'"/>
+         </fos:proto>        
+       </fos:signatures> 
+      <fos:properties>
+         <fos:property>deterministic</fos:property>
+         <fos:property>context-independent</fos:property>
+         <fos:property>focus-independent</fos:property>
+      </fos:properties>   
+      <fos:summary>
+        <p>Sorts the items of a supplied sequence based on the value of one or more sort keys, 
+        grouping the results so that items with the same key appear together 
+        as members of the same array, ordered by increasing key value.
+        </p>
+      </fos:summary>  
+      <fos:rules>
+         <p>The effect of the function is equivalent to first sorting the input
+            sequence by applying the <code>fn:sort</code> function with the same
+            arguments, and then partitioning the result into a sequence of arrays
+            so that adjacent items with the same sort key go into the same array.</p>
+
+         <p>That is, the result of the function is given by the expression:</p>
+
+         <eg>sort($input, $collations, $keys, $orders) =>
+   partition(split-when := fn($group, $item) {
+      not(op:same-sort-keys(foot($group), 
+                            $item, 
+                            $collations, 
+                            $keys))})</eg>
+
+         <p>where <code>op:same-sort-keys($item1, $item2, $collations, $keys)</code> is a function
+            that returns true if and only if the first two arguments have pairwise equal sort
+            key values as defined in the rules of the <code>fn:sort</code> function.</p>
+
+      </fos:rules>
+
+      <fos:errors>
+         <p>The errors that may be raised are the same as for <code>fn:sort</code>.</p>
+      </fos:errors>
+      <fos:examples>
+         <fos:example>
+            <fos:test>
+               <fos:expression><eg>ranks(("red", "orange", "yellow", "green", "blue", "indigo", "violet"),
+   (), string-length#1)</eg></fos:expression>
+               <fos:result>["red"], ["blue"], ["green"], ["orange", "yellow", "indigo", "violet"]</fos:result>
+            </fos:test>
+         </fos:example>
+         <fos:example>
+            <fos:test>
+               <fos:expression><eg>ranks((3, 2, 4), (), fn($n) {$n mod 2})</eg></fos:expression>
+               <fos:result>[2, 4], [3]</fos:result>
+            </fos:test>
+         </fos:example>       
+         <fos:example>
+         <fos:test>
+               <fos:expression><eg>ranks((-2, -1, 0, 1, 2, 3), (), fn($n) {$n * $n})</eg></fos:expression>
+               <fos:result>[0], [-1, 1], [-2, 2], [3]</fos:result>
+            </fos:test>
+         </fos:example>      
+         <fos:example>
+            <fos:test>
+               <fos:expression><eg><![CDATA[
+let $group := map {
+  "Argentina" : (2, 0, 1),
+  "Poland" : (1, 1, 1),
+  "Mexico" : (1, 1, 1),
+  "Saudi Arabia" : (1, 0, 2)
+}
+return ranks(map:keys($group), 
+             (),
+             fn($team){3 * $group($team)[1] + $group($team)[2]}, 
+             "descending")) ]]></eg>
+               </fos:expression>
+               <fos:result>["Argentina"], ["Poland", "Mexico"], ["Saudi Arabia"]</fos:result>
+            </fos:test>
+         </fos:example>       
+ <!--        <fos:example>
+            <fos:test>
+               <fos:expression><eg><![CDATA[
+ $toSwedish := map{
+   "good" : "Bra",
+   "difficult" : "svår",
+   "great" : "Bra",
+   "severe": "svår",
+   "fine": "Bra"
+ }
+ return
+   ranks(("good", "difficult", "great", "severe", "fine", "good"), ()
+         fn($word){$toSwedish($word)}, true(), default-collation(), 
+                   "http://www.w3.org/2013/collation/UCA?lang=se") ]]></eg>
+               </fos:expression>
+               <fos:result>["good","great","fine"], ["difficult","severe"]</fos:result>
+            </fos:test>
+         </fos:example>       
+         <fos:example>
+            <fos:test>
+               <fos:expression><eg><![CDATA[
+ $toSwedish := map{
+   "good" : "Bra",
+   "difficult" : "svår",
+   "great" : "Bra",
+   "severe": "svår",
+   "fine": "Bra"
+ }
+ return
+   ranks(("good", "difficult", "great", "severe", "fine", "good"), 
+         fn($word){$toSwedish($word)}, false(), default-collation(), 
+                   "http://www.w3.org/2013/collation/UCA?lang=se") ]]></eg>
+               </fos:expression>
+               <fos:result>["good","great","fine","good"], ["difficult","severe"]</fos:result>
+            </fos:test>
+         </fos:example> -->
+         <fos:example>
+            <fos:test>
+               <fos:expression><eg><![CDATA[
+let $decompose := fn($s as xs:string) {
+  let $chars := characters($s)[. ne ' '],
+      $frequencies := map:build($chars, value:=fn{1}, combine:=op('+'))
+                      => map:pairs()
+                      => sort((), fn{?key})
+  return string-join($frequencies ! (?key, ?value), '')      
+}
+return
+   ranks (("apple macintosh", "astronomer", 
+             "angered", "brush", "dictionary", 
+             "dirty room", "editor", 
+             "enraged", "eleven plus two",  
+             "indicatory", "laptop machines", 
+             "redo it", "dormitory", "shrub", 
+             "moon starer", "twelve plus one"),
+          keys := $decompose ) ]]></eg>               
+               </fos:expression>
+               <fos:result>["astronomer", "moon starer"], 
+["apple macintosh", "laptop machines"],
+["editor", "redo it"],
+["dirty room", "dormitory"],
+["eleven plus two", "twelve plus one"],
+["dictionary", "indicatory"],
+["angered", "enraged"],
+["brush", "shrub"]
+</fos:result>
+            </fos:test>            
+         </fos:example>        
+      </fos:examples>       
+      <fos:history>
+         <fos:version version="4.0">Proposed for 4.0</fos:version>
+      </fos:history>
+   </fos:function>
 
    <fos:function name="scan-left" prefix="fn">
        <fos:signatures>

specifications/xpath-functions-40/src/xpath-functions.xml

@@ -7571,6 +7571,9 @@ return <table>
             <div3 id="func-partition" diff="add" at="A">
                <head><?function fn:partition?></head>
             </div3>
+            <div3 id="func-ranks" diff="add" at="A">
+               <head><?function fn:ranks?></head>
+            </div3>
             <div3 id="func-scan-left" diff="add" at="A">
                <head><?function fn:scan-left?></head>
             </div3>
@@ -11886,6 +11889,7 @@ ISBN 0 521 77752 6.</bibl>
               <item><p><code>fn:parse-QName</code></p></item>
               <item><p><code>fn:parse-uri</code></p></item>
               <item><p><code>fn:partition</code></p></item>
+              <item><p><code>fn:ranks</code></p></item>
               <item><p><code>fn:replicate</code></p></item>
               <item><p><code>fn:scan-left</code></p></item>
               <item><p><code>fn:scan-right</code></p></item>