Changes

This [[Module Library|XQuery Module]] contains various small utility and helper functions. Please note that some of the  For all listed functions are used for internal query rewritings. They , equivalent expressions exist in standard XQuery, but code may be renamed better readable with function calls: <syntaxhighlight lang="xquery">(: standard XQuery :)let $result := if(exists($sequence)) then $sequence else ('default', 'values')return $result[last()] (: XQuery with functions of this module :)$sequence=> util:or moved (('default', 'values'))=> util:last()</syntaxhighlight> In addition, various query optimizations create calls to other modules in future versions of BaseXthe utility functions.

|Returns {{Code|$items}} if it is a non-empty sequence. Otherwise, returns {{Code|$default}}. The function is equivalent Equivalent to one of the following expressions:* <codesyntaxhighlight lang="xquery">if(exists($items)) then $items else $default</code>,(: Elvis operator :)* <code>$items ?: $default</codesyntaxhighlight> (see [[XQuery Extensions#Elvis Operator|Elvis Operator]] for more details)

{{Mark|Introduced with Version 9.45:}}

|{{Func|util:within|$items sequence as item()*, $min as xs:integer|xs:boolean}}<br/>{{Func|util:within|$items sequence as item()*, $min as xs:integer, $max as xs:integer|xs:boolean}}

|Checks if the specified {{Code|$itemssequence}} has at least {{Code|$min}} and, optionally, at most {{Code|$max}} resultsitems.Equivalent to:<syntaxhighlight lang="xquery">let $count := count($sequence)return $count >= $min and $count <= $max</syntaxhighlight>

* <code>util:within((1 to 1000000000)[. < 10], 53, 6)</code> returns {{Code|true}}.

|Returns the item from {{Code|$sequence}} at the specified {{Code|$position}}. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[$position]</codesyntaxhighlight>.

|Returns items from {{Code|$sequence}}, starting at position {{Code|$first}} and ending at {{Code|$last}}. Equivalent to :<codesyntaxhighlight lang="xquery">subsequence($sequence, $first, $last - $first + 1)</codesyntaxhighlight>.

|Returns last item of a {{Code|$sequence}}. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[last()]</codesyntaxhighlight>.

|Returns all items of a {{Code|$sequence}} except for the last one. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[position() < last()]</codesyntaxhighlight>.

|Returns nodes in ''distinct document order'': duplicate nodes will be removed, and the remaining nodes will be returned in [https://www.w3.org/TR/xquery-31/#dt-document-order document order]. All As results of path expression expressions are in brought distinct document orderbefore they are returned, so the function is equivalent to the expression :<codesyntaxhighlight lang="xquery">$nodes/self::node()</codesyntaxhighlight>.

|Returns the document nodes of the specified {{Code|$nodes}}. The function path expression <code>/abc</code> is equivalent internally represented as <code>util:root(.)/abc</code. Equivalent to the expression :<codesyntaxhighlight lang="xquery">$nodes ! /</codesyntaxhighlight>|} =Array and Map Functions= ==util:array-members== {{Mark|Introduced with Version 9.5.}} {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:array-members|$array as array(*)|array(*)*}}|-| '''Summary'''|Returns each member of an {{Code|$array}} as a new array. Equivalent to:<syntaxhighlight lang="xquery">for $a in 1 to array:size($array)return [ $array($a) ]</syntaxhighlight>|-| '''Examples'''|* Returns three elements with the member values as concatenated text node. The path expression <codesyntaxhighlight lang="xquery">let $array := [ (), 2, (3, 4) ]for $member in array:members($array)return element numbers { $member }</abcsyntaxhighlight>|} ==util:array-values== {{Mark|Introduced with Version 9.5.}} {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:array-values|$array as array(*)|item()*}}|-| '''Summary'''|Returns all members of an {{Code|$array}} as a sequence. Equivalent to:<syntaxhighlight lang="xquery">$array ? *</codesyntaxhighlight>is internally represented |-| '''Examples'''|* Returns the array members as two items:<syntaxhighlight lang="xquery">let $array := [ (), 2, [ 3, 4 ] ]return array:values($array)<code/syntaxhighlight>|} ==util:map-entries== {{Mark|Introduced with Version 9.5.}} {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:rootmap-entries|$map as map(*)|map(xs:string, item()*)*}}|-| '''Summary'''|Returns each entry of a {{Code|$map}} as a new map, each with a {{Code|key}} and {{Code|value}} entry.Equivalent to:<syntaxhighlight lang="xquery">map:for-each($map, function($key, $value) { map { "key": $key, "value": $value }})</abcsyntaxhighlight>|-| '''Examples'''|* Returns three elements named by the key of the map, and with the entries as concatenated text node.<syntaxhighlight lang="xquery">let $map := map { 'a': (), 'b': 2, 'c': [ 3, 4 ] }for $entry in map:entries($map)return element { $entry?key } { string-join($entry?value) }</codesyntaxhighlight>|} ==util:map-values== {{Mark|Introduced with Version 9.5.}}

|Evaluates {{Code|$input}} and returns the result {{Code|$count}} times. Unless {{Code|$multiple}} is enabled, the input expression is only evaluated once. The function call Equivalent expressions:<codesyntaxhighlight lang="xquery">util:replicate($input, $count, true())</code> is equivalent to <code>,(1 to $count) ! $input</codesyntaxhighlight>.

|Inserts the defined {{Code|$separator}} between the {{Code|$items}} of a sequence and returns the resulting sequence. The function is equivalent Equivalent to:<br/syntaxhighlight lang="xquery"><code>head($items), for $item in tail($items) return ($separator, $item)</codesyntaxhighlight>

|Returns all characters of a {{Code|$string}} as a sequence. Equivalent to :<codesyntaxhighlight lang="xquery">for $cp in string-to-codepoints($string) ! return codepoints-to-string(.$cp)</codesyntaxhighlight>.

* Added: [[#util:intersperse|util:intersperse]], [[#util:within|util:within]], [[#util:duplicates|util:duplicates]], [[#util:array-members|util:array-members]], [[#util:array-values|util:array-values]], [[#util:map-entries|util:map-entries]], [[#util:map-values|util:map-values]]