Utility Module

From BaseX Documentation
Jump to navigation Jump to search

This XQuery Module contains various utility and helper functions.

For all listed functions, equivalent expressions exist in standard XQuery, but code may be better readable with function calls:

(: 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()

In addition, various query optimizations create calls to the utility functions.

Conventions[edit]

All functions and errors in this module and errors are assigned to the http://basex.org/modules/util namespace, which is statically bound to the util prefix.

Conditions[edit]

util:if[edit]

Signatures util:if($condition as item()*, $then as item()*) as item()*
util:if($condition as item()*, $then as item()*, $else as item()*) as item()*
Summary Alternative writing for the if/then/else expression:
  • If the effective boolean value of $condition is true, the $then branch will be evaluated.
  • Otherwise, $else will be evaluated. If no third argument is supplied, an empty sequence will be returned.
Examples
  • util:if(true(), 123, 456) returns 123.
  • util:if(0, 'wrong!') returns an empty sequence.

util:or[edit]

Signatures util:or($items as item()*, $default as item()*) as item()*
Summary Returns $items if it is a non-empty sequence. Otherwise, returns $default. Equivalent to the following expressions:
if(exists($items)) then $items else $default,
(: Elvis operator :)
$items ?: $default
Examples
  • util:or(123, 456) returns 123.
  • util:or(1[. = 0], -1) returns -1.

util:within[edit]

Introduced with Version 9.5:

Signatures util:within($sequence as item()*, $min as xs:integer) as xs:boolean
util:within($sequence as item()*, $min as xs:integer, $max as xs:integer) as xs:boolean
Summary Checks if the specified $sequence has at least $min and, optionally, at most $max items. Equivalent to:
let $count := count($sequence)
return $count >= $min and $count <= $max
Examples
  • util:within(('a', 'b', 'c'), 2) returns true.
  • util:within((1 to 1000000000)[. < 10], 3, 6) returns true.

Positional Access[edit]

util:item[edit]

Signatures util:item($sequence as item()*, $position as xs:double) as item()?
Summary Returns the item from $sequence at the specified $position. Equivalent to:
$sequence[$position]
Examples
  • util:item(reverse(1 to 5), 1) returns 5.
  • util:item(('a','b'), 0) returns an empty sequence.

util:range[edit]

Signatures util:range($sequence as item()*, $first as xs:double, $last as xs:double) as item()*
Summary Returns items from $sequence, starting at position $first and ending at $last. Equivalent to:
subsequence($sequence, $first, $last - $first + 1)
Examples
  • util:range(//item, 11, 20) returns all path results from (if available) position 11 to 20.

util:last[edit]

Signatures util:last($sequence as item()*) as item()?
Summary Returns last item of a $sequence. Equivalent to:
$sequence[last()]
Examples
  • util:last(reverse(1 to 100)) returns 1.

util:init[edit]

Signatures util:init($sequence as item()*) as item()*
Summary Returns all items of a $sequence except for the last one. Equivalent to:
$sequence[position() < last()]
Examples
  • util:init(1 to 4) returns 1 2 3.

Node Functions[edit]

util:ddo[edit]

Signatures util:ddo($nodes as node()*) as node()*
Summary Returns nodes in distinct document order: duplicate nodes will be removed, and the remaining nodes will be returned in document order. As results of path expressions are brought distinct document order before they are returned, the function is equivalent to:
$nodes/self::node()

util:root[edit]

Signatures util:root($nodes as node()*) as document-node()*
Summary Returns the document nodes of the specified $nodes. The path expression /abc is internally represented as util:root(.)/abc</code. Equivalent to:
$nodes ! /

Array and Map Functions[edit]

util:array-members[edit]

Introduced with Version 9.5.

Signatures util:array-members($array as array(*)) as array(*)*
Summary Returns each member of an $array as a new array. Equivalent to:
for $a in 1 to array:size($array)
return [ $array($a) ]
Examples
  • Returns three elements with the member values as concatenated text node.
let $array := [ (), 2, (3, 4) ]
for $member in array:members($array)
return element numbers { $member }

util:array-values[edit]

Introduced with Version 9.5.

Signatures util:array-values($array as array(*)) as item()*
Summary Returns all members of an $array as a sequence. Equivalent to:
$array ? *
Examples
  • Returns the array members as two items:
let $array := [ (), 2, [ 3, 4 ] ]
return array:values($array)

util:map-entries[edit]

Introduced with Version 9.5.

Signatures util:map-entries($map as map(*)) as map(xs:string, item()*)*
Summary Returns each entry of a $map as a new map, each with a key and value entry. Equivalent to:
map:for-each($map, function($key, $value) {
  map { "key": $key, "value": $value }
})
Examples
  • Returns three elements named by the key of the map, and with the entries as concatenated text node.
let $map := map { 'a': (), 'b': 2, 'c': [ 3, 4 ] }
for $entry in map:entries($map)
return element { $entry?key } { string-join($entry?value) }

util:map-values[edit]

Introduced with Version 9.5.

Signatures util:map-values($map as map(*)) as item()*
Summary Returns all values of a $map as a sequence. Equivalent to:
$map ? *
Examples
  • Returns the map values as two items:
let $map := map { 'a': (), 'b': 2, 'c': [ 3, 4 ] }
return map:values($map)

Helper Functions[edit]

util:replicate[edit]

Updated with Version 9.5: Third argument added.

Signatures util:replicate($input as item()*, $count as xs:integer) as item()*
util:replicate($input as item()*, $count as xs:integer, $multiple as xs:boolean) as item()*
Summary Evaluates $input and returns the result $count times. Unless $multiple is enabled, the input expression is only evaluated once. Equivalent expressions:
util:replicate($input, $count, true()),
(1 to $count) ! $input
Errors negative: The specified number is negative.
Examples
  • util:replicate('A', 3) returns A A A.
  • In the following query, a single new element node is constructed, and true is returned:
let $nodes := util:replicate(<node/>, 2)
return $nodes[1] is $nodes[2]
  • In this query, two nodes are constructed, and the result is false:
let $nodes := util:replicate(<node/>, 2, true())
return $nodes[1] is $nodes[2]

util:intersperse[edit]

Introduced with Version 9.5.

Signatures util:intersperse($items as item()*, $separator as item()*) as item()*
Summary Inserts the defined $separator between the $items of a sequence and returns the resulting sequence. Equivalent to:
head($items), for $item in tail($items) return ($separator, $item)
Examples Inserts semicolon strings between the three input items:
fn:intersperse((<_>1</_>, <_>2</_>, <_>3</_>), '; ')

util:duplicates[edit]

Introduced with Version 9.5.

Signatures util:duplicates($sequence as item()*) as xs:anyAtomicType*
util:duplicates($sequence as item()*, $collation as xs:string) as xs:anyAtomicType*
Summary Returns duplicate values in a $sequence. See fn:distinct-values for the applied equality rules and the usage of the $collation argument.
Examples
  • util:duplicates((1, 2, 1, 1)) returns 1.

util:chars[edit]

Signatures util:chars($string as xs:string) as xs:string*
Summary Returns all characters of a $string as a sequence. Equivalent to:
for $cp in string-to-codepoints($string)
return codepoints-to-string($cp)
Examples
  • util:chars('AB') returns the two strings A and B.

Errors[edit]

Code Description
negative The specified number is negative.

Changelog[edit]

Version 9.5
Version 9.4
Version 9.3
Version 9.2
Version 9.1
Version 9.0

The Module was introduced with Version 8.5.