Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
For all listed With {{Announce|Version 11}}, many functions, equivalent expressions exist have been removed in standard favor of new features of XQuery, but code may be better readable with function calls4:
<syntaxhighlight lang{||- valign="xquerytop">(: standard | '''BaseX 10'''| '''XQuery 4'''|- valign="top"| {{Code|util:)array-members}}let $result | [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-array-members <code>array:members</code>]|- valign= if(exists($sequence)) then $sequence else ('default', '"top"| {{Code|util:array-values')}}return $result| [last()https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-array-values <code>array:values</code>]|- valign="top"| {{Code|util:chars}}(| [https: XQuery with //qt4cg.org/specifications/xpath-functions of this module -40/Overview.html#func-chars <code>fn:characters</code>]|- valign="top"| {{Code|util:)duplicates}}$sequence| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-duplicate-values <code>fn:duplicate-values</code>]|- valign="top"| {{Code|util:init}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-trunk <code> fn:trunk</code>]|- valign="top"| {{Code|util:or(('default', 'values'))intersperse}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-intersperse <code>fn:intersperse</code>]|- valign="top"| {{Code|util:item}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-items-at <code> fn:items-at</code>]|- valign="top"| {{Code|util:last()}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-foot <code>fn:foot</syntaxhighlightcode>]|- valign="top"| {{Code|util:map-entries}}In addition, various query optimizations create calls to the utility | [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-map-entries <code>map:entries</code>]|- valign="top"| {{Code|util:map-values}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-map-values <code>map:values</code>]|- valign="top"| {{Code|util:or}}| <code>$expr1 otherwise $expr2|- valign="top"| {{Code|util:replicate}}| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-replicate <code>fn:replicate</code>]|}
|}
==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>.
=Array and Map Functions= ==util:arraystrip-membersnamespaces==
==util(:array-values== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|utilyields :array-values|$array as array(*)|item()*}}|-| '''Summary'''|Returns all members of an {{Code|$array}} as a sequence. Equivalent to:<syntaxhighlight langxml name="xquery">$array ? *</syntaxhighlight>|-| 'value''Examples'''|* Returns the array members as two items:<syntaxhighlight lang="xquery">let $array := [ (), 2, [ 3, 4 ] ]return array:values($array)<child/syntaxhighlight>|} ==util:map-entries== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:map-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 }})</syntaxhighlightxml>|-| '''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) }</syntaxhighlightpre>|} ==util:map-values== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:map-values|$map as map(*)|item()*}}|-| '''Summary'''|Returns Remove all values of a {{Code|$map}} as a sequence. Equivalent todefault namespaces:<syntaxhighlight pre lang="xquery">$map ? *</syntaxhighlight>|-| '''Examples'''|* Returns the map values as two items:<syntaxhighlight lang="xquery">let $map := map { 'a': (), 'b': 2, 'c': [ 3, 4 ] }return map:values($map)</syntaxhighlight>|} =Helper Functions= ==util:replicate== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:replicate|$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'''|Evaluates {{Code|$input}} and returns the result {{Code|$count}} times. Unless {{Code|$multiple}} is enabled, the input expression is only evaluated once. Equivalent expressions:<syntaxhighlight langxml xmlns="xquery">util:replicate($input, $count, true()),(1 to $count) ! $input</syntaxhighlight>|-| '''Errors'''|{{Error|negative|#Errors}} The specified number is negative.|-| '''Examples'''|* <code>util:replicate('Auri1', 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>|} child xmlns==util:intersperse== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|util:intersperse|$items as item()*, $separator as item()*|item()*}}|-| '''Summaryuri2'''|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</_>), '; ')</syntaxhighlightxml>|} ==util:duplicates== {| 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/xpathstrip-functions-31/#func-distinct-values fn:distinct-values] for the applied equality rules and the usage of the {{Code|$collation}} argument.|-| '''Examples'''|* <code>util:duplicatesnamespaces((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</codepre>.
no edit summary
This [[Module Library|XQuery Module]] contains various some utility and helper 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/>
=Conditionsand Ranges=
==util:if==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|util:if|$condition as item()*, $then as item()*|item()*}}<br/pre>{{Func|util:if|( $condition as item()*, $then as item()*, $else as item()*| := ()) as item()*}}<br/pre>|-valign="top"
| '''Summary'''
|Alternative writing for the if/then/else expression:
* If the ''effective boolean value'' of {{Code|$condition}} is true, the {{Code|$then}} branch will be evaluated.
* Otherwise, {{Code|$else}} will be evaluated. If no the third argument is suppliedomitted, an empty sequence will be returned.|-valign="top"
| '''Examples'''
|
|}
==util:orcount-within==
{| 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 langvalign="xquerytop">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== {| width='100%'|-| width='120' | '''SignaturesSignature'''|{{Func|util:within|$sequence as item()*, $min as xs:integer|xs:boolean}}<br/pre>{{Func|util:count-within|( $sequence as item()*, $min as xs:integer, $max as xs:integer| := ()) as xs:boolean}}</pre>|-valign="top"
| '''Summary'''
|Checks if the specified {{Code|$sequence}} has at least {{Code|$min}} and, optionally, at most {{Code|$max}} items. Equivalent to:
<syntaxhighlight pre lang="'xquery"'>
let $count := count($sequence)
return $count >= $min and $count <= $max
</syntaxhighlightpre>|-valign="top"
| '''Examples'''
|
* <code>util:count-within(('a', 'b', 'c'), 2)</code> returns {{Code|true}}.* <code>util:count-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.
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>util:range|( $sequence as item()*, $first as xs:double, $last as xs:double|) as item()*}}<br/pre>|-valign="top"
| '''Summary'''
|Returns items from {{Code|$sequence}}, starting at position {{Code|$first}} and ending at {{Code|$last}}. Equivalent to:
<syntaxhighlight pre lang="'xquery"'>
subsequence($sequence, $first, $last - $first + 1)
</syntaxhighlightpre>|-valign="top"
| '''Examples'''
|
* <code>util:range(//item, 11, 20)</code> returns all path results from (if available) position 11 to 20.
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>util:ddo|( $nodes as node()*|) as node()*}}<br/pre>|-valign="top"
| '''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]. As results of path expressions are brought into distinct document order before they are returned, the function is equivalent to:<syntaxhighlight pre lang="'xquery"'>
$nodes/self::node()
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>util:root|( $nodes as node()*|) as document-node()*}}<br/pre>|-valign="top"
| '''Summary'''
|Returns the document nodes of the specified {{Code|$nodes}}. The path expression <code>/abc</code> is internally represented as <code>util:root(.)/abc</code>. Equivalent to:<syntaxhighlight pre lang="'xquery"'>util:ddo($nodes x ! /)</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>util:arraystrip-members|namespaces( $array node as arraynode(), $prefixes as xs:string* := ())|arrayas node(*)*}}</pre>|-valign="top"
| '''Summary'''
|Returns each member of an {{Code|Removes namespaces with the specified <code>$array}} as a new array. Equivalent to:prefixes</code> from the supplied <syntaxhighlight lang="xquery"code>for $a in 1 to array:size($array)return [ $array($a) ]node</syntaxhighlightcode>. An empty string can be supplied to remove the default namespace. If no prefixes are specified, all namespaces will be removed.|-valign="top"
| '''Examples'''
|
* Returns three elements with the member values as concatenated text node.Remove all namespaces from an element and its descendants:<syntaxhighlight pre lang="'xquery"'>let $array util:strip-namespaces(<xml xmlns='uri' xmlns:prefix='uri2' prefix:name= [ (), 2, (3, 4) ]for $member in array'value'><prefix:members($array)return element numbers { $member }child/></syntaxhighlightxml>|})
|}
! width="110"|Code
|Description
|-valign="top"
|{{Code|negative}}
|The specified number is negative.
=Changelog=
;Version 11.0
* Removed: {{Code|util:array-members}}, {{Code|util:array-values}}, {{Code|util:chars}}, {{Code|util:duplicates}}, {{Code|util:init}}, {{Code|util:intersperse}}, {{Code|util:item}}, {{Code|util:last}}, {{Code|util:map-entries}}, {{Code|util:map-values}}, {{Code|util:replicate}}
;Version 9.7
* Added: {{Function||util:strip-namespaces}}
* Updated: {{Function||util:count-within}}: Renamed from {{Code|util:within}}.
;Version 9.5
* Added: [[#util:intersperse{{Code|util:intersperse]]}}, [[#util:within{{Code|util:within]]}}, [[#util:duplicates{{Code|util:duplicates]]}}, [[#util:array-members{{Code|util:array-members]]}}, [[#util:array-values{{Code|util:array-values]]}}, [[#util:map-entries{{Code|util:map-entries]]}}, [[#util:map-values{{Code|util:map-values]]}}* Updated: [[#util:replicate{{Code|util:replicate]]}}: Third argument added.
;Version 9.4
* Added: [[#util:root{{Function||util:root]]}}
;Version 9.3
* Added: [[#util:ddo{{Function||util:ddo]]}}
;Version 9.2
* Added: [[#util:chars{{Code|util:chars]]}}, [[#util:init{{Code|util:init]]}}* Updated: [[#util:item{{Code|util:item]]}}, [[#util:last{{Code|util:last]]}}, [[#util:range{{Function||util:range]] }} renamed (before: {{Code|util:item-at}}, {{Code|util:item-range}}, {{Code|util:last-from}})
;Version 9.1
* Added: [[#util:if{{Function||util:if]]}}, [[#util:or{{Code|util:or]]}}
;Version 9.0
* Added: [[#util:replicate{{Code|util:replicate]]}}
The Module was introduced with Version 8.5.
