Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
For all listed functions, equivalent expressions exist in standard XQuery, but code may be 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(('default', 'values'))=> util:last()</syntaxhighlight> In addition, various query optimizations create calls to the utility functions. With {{Announce|Version 11}}, various many functions of this module have been removed as they are now part in favor of new features of the official specificationXQuery 4:
=Positional Access=
no edit summary
This [[Module Library|XQuery Module]] contains various some utility and helper functions.
{|
|- valign="top"
| {{Code|util:map-entries}}
| [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-map-pairs entries <code>map:pairsentries</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}}
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' | '''Signature'''|<pre>util:if( $condition as item()*, $then as item()*, $else as item()* := ()) as item()*</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 the third argument is omitted, 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==
| '''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((1 to 1000000000)[. < 10], 3, 6)</code> returns {{Code|true}}.
|}
==util:range==
| '''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'''
|- 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>
|}
| '''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>
|}
|
* 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('')
</syntaxhighlight>|} =Array and Map Functions= ==util:map-entries== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<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' | '''Signature'''|<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' | '''Signature'''|<pre>util:replicate( $input as item()*, $count as xs:integer, $repeat as xs:boolean? := false()) as item()*</pre>|- valign="top"| '''Summary'''|Evaluates {{Code|$input}} and returns the result {{Code|$count}} times. Unless {{Code|$repeat}} is set to true, the input expression is evaluated multiple times. 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:duplicates== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<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' | '''Signature'''|<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>.
|}
;Version 11.0
* Removed: {{FunctionCode|util:array-members}}, {{Code|util:ifarray-values}}, {{FunctionCode|util:chars}}, {{Code|util:duplicates}}, {{Code|util:init}}, {{Code|util:intersperse}}, {{FunctionCode|util:item}}, {{Code|util:itemlast}}, {{Code|util:map-entries}}, {{FunctionCode|util:map-values}}, {{Code|util:orreplicate}}
;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.
