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:or==
{| width='100%'
|- valign="top"
| width='120' | '''Signatures'''
|<pre>util:or(
$items as item()*
$default as item()*
) as item()*</pre>
|- valign="top"
| '''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>
|- valign="top"
| '''Examples'''
|
* <code>util:or(123, 456)</code> returns {{Code|123}}.
* <code>util:or(1[. = 0], -1)</code> returns {{Code|-1}}.
{{Announce|Updated with BaseX 10:}} Renamed from {{Code|util:within}}
|}
=Positional Access=
==util:item==
{| width='100%'
|- valign="top"
| width='120' | '''Signatures'''
|<pre>util:item(
$sequence as item()*
$position as xs:double
) as item()?</pre>
|- valign="top"
| '''Summary'''
|Returns the item from {{Code|$sequence}} at the specified {{Code|$position}}. Equivalent to:
<syntaxhighlight lang="xquery">
$sequence[$position]
</syntaxhighlight>
|- valign="top"
| '''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:last==
{| width='100%'
|- valign="top"
| width='120' | '''Signatures'''
|<pre>util:last(
$sequence as item()*
) as item()?</pre>
|- valign="top"
| '''Summary'''
|Returns last item of a {{Code|$sequence}}. Equivalent to:
<syntaxhighlight lang="xquery">
$sequence[last()]
</syntaxhighlight>
|- valign="top"
| '''Examples'''
|
* <code>util:last(reverse(1 to 100))</code> returns <code>1</code>.
|}
==util:init==
{| width='100%'
|- valign="top"
| width='120' | '''Signatures'''
|<pre>util:init(
$sequence as item()*
) as item()*</pre>
|- valign="top"
| '''Summary'''
|Returns all items of a {{Code|$sequence}} except for the last one. Equivalent to:
<syntaxhighlight lang="xquery">
$sequence[position() < last()]
</syntaxhighlight>
|- valign="top"
| '''Examples'''
|
* <code>util:init(1 to 4)</code> returns <code>1 2 3</code>.
</syntaxhighlight>|} =Array and Map Functions= ==util:array-members== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:array-members( $array as array(*)) as array(*)*</pre>|- valign="top"| '''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>|- valign="top"| '''Examples'''|* Returns three elements with the member values as concatenated text node.<syntaxhighlight lang="xquery">let $array := [ (), 2, (3, 4) ]for $member in util:array-members($array)return element numbers { $member }</syntaxhighlight>|} ==util:array-values== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:array-values( $array as array(*)) as item()*</pre>|- valign="top"| '''Summary'''|Returns all members of an {{Code|$array}} as a sequence. Equivalent to:<syntaxhighlight lang="xquery">$array ? *</syntaxhighlight>|- valign="top"| '''Examples'''|* Returns the array members as two items:<syntaxhighlight lang="xquery">let $array := [ (), 2, [ 3, 4 ] ]return util:array-values($array)</syntaxhighlight>|} ==util:map-entries== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:map-entries( $map as map(*)) as map(xs:string, item()*)*</pre>|- valign="top"| '''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 }})</syntaxhighlight>|- valign="top"| '''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 util:map-entries($map)return element { $entry?key } { string-join($entry?value) }</syntaxhighlight>|} ==util:map-values== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:map-values( $map as map(*)) as item()*</pre>|- valign="top"| '''Summary'''|Returns all values of a {{Code|$map}} as a sequence. Equivalent to:<syntaxhighlight lang="xquery">$map ? *</syntaxhighlight>|- valign="top"| '''Examples'''|* Returns the map values as two items:<syntaxhighlight lang="xquery">let $map := map { 'a': (), 'b': 2, 'c': [ 3, 4 ] }return util:map-values($map)</syntaxhighlight>|} =Helper Functions= ==util:replicate== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:replicate( $input as item()* $count as xs:integer $multiple as xs:boolean := ()) as item()*</pre>|- valign="top"| '''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 lang="xquery">util:replicate($input, $count, true()),(1 to $count) ! $input</syntaxhighlight>|- valign="top"| '''Errors'''|{{Error|negative|#Errors}} The specified number is negative.|- valign="top"| '''Examples'''|* <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== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:intersperse( $items as item()* $separator as item()*) as item()*</pre>|- valign="top"| '''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>|- valign="top"| '''Examples'''| Inserts semicolon strings between the three input items:<syntaxhighlight lang="xquery">fn:intersperse((<_>1</_>, <_>2</_>, <_>3</_>), '; ')</syntaxhighlight>|} ==util:duplicates== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:duplicates( $sequence as item()* $collation as xs:string := ()) as xs:anyAtomicType*</pre>|- valign="top"| '''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.|- valign="top"| '''Examples'''|* <code>util:duplicates((1, 2, 1, 1))</code> returns <code>1</code>.|} ==util:chars== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|<pre>util:chars( $string as xs:string?) as xs:string*</pre>|- valign="top"| '''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>|- valign="top"| '''Examples'''|* <code>util:chars('AB')</code> returns the two strings <code>A</code> and <code>B</code>.
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'''
|<pre>util:if(
$condition as item()*, $then as item()*,
$else as item()* := ()
) as item()*</pre>
|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'''
* <code>util:if(true(), 123, 456)</code> returns {{Code|123}}.
* <code>util:if(0, 'wrong!')</code> returns an empty sequence.
|}
==util:count-within==
{| width='100%'
|- valign="top"
| width='120' | '''SignaturesSignature'''
|<pre>util:count-within(
$sequence as item()*, $min as xs:integer,
$max as xs:integer := ()
) as xs:boolean</pre>
| '''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}}.
|}
{| width='100%'
|- valign="top"
| width='120' | '''SignaturesSignature'''
|<pre>util:range(
$sequence as item()*, $first as xs:double,
$last as xs:double
) as item()*</pre>
| '''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'''
|<pre>util:ddo(
$nodes as node()*
|- 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'''
|<pre>util:root(
$nodes as node()*
| '''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'''
|<pre>util:strip-namespaces(
$node as node(),
$prefixes as xs:string* := ()
) as node()</pre>
|
* Remove all namespaces from an element and its descendants:
<syntaxhighlight pre lang="'xquery"'>
util:strip-namespaces(<xml xmlns='uri' xmlns:prefix='uri2' prefix:name='value'><prefix:child/></xml>)
(: yields :)
<xml name='value'><child/></xml>
</syntaxhighlightpre>
* Remove all default namespaces:
<syntaxhighlight pre lang="'xquery"'>
<xml xmlns='uri1'><child xmlns='uri2'/></xml>
=> util:strip-namespaces('')
|}
=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
;Version 9.5
* Added: {{Function|Code|util:intersperse}}, {{Function|Code|util:within}}, {{Function|Code|util:duplicates}}, {{Function|Code|util:array-members}}, {{Function|Code|util:array-values}}, {{Function|Code|util:map-entries}}, {{Function|Code|util:map-values}}* Updated: {{Function|Code|util:replicate}}: Third argument added.
;Version 9.4
;Version 9.2
* Added: {{Function|Code|util:chars}}, {{Function|Code|util:init}}* Updated: {{Function|Code|util:item}}, {{Function|Code|util:last}}, {{Function||util:range}} renamed (before: {{Code|util:item-at}}, {{Code|util:item-range}}, {{Code|util:last-from}})
;Version 9.1
* Added: {{Function||util:if}}, {{Function|Code|util:or}}
;Version 9.0
* Added: {{Function|Code|util:replicate}}
The Module was introduced with Version 8.5.
