Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Introduced with Version 9.1:}}
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=
All functions and errors in this module and errors are assigned to the <code><nowiki>http://basex.org/modules/util</nowiki></code> namespace, which is statically bound to the {{Code|util}} prefix.<br/>
=FunctionsConditions=
==util:if==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:if|$codition condition as item()*, $then as item()*|item()*}}<br/>{{Func|util:if|$codition condition as item()*, $then as item()*, $else as item()*|item()*}}<br/>
|-
| '''Summary'''
|Alternative writing for the if/then/else expression. :* If the ''effective boolean value'' of {{Code|$condition yields false}} is true, the {{Code|$then}} branch will be evaluated.* Otherwise, and if no {{Code|$else}} branch will be evaluated. If no third argument is supplied, an empty sequence is will be returned.
|-
| '''Examples'''
|}
==util:or== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:or|$items as item()*, $default as item()*|item()*}}|-| '''Summary'''|Returns {{Code|$items}} if it is a non-empty sequence. Otherwise, returns {{Code|$default}}. Equivalent to the following expressions:<syntaxhighlight lang="xquery">if(exists($items)) then $items else $default,(: Elvis operator :)$items ?: $default</syntaxhighlight>|-| '''Examples'''|* <code>util:or(123, 456)</code> returns {{Code|123}}.* <code>util:or(1[. = 0], -1)</code> returns {{Code|-1}}.|} ==util:within== {{Mark|Introduced with Version 9.5:}} {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:within|$sequence as item()*, $min as xs:integer|xs:boolean}}<br/>{{Func|util:within|$sequence as item()*, $min as xs:integer, $max as xs:integer|xs:boolean}}|-| '''Summary'''|Checks if the specified {{Code|$sequence}} has at least {{Code|$min}} and, optionally, at most {{Code|$max}} items. Equivalent to:<syntaxhighlight lang="xquery">let $count := count($sequence)return $count >= $min and $count <= $max</syntaxhighlight>|-| '''Examples'''|* <code>util:within(('a', 'b', 'c'), 2)</code> returns {{Code|true}}.* <code>util:within((1 to 1000000000)[. < 10], 3, 6)</code> returns {{Code|true}}.|} =Positional Access= ==util:item== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:item|$sequence as item()*, $position as xs:double|item()?}}<br/>|-| '''Summary'''|Returns the item from {{Code|$sequence}} at the specified {{Code|$position}}. Equivalent to:<syntaxhighlight lang="xquery">$sequence[$position]</syntaxhighlight>|-| '''Examples'''|* <code>util:item(reverse(1 to 5), 1)</code> returns <code>5</code>.* <code>util:item(('a','b'), 0)</code> returns an empty sequence.|} ==util:range== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:range|$sequence as item()*, $first as xs:double, $last as xs:double|item()*}}<br/>|-| '''Summary'''|Returns items from {{Code|$sequence}}, starting atposition {{Code|$first}} and ending at {{Code|$last}}. Equivalent to:<syntaxhighlight lang="xquery">subsequence($sequence, $first, $last - $first + 1)</syntaxhighlight>|-| '''Examples'''|* <code>util:range(//item, 11, 20)</code> returns all path results from (if available) position 11 to 20.|} ==util:last== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:last|$sequence as item()*|item()?}}<br/>|-| '''Summary'''|Returns last item of a {{Code|$sequence}}. Equivalent to:<syntaxhighlight lang="xquery">$sequence[last()]</syntaxhighlight>|-| '''Examples'''|* <code>util:last(reverse(1 to 100))</code> returns <code>1</code>.|} ==util:init== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:init|$sequence as item()*|item()*}}<br/>|-| '''Summary'''|Returns all items of a {{Code|$sequence}} except for the last one. Equivalent to:<syntaxhighlight lang="xquery">$sequence[position() < last()]</syntaxhighlight>|-| '''Examples'''|* <code>util:init(1 to 4)</code> returns <code>1 2 3</code>.|} =Node Functions= ==util:ddo==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:item-atddo|$sequence nodes as itemnode()*, $position as xs:double|itemnode()?*}}<br/>
|-
| '''Summary'''
|Returns nodes in ''distinct document order'': duplicate nodes will be removed, and the item from remaining nodes will be returned in [https://www.w3.org/TR/xquery-31/#dt-document-order document order]. As results of path expressions are brought distinct document order before they are returned, the function is equivalent to:<syntaxhighlight lang="xquery">$nodes/self::node()</syntaxhighlight>|} ==util:root== {| width='100%'|-| width='120' | '''Signatures'''|{{CodeFunc|util:root|$sequencenodes as node()*|document-node()*}} at <br/>|-| '''Summary'''|Returns the document nodes of the specified {{Code|$positionnodes}}. The path expression <code>/abc</code> is internally represented as <code>util:root(.)/abc</code. Equivalent to :<codesyntaxhighlight lang="xquery">$nodes ! /</syntaxhighlight>|} =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($sequencearray)return [$positionarray($a) ]</codesyntaxhighlight>.
|-
| '''Examples'''
|
* Returns three elements with the member values as concatenated text node.<codesyntaxhighlight lang="xquery">utillet $array :item-at= [ (reverse), 2, (1 to 5)3, 14)</code> returns <code>5</code>.]* <code>utilfor $member in array:item-at(members('a','b'), 0$array)return element numbers { $member }</codesyntaxhighlight> returns an empty sequence.
|}
==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 ? *</syntaxhighlight>|-| '''Examples'''|* Returns the array members as two items:<syntaxhighlight lang="xquery">let $array := [ (), 2, [ 3, 4 ] ]return array:values($array)</syntaxhighlight>|} ==util:map-rangeentries== {{Mark|Introduced with Version 9.5.}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:itemmap-rangeentries|$sequence map as itemmap(*)*, $first as |map(xs:doublestring, $last as xs:double|item()*)*}}<br/>
|-
| '''Summary'''
|Returns items from each entry of a {{Code|$sequencemap}}as a new map, starting at position each with a {{Code|$firstkey}} and ending at {{Code|$lastvalue}}entry. Equivalent to :<codesyntaxhighlight lang="xquery">subsequencemap:for-each($sequencemap, function($firstkey, $last - value) { map { "key": $key, "value": $first + 1value }})</codesyntaxhighlight>.
|-
| '''Examples'''
|
* Returns three elements named by the key of the map, and with the entries as concatenated text node.<codesyntaxhighlight lang="xquery">utillet $map := map { 'a':item-range(//item), 'b': 2, 11'c': [ 3, 204 ] }for $entry in map:entries($map)return element { $entry?key } { string-join($entry?value) }</codesyntaxhighlight> returns all path results from (if available) position 11 to 20.
|}
==util:lastmap-fromvalues== {{Mark|Introduced with Version 9.5.}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:lastmap-fromvalues|$sequence map as itemmap(*)*|item()?*}}<br/>
|-
| '''Summary'''
|Returns last item all values of a {{Code|$sequencemap}}as a sequence. Equivalent to :<codesyntaxhighlight lang="xquery">$sequence[last()]map ? *</codesyntaxhighlight>.
|-
| '''Examples'''
|
* Returns the map values as two items:<codesyntaxhighlight lang="xquery">utillet $map := map { 'a':last-from(reverse), 'b': 2, 'c': [ 3, 4 ] }return map:values(1 to 100)$map)</code> returns <code>1</codesyntaxhighlight>.
|}
=Helper Functions=
==util:replicate==
{{Mark|Updated with Version 9.5:}} Third argument added.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:replicate|$sequence input as item()*, $count as xs:integer|item()*}}<br/>{{Func|util:replicate|$input as item()*, $count as xs:integer, $multiple as xs:boolean|item()*}}
|-
| '''Summary'''
|Returns Evaluates {{Code|$input}} and returns the result {{Code|$count}} instances of the specified times. Unless {{Code|$sequencemultiple}}is enabled, the input expression is only evaluated once. A similar result can be generated with Equivalent expressions:<codesyntaxhighlight lang="xquery">util:replicate($input, $count, true()),(1 to $count) ! $sequenceinput</codesyntaxhighlight>, but in the latter case, the right-hand expression will be evaluated multiple times.
|-
| '''Errors'''
|
* <code>util:replicate('A', 3)</code> returns <code>A A A</code>.
* In the following query, a single new element node is constructed, and {{Code|true}} is returned:
<syntaxhighlight lang="xquery">
let $nodes := util:replicate(<node/>, 2)
return $nodes[1] is $nodes[2]
</syntaxhighlight>
* In this query, two nodes are constructed, and the result is {{Code|false}}:
<syntaxhighlight lang="xquery">
let $nodes := util:replicate(<node/>, 2, true())
return $nodes[1] is $nodes[2]
</syntaxhighlight>
|}
==util:intersperse==
{{Mark|Introduced with Version 9.5.}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:intersperse|$items as item()*, $separator as item()*|item()*}}
|-
| '''Summary'''
|Inserts the defined {{Code|$separator}} between the {{Code|$items}} of a sequence and returns the resulting sequence. Equivalent to:
<syntaxhighlight lang="xquery">
head($items), for $item in tail($items) return ($separator, $item)
</syntaxhighlight>
|-
| '''Examples'''
| Inserts semicolon strings between the three input items:
<syntaxhighlight lang="xquery">
fn:intersperse((<_>1</_>, <_>2</_>, <_>3</_>), '; ')
</syntaxhighlight>
|}
==util:duplicates==
{{Mark|Introduced with Version 9.5.}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:duplicates|$sequence as item()*|xs:anyAtomicType*}}<br/>{{Func|util:duplicates|$sequence as item()*, $collation as xs:string|xs:anyAtomicType*}}
|-
| '''Summary'''
|Returns duplicate values in a {{Code|$sequence}}. See [https://www.w3.org/TR/xpath-functions-31/#func-distinct-values fn:distinct-values] for the applied equality rules and the usage of the {{Code|$collation}} argument.
|-
| '''Examples'''
|
* <code>util:duplicates((1, 2, 1, 1))</code> returns <code>1</code>.
|}
==util:chars==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|util:chars|$string as xs:string|xs:string*}}<br/>
|-
| '''Summary'''
|Returns all characters of a {{Code|$string}} as a sequence. Equivalent to:
<syntaxhighlight lang="xquery">
for $cp in string-to-codepoints($string)
return codepoints-to-string($cp)
</syntaxhighlight>
|-
| '''Examples'''
|
* <code>util:chars('AB')</code> returns the two strings <code>A</code> and <code>B</code>.
|}
=Changelog=
;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.
;Version 9.4
* Added: [[#util:root|util:root]]
;Version 9.3
* Added: [[#util:ddo|util:ddo]]
;Version 9.2
* Added: [[#util:chars|util:chars]], [[#util:init|util:init]]
* Updated: [[#util:item|util:item]], [[#util:last|util:last]], [[#util:range|util:range]] renamed (before: {{Code|util:item-at}}, {{Code|util:item-range}}, {{Code|util:last-from}})
;Version 9.1
* Added: [[#util:if|util:if]], [[#util:or|util:or]]
;Version 9.0
