Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
no edit summary
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.
=Conventions=
|-
| '''Summary'''
|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)
|-
| '''Examples'''
|-
| '''Summary'''
|Checks if the specified {{Code|$sequence}} has at least {{Code|$min}} and, optionally, at most {{Code|$max}} items. Equivalent to :<codesyntaxhighlight lang="xquery">let $count := count($sequence) return $count >= $min and $count <= $max</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns the item from {{Code|$sequence}} at the specified {{Code|$position}}. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[$position]</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|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>.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns last item of a {{Code|$sequence}}. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[last()]</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns all items of a {{Code|$sequence}} except for the last one. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[position() < last()]</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|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>.
|}
==util:root==
{| width='100%'
|-
| '''Summary'''
|Returns the document nodes of the specified {{Code|$nodes}}. The function is equivalent to the expression <code>$nodes ! /</code>. The path expression <code>/abc</code>is internally represented as <code>util:root(.)/abc</code.Equivalent to:<syntaxhighlight lang="xquery">$nodes ! /</syntaxhighlight>
|}
|-
| '''Summary'''
|Returns each member of an {{Code|$array}} as a new array. Equivalent to: <codesyntaxhighlight lang="xquery">for $a in 1 to array:size($array) return [ $array($a) ]</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns all members of an {{Code|$array}} as a sequence. Equivalent to {{Code|:<syntaxhighlight lang="xquery">$array ? *?}}, but better composable and easier to read.</syntaxhighlight>
|-
| '''Examples'''
|-
| '''Summary'''
|Returns each entry of a {{Code|$map}} as a new map, each with a {{Code|key}} and {{Code|value}} entry. Equivalent to: <codesyntaxhighlight lang="xquery">map:for-each($map, function($key, $value) { map { "key": $key, "value": $value } })</codesyntaxhighlight>.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns all values of a {{Code|$map}} as a sequence. Equivalent to {{Code|:<syntaxhighlight lang="xquery">$map ? *?}}, but better composable and easier to read.</syntaxhighlight>
|-
| '''Examples'''
|-
| '''Summary'''
|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>.
|-
| '''Errors'''
|-
| '''Summary'''
|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>
|-
| '''Examples'''
|-
| '''Summary'''
|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>.
|-
| '''Examples'''
;Version 9.5
* 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]]
* Updated: [[#util:replicate|util:replicate]]: Third argument added.
