Skip to content

Commit

Permalink
Resubmission of the PR for adding the BLAKE 3 hashing algorithm
Browse files Browse the repository at this point in the history
  • Loading branch information
@dnovatchev
dnovatchev committed May 19, 2024
1 parent dfbdbee commit 44ad3af
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 200 deletions.
213 changes: 17 additions & 196 deletions specifications/xpath-functions-40/src/function-catalog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5162,15 +5162,18 @@ return normalize-unicode(concat($v1, $v2))</eg>
the value through <code>fn:upper-case(fn:normalize-space())</code>. </p>
<p>Conforming implementations <rfc2119>must</rfc2119> support the following
options and the functions referred to by them:</p>
<ulist>
<ulist>
<item><p><code>MD5</code>: the MD5 Message-Digest algorithm defined by <bibref
ref="rfc6151"/> (update to <bibref ref="rfc1321"/>).</p></item>
<item><p><code>SHA-1</code>: the <code>SHA-1</code> algorithm, defined by <bibref
<item><p><code>BLAKE3</code>: the <code>BLAKE3</code> algorithm defined by <bibref
ref="BLAKE3"/>.</p></item>
<item><p><code>CRC-32</code>: the <code>CRC-32</code> algorithm, defined by <bibref
ref="ieee802-3"/>. </p></item>
<item><p><code>SHA-1</code>: the <code>SHA-1</code> algorithm, defined by <bibref
ref="fips180-4"/>. </p></item>
<item><p><code>SHA-256</code>: the <code>SHA-256</code> algorithm, defined by <bibref
ref="fips180-4"/>. </p></item>
<item><p><code>CRC-32</code>: the <code>CRC-32</code> algorithm, defined by <bibref
ref="ieee802-3"/>. </p></item>

</ulist>
<p>Conforming implementations <rfc2119>may</rfc2119> support other checksum and
hash functions with implementation-defined semantics.</p>
Expand Down Expand Up @@ -5221,6 +5224,16 @@ return normalize-unicode(concat($v1, $v2))</eg>
=> string()</eg></fos:expression>
<fos:result>"3C01BDBB26F358BAB27F267924AA2C9A03FCFDB8"</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg>hash("ABC", { "algorithm": "BLAKE3" })
=> string() => lower-case()</eg></fos:expression>
<fos:result>"d1717274597cf0289694f75d96d444b992a096f1afd8e7bbfa6ebb1d360fedfc"</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg>hash("ABC", { "algorithm": "BLAKE3" })
=> xs:base64Binary() => string()</eg></fos:expression>
<fos:result>"0XFydFl88CiWlPddltREuZKglvGv2Oe7+m67HTYP7fw="</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg>hash("ABC", { "algorithm": "sha-256" })
=> string()</eg></fos:expression>
Expand Down Expand Up @@ -31054,198 +31067,6 @@ 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" pefix="fn">
<fos:signatures>
<fos:proto name="ranks" return-type="array(item())*">
<fos:arg name="input" type="item()*" usage ="navigation"/>
<fos:arg name="key" type="function(item()) as xs:anyAtomicType*" usage="inspection" default="fn:data#1"/>
<fos:arg name="distinct-ranks" type="xs:boolean" usage="navigation" default="true()"/>
<fos:arg name="collation-input" type="xs:string?" usage="absorption" default="fn:default-collation()"/>
<fos:arg name="collation-keys" type="xs:string?" usage="absorption" default="fn:default-collation()"/>
</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 a sort key function,
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 items from <code>$input</code> are sorted
by the results of applying the <code>$key</code> function on each of them,
and then for each of the sorted key-values (in increasing sort-order) an array is produced,
containing all <code>$input</code> items having that same key-value, that are distinct
if the value of the <code>$distinct-ranks</code> argument is specified as <code>true()</code>.
Each such result-array contains its members ordered in the same way as they appear
in <code>$input</code>

More formally, the function is equivalent to the following implementation in XPath (return clause added in comments for completeness):</p>
<eg><![CDATA[let $ranks := function(
$input as item()*,
$key as function(item()) as xs:anyAtomicType*,
$distinct-ranks as xs:boolean,
$collation-input as xs:string?,
$collation-keys as xs:string?
) as array(item())*
{
let $make-distinct := ( (distinct-values#2)[$distinct-ranks], fn($x, $y){$x} )[1],
$compare-keys := fn($k1, $k2, $collation-keys) {deep-equal($k1, $k2, $collation-keys)}
return
for $v in sort(distinct-values($input ! $key(.), $collation-keys), $collation-keys)
return
array{$make-distinct($input[$compare-keys($key(.), $v, $collation-keys)],
$collation-input)}
}
(:
return $ranks($input, $key, $distinct-ranks, $collation-input, $collation-keys)
:)
]]></eg>
</fos:rules>
<fos:notes>
<olist>
<item><p>The arguments <code>$collation-input</code> and <code>$collation-keys</code> will be used in cases
when, respectively, the values of <code>$input</code> and <code>$key($inputValue)</code> are strings.
These collation arguments have default values, thus in most cases it would not be necessary
to specify collations on the function call.
</p></item>
<item>
<p>The argument <code>$distinct-ranks</code> has a default of <code>true()</code> and only
needs to be specified if the caller wants ranks to contain any duplicate items.
</p>
</item>
<item>
<p>Note that each result is placed in a separate array.
This is necessary because we cannot represent a sequence of results, some or all of which are
a sequence - that is "sequence of sequences" as just a single sequence.
</p>
</item>
</olist>
</fos:notes>
<fos:errors>
<p>If the set of computed keys contains <code>xs:untypedAtomic</code> values that are not
castable to <code>xs:double</code> then
operation will fail with a dynamic error (<xerrorref
spec="FO" class="RG" code="0001"/>).
</p>
<p>If the set of computed keys contains values that are not comparable using
the <code>lt</code> operator then the sort
operation will fail with a type error (<xerrorref
spec="XP" class="TY" code="0004"/>).
</p>
</fos:errors>
<fos:examples>
<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
reverse(ranks($Group => map:keys(),
fn($team){3 * $Group($team)[1] + $Group($team)[2]})) ]]></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 := string-to-codepoints($s) ! codepoints-to-string#1(.),
$freqs := fold-left($chars, map{},
fn($m as map(*), $c as xs:string)
{
if(not($m($c))) then $m => map:put($c, 1)
else $m => map:put($c, $m($c) +1)
}
)
return
string-join((for $k in sort($freqs => map:keys()),
$kv in $k || $freqs($k)
return $kv),
'')
}
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"),
fn($word){$decompose($word)} ) ]]></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>
Expand Down
8 changes: 4 additions & 4 deletions specifications/xpath-functions-40/src/xpath-functions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7483,9 +7483,6 @@ 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>
Expand Down Expand Up @@ -11045,6 +11042,10 @@ currently, Version 9.0.0.
<div2 id="non-normative-biblio">
<head>Non-normative references</head>
<blist>
<bibl id="BLAKE3" key="BLAKE3 Hashing">
<emph>Blake3 Algorithm Specification</emph>. Available at:
<loc href="https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf">https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf</loc>
</bibl>
<bibl id="CALCALC"
key="Calendrical Calculations">Edward M. Reingold and Nachum Dershowitz.
<emph>Calendrical Calculations Millennium edition (2nd Edition)</emph>. Cambridge University Press,
Expand Down Expand Up @@ -11833,7 +11834,6 @@ 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>
Expand Down

0 comments on commit 44ad3af

Please sign in to comment.