XQuery Function Documentation

Search and Browse

http://exist-db.org/xquery/util

java:org.exist.xquery.functions.util.UtilModule

A module for various utility extension functions.

util:absolute-resource-id

util:absolute-resource-id($node-or-path as item()) as xs:integer?

Returns the absolute internal id of a resource as a 65 bit number. The first 32 bits are the collection id, the next 32 bits are the document id, the last bit is the document type. The argument can either be a node or a string path pointing to a resource in the database. If the resource does not exist or the node does not belong to a stored document, the empty sequence is returned.

Parameters:
$node-or-path The node or a string path pointing to a resource in the database.
Returns:
xs:integer? : the absolute ID of the resource

util:base-to-integer

util:base-to-integer($number as item(), $base as xs:integer) as xs:integer

Converts the number $number from base $base to xs:integer.

Parameters:
$number The number to convert
$base The base of $number
Returns:
xs:integer : the xs:integer representation of $number in base $base

util:base64-decode

util:base64-decode($string as xs:string?) as xs:string?

Decode the given Base64 encoded string back to clear text

Parameters:
$string? The Base64 string to be decoded
Returns:
xs:string? : the decoded output

util:base64-encode

util:base64-encode($string as xs:string?) as xs:string?

Encodes the given string as Base64 (see RFC 2045 §6.8)

Parameters:
$string? The string to be Base64 encoded
Returns:
xs:string? : the Base64 encoded output, with trailing newlines trimmed

util:base64-encode

util:base64-encode($string as xs:string?, $trim as xs:boolean) as xs:string?

Encodes the given string as Base64

Parameters:
$string? The string to be Base64 encoded
$trim Trim trailing newlines?
Returns:
xs:string? : the Base64 encoded output
Deprecated:
This function is deprecated. The output does not need to be trimmed, please use util:base64-encode#1 instead. This function could be removed in the next major release version.

util:base64-encode-url-safe

util:base64-encode-url-safe($string as xs:string?) as xs:string?

Encodes the given string as Base64, url-safe. No padding and use - and _ instead of + and / (see RFC 4648 §5).

Parameters:
$string? The string to be Base64 encoded (url-safe)
Returns:
xs:string? : the Base64, url-safe encoded output without padding

util:binary-doc

util:binary-doc($binary-resource as xs:string?) as xs:base64Binary?

Retrieves the binary resource and returns its contents as a value of type xs:base64Binary. An empty sequence is returned if the resource could not be found or $binary-resource was empty.

Parameters:
$binary-resource? The path to the binary resource
Returns:
xs:base64Binary? : the binary document

util:binary-doc-available

util:binary-doc-available($binary-resource as xs:string?) as xs:boolean

Checks if the binary resource identified by $binary-resource is available.

Parameters:
$binary-resource? The path to the binary resource
Returns:
xs:boolean : true if the binary document is available

util:binary-doc-content-digest

util:binary-doc-content-digest($binary-resource as xs:string?, $algorithm as xs:string) as xs:hexBinary?

Gets the digest of the content of the resource identified by $binary-resource.

Parameters:
$binary-resource? The path to the binary resource
$algorithm The name of the algorithm to use for calculating the digest. Supports: MD2, MD4, MD5, SHA-1, SHA-256, SHA-512, RIPEMD-160, RIPEMD-256, BLAKE2B-160, BLAKE2B-256, BLAKE2B-512
Returns:
xs:hexBinary? : the digest of the content of the Binary Resource

util:binary-to-string

util:binary-to-string($binary-resource as xs:base64Binary?) as xs:string?

Returns the contents of a binary resource as an xs:string value. The binary data is transformed into a Java string using the encoding specified in the optional second argument or the default of UTF-8.

Parameters:
$binary-resource? The binary resource
Returns:
xs:string? : the string containing the encoded binary resource

util:binary-to-string

util:binary-to-string($binary-resource as xs:base64Binary?, $encoding as xs:string) as xs:string?

Returns the contents of a binary resource as an xs:string value. The binary data is transformed into a Java string using the encoding specified in the optional second argument or the default of UTF-8.

Parameters:
$binary-resource? The binary resource
$encoding The encoding type. i.e. 'UTF-8'
Returns:
xs:string? : the string containing the encoded binary resource

util:call

util:call($function-reference as function(*), $parameters as item()*) as item()*

Invokes a first-class function reference created by util:function. The function to be called is passed as the first argument. All remaining arguments are forwarded to the called function.

Parameters:
$function-reference The function to ba called
$parameters* The parameters to be passed into the function
Returns:
item()* : the results from the function called

util:collations

util:collations() as xs:string*

Returns a sequence of strings containing all collation locales that might be specified in the '?lang=' parameter of a collation URI.

Returns:
xs:string* : the sequence of strings containing all collation locales that might be specified in the '?lang=' parameter of a collation URI.

util:collection-name

util:collection-name($node-or-path-string as item()?) as xs:string?

Returns the name of the collection from a passed node or path string. If the argument is a node, the function returns the name of the collection to which the node's document belongs. If the argument is a string, it is interpreted as path to a resource and the function returns the computed parent collection path for this resource.

Parameters:
$node-or-path-string? The document node or a path string.
Returns:
xs:string? : the name of the collection.

util:compile

util:compile($expression as xs:string) as xs:string

Compiles the XQuery expression given in parameter $expression. Returns an empty string if no errors were found, a description of the error otherwise.

Parameters:
$expression The XPath/XQuery expression.
Returns:
xs:string : the results of the expression

util:compile

util:compile($expression as xs:string, $module-load-path as xs:string) as xs:string

Compiles the XQuery expression given in parameter $expression. Returns an empty string if no errors were found, a description of the error otherwise.

Parameters:
$expression The XPath/XQuery expression.
$module-load-path The module load path. Imports will be resolved relative to this. Use xmldb:exist:///db if your modules are stored in db.
Returns:
xs:string : the results of the expression

util:compile-query

util:compile-query($expression as xs:string, $module-load-path as xs:string?) as element()

Compiles the XQuery expression given in parameter $expression. Returns an XML fragment which describes any errors found. If the query could be compiled successfully, a fragment <info result="pass"/> is returned. Otherwise, an error description is returned as follows: <info result="fail"><error code="errcode" line="line" column="column">error description</error></info>.

Parameters:
$expression The XPath/XQuery expression.
$module-load-path? The module load path. Imports will be resolved relative to this. Use xmldb:exist:///db if your modules are stored in db.
Returns:
element() : the results of the expression

util:declare-namespace

util:declare-namespace($prefix as xs:string, $namespace-uri as xs:anyURI) as item()

Dynamically declares a namespace/prefix mapping for the current context.

Parameters:
$prefix The prefix to be assigned to the namespace
$namespace-uri The namespace URI
Returns:
item()

util:declare-option

util:declare-option($name as xs:string, $option as xs:string) as item()

Dynamically declares a serialization option as with 'declare option'.

Parameters:
$name The serialization option name
$option The serialization option value
Returns:
item()

util:declared-variables

util:declared-variables($namespace-uri as xs:string) as xs:string+

Returns a sequence containing the QNames of all functions declared in the module identified by the specified namespace URI. An error is raised if no module is found for the specified URI.

Parameters:
$namespace-uri The namespace URI of the function module
Returns:
xs:string+ : the sequence of function names

util:deep-copy

util:deep-copy($item as item()?) as item()?

Creates a new, entirely in-memory copy of the passed in item.

Parameters:
$item? The item to be copied
Returns:
item()? : The copied item

util:describe-function

util:describe-function($function-name as xs:QName) as node()

Describes a built-in function. Returns an element describing the function signature.

Parameters:
$function-name The name of the function to get the signature of
Returns:
node() : the signature of the function
Deprecated:
Use inspect:inspect-function#1 instead! This function could be removed in the next major release version.

util:disable-profiling

util:disable-profiling() as item()

Disable profiling output within the query.

Returns:
item()

util:doctype

util:doctype($doctype as xs:string+) as node()*

Returns the document nodes of the documents with the given DOCTYPE(s).

Parameters:
$doctype+ The DOCTYPE of the documents to find
Returns:
node()* : the document nodes

util:document-id

util:document-id($node-or-path as item()) as xs:int?

Returns the internal integer id of a document. The argument can either be a node or a string path pointing to a resource in the database. If the resource does not exist or the node does not belong to a stored document, the empty sequence is returned.

Parameters:
$node-or-path The node or a string path pointing to a resource in the database.
Returns:
xs:int? : the ID of the document

util:document-name

util:document-name($node-or-path as item()) as xs:string?

Returns the name of a document (excluding the collection path). The argument can either be a node or a string path pointing to a resource in the database. If the resource does not exist or the node does not belong to a stored document, the empty sequence is returned.

Parameters:
$node-or-path The node or a string path pointing to a resource in the database.
Returns:
xs:string? : the name of the document

util:enable-profiling

util:enable-profiling($verbosity as xs:int) as item()

Enable profiling output within the query. The profiling starts with this function call and will end with a call to 'disable-profiling'. Argument $verbosity specifies the verbosity. All other profiling options can be configured via the 'declare option exist:profiling ...' in the query prolog.

Parameters:
$verbosity The verbosity of the profiling
Returns:
item()

util:eval

util:eval($expression as item()) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval

util:eval($expression as item(), $cache-flag as xs:boolean) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval

util:eval($expression as item(), $cache-flag as xs:boolean, $external-variable as xs:anyType*) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
$external-variable* External variables to be bound for the query that is being evaluated. Should be alternating variable QName and value.
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval

util:eval($expression as item(), $cache-flag as xs:boolean, $external-variable as xs:anyType*, $pass as xs:boolean) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
$external-variable* External variables to be bound for the query that is being evaluated. Should be alternating variable QName and value.
$pass Passes on the original error info (line and column number). By default, this option is false
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval-and-serialize

util:eval-and-serialize($expression as item(), $default-serialization-params as item()?) as item()*

Dynamically evaluates an XPath/XQuery expression and serializes the results

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$default-serialization-params? The default parameters for serialization, these maybe overridden by any settings within the XQuery Prolog of the $expression.
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-and-serialize

util:eval-and-serialize($expression as item(), $default-serialization-params as item()?, $starting-loc as xs:double?) as item()*

Dynamically evaluates an XPath/XQuery expression and serializes the results

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$default-serialization-params? The default parameters for serialization, these maybe overridden by any settings within the XQuery Prolog of the $expression.
$starting-loc? the starting location within the results to return the values from
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-and-serialize

util:eval-and-serialize($expression as item(), $default-serialization-params as item()?, $starting-loc as xs:double?, $length as xs:double?) as item()*

Dynamically evaluates an XPath/XQuery expression and serializes the results

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$default-serialization-params? The default parameters for serialization, these maybe overridden by any settings within the XQuery Prolog of the $expression.
$starting-loc? the starting location within the results to return the values from
$length? the number of items from $starting-loc to return the values of
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-and-serialize

util:eval-and-serialize($expression as item(), $default-serialization-params as item()?, $starting-loc as xs:double?, $length as xs:double?, $pass as xs:boolean) as item()*

Dynamically evaluates an XPath/XQuery expression and serializes the results

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$default-serialization-params? The default parameters for serialization, these maybe overridden by any settings within the XQuery Prolog of the $expression.
$starting-loc? the starting location within the results to return the values from
$length? the number of items from $starting-loc to return the values of
$pass Passes on the original error info (line and column number). By default, this option is false
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-inline

util:eval-inline($inline-context as item()?, $expression as item()) as item()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$inline-context? The inline context
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-inline

util:eval-inline($inline-context as item()?, $expression as item(), $cache-flag as xs:boolean) as item()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$inline-context? The inline context
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-inline

util:eval-inline($inline-context as item()?, $expression as item(), $cache-flag as xs:boolean, $pass as xs:boolean) as item()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$inline-context? The inline context
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
$pass Passes on the original error info (line and column number). By default, this option is false
Returns:
item()* : the results of the evaluated XPath/XQuery expression

util:eval-with-context

util:eval-with-context($expression as item(), $context as node()?, $cache-flag as xs:boolean) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$context? The query inherits the context described by the XML fragment in this parameter. It should have the format: <static-context> <output-size-limit value="-1"/> <unbind-namespace uri="http://exist.sourceforge.net/NS/exist"/> <current-dateTime value="dateTime"/> <implicit-timezone value="duration"/> <variable name="qname">variable value</variable> <default-context>explicitly provide default context here</default-context> <mapModule namespace="uri" uri="uri_to_module"/> </static-context>.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval-with-context

util:eval-with-context($expression as item(), $context as node()?, $cache-flag as xs:boolean, $eval-context-item as item()?) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$context? The query inherits the context described by the XML fragment in this parameter. It should have the format: <static-context> <output-size-limit value="-1"/> <unbind-namespace uri="http://exist.sourceforge.net/NS/exist"/> <current-dateTime value="dateTime"/> <implicit-timezone value="duration"/> <variable name="qname">variable value</variable> <default-context>explicitly provide default context here</default-context> <mapModule namespace="uri" uri="uri_to_module"/> </static-context>.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
$eval-context-item? the context item against which the expression will be evaluated
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:eval-with-context

util:eval-with-context($expression as item(), $context as node()?, $cache-flag as xs:boolean, $eval-context-item as item()?, $pass as xs:boolean) as node()*

Dynamically evaluates an XPath/XQuery expression.

Parameters:
$expression The expression to be evaluated. If it is of type xs:string, the function tries to execute this string as the query. If the first argument is of type xs:anyURI, the function will try to load the query from the resource to which the URI resolves. If the URI has no scheme, it is assumed that the query is stored in the db and the URI is interpreted as a database path. This is the same as calling util:eval(xs:anyURI('xmldb:exist:///db/test/test.xq')). The query inherits the current execution context, i.e. all namespace declarations and variable declarations are visible from within the inner expression. The function returns an empty sequence if a whitespace string is passed.
$context? The query inherits the context described by the XML fragment in this parameter. It should have the format: <static-context> <output-size-limit value="-1"/> <unbind-namespace uri="http://exist.sourceforge.net/NS/exist"/> <current-dateTime value="dateTime"/> <implicit-timezone value="duration"/> <variable name="qname">variable value</variable> <default-context>explicitly provide default context here</default-context> <mapModule namespace="uri" uri="uri_to_module"/> </static-context>.
$cache-flag The flag for whether the compiled query should be cached. The cached querywill be globally available within the db instance.
$eval-context-item? the context item against which the expression will be evaluated
$pass Passes on the original error info (line and column number). By default, this option is false
Returns:
node()* : the results of the evaluated XPath/XQuery expression

util:exclusive-lock

util:exclusive-lock($nodes as node()*, $expression as item()*) as item()*

Puts an exclusive lock on the owner documents of all nodes in the first argument $nodes. Then evaluates the expressions in the second argument $expression and releases the acquired locks after their completion.

Parameters:
$nodes* The nodes whose owning documents will have exclusive locks set.
$expression* The expression(s) that are to be evaluated before the acquired locks are released.
Returns:
item()* : the results of the evaluated expression(s)

util:expand

util:expand($node as node()*) as node()*

Creates an in-memory copy of the passed node set, using the specified serialization options. By default, full-text match terms will be tagged with &lt;exist:match&gt; and XIncludes will be expanded.

Parameters:
$node* The node(s) to create in-memory copies of.
Returns:
node()* : the results

util:expand

util:expand($node as node()*, $serialization-parameters as xs:string) as node()*

Creates an in-memory copy of the passed node set, using the specified serialization options. By default, full-text match terms will be tagged with &lt;exist:match&gt; and XIncludes will be expanded. Serialization parameters can be set in the second argument, which accepts the same parameters as the exist:serialize option.

Parameters:
$node* The node(s) to create in-memory copies of.
$serialization-parameters The serialization parameters
Returns:
node()* : the results

util:function

util:function($name as xs:QName, $arity as xs:integer) as function(*)

Creates a reference to an XQuery function which can later be called from util:call. This allows for higher-order functions to be implemented in XQuery. A higher-order function is a function that takes another function as argument. The first argument represents the name of the function, which should bea valid QName. The second argument is the arity (number of parameters) of the function. If no function can be found that matches the name and arity, an error is thrown. Please note: the arguments to this function have to be literals or need to be resolvable at compile time at least.

Parameters:
$name The name of the function
$arity The arity of the function
Returns:
function(*) : the reference to the XQuery function

util:get-fragment-between

util:get-fragment-between($beginning-node as node(), $ending-node as node()?, $make-fragment as xs:boolean?, $display-root-namespace as xs:boolean?) as xs:string

Serializes an XML fragment or a sequence of nodes between two elements (normally milestone elements). This function works only on documents which are stored in the database itself.The $beginning-node represents the first node/milestone element, $ending-node, the second one. The results will be inclusive of $beginning-node and exclusive of the $ending-node.The third argument, $make-fragment, is a boolean value for the path completion. If it is set to true() the result sequence is wrapped into a parent element node. The fourth argument display-root-namespace (only used when $make-fragment is true()), is a boolean value for displaying the root node namespace. If it is set to true() the attribute "xmlns" in the root node of the result sequence is determined from the $beginning-node. Example call of the function for getting the fragment between two TEI page break element nodes: let $fragment := util:get-fragment-between(//pb[1], //pb[2], true(), true())

Parameters:
$beginning-node The first node/milestone element
$ending-node? The second node/milestone element
$make-fragment? The flag make a fragment.
$display-root-namespace? Display the namespace of the root node of the fragment.
Returns:
xs:string : the string containing the fragment between the two node/milestone elements.

util:get-module-description

util:get-module-description($namespace-uri as xs:string) as xs:string+

Returns a short description of the module identified by the namespace URI.

Parameters:
$namespace-uri The namespace URI of the module
Returns:
xs:string+ : the description of the active function module identified by the namespace URI
Deprecated:
Use inspect:inspect-module-uri#1 instead! This function could be removed in the next major release version.

util:get-module-info

util:get-module-info() as element()

Returns an XML fragment providing additional information about the module identified by the namespace URI.

Returns:
element() : the description of the active function module identified by the namespace URI

util:get-module-info

util:get-module-info($namespace-uri as xs:string) as element()

Returns an XML fragment providing additional information about the module identified by the namespace URI.

Parameters:
$namespace-uri The namespace URI of the module
Returns:
element() : the description of the active function module identified by the namespace URI
Deprecated:
Use inspect:inspect-module-uri#1 instead! This function could be removed in the next major release version.

util:get-option

util:get-option($name as xs:string) as xs:string?

Gets the value of a serialization option as set with 'declare option'.

Parameters:
$name The serialization option name
Returns:
xs:string?

util:get-resource-by-absolute-id

util:get-resource-by-absolute-id($absolute-id as xs:integer) as item()?

Returns the resource indicated by its absolute internal id. The first 32 bits are the collection id, the next 32 bits are the document id, the last bit is the document type. If the resource does not exist, the empty sequence is returned.

Parameters:
$absolute-id The absolute id of a resource in the database.
Returns:
item()? : The resource from the database. A document() if its an XML resource, or an xs:base64binary otherwise

util:get-sequence-type

util:get-sequence-type($sequence-type as xs:anyType*) as xs:string

Returns the string representation of the type of sequence.

Parameters:
$sequence-type* The type of sequence
Returns:
xs:string : the string representation of the type of sequence

util:hash

util:hash($message as item(), $algorithm as xs:string) as xs:string

Calculates a hashcode from a string based on a specified algorithm.

Parameters:
$message The string to generate the hashcode from
$algorithm The algorithm used to generate the hashcode
Returns:
xs:string : the hashcode

util:hash

util:hash($message as item(), $algorithm as xs:string, $base64flag as xs:boolean) as xs:string

Calculates a hashcode from a string based on a specified algorithm.

Parameters:
$message The string to generate the hashcode from
$algorithm The algorithm used to generate the hashcode
$base64flag The flag that specifies whether to return the result as Base64 encoded
Returns:
xs:string : the hashcode

util:import-module

util:import-module($module-uri as xs:anyURI, $prefix as xs:string, $location as xs:anyURI*) as item()

Dynamically imports an XQuery module into the current context. The parameters have the same meaning as in an 'import module ...' expression in the query prolog.

Parameters:
$module-uri The namespace URI of the module
$prefix The prefix to be assigned to the namespace
$location* The location of the module
Returns:
item()
Deprecated:
Use fn:load-module#2 instead! This function could be removed in the next major release version.

util:index-key-documents

util:index-key-documents($nodes as node()*, $value as xs:anyAtomicType) as xs:integer?

Return the number of documents for an indexed value.

Parameters:
$nodes* The nodes whose content is indexed
$value The indexed value to search for
Returns:
xs:integer? : the number of documents for the indexed value

util:index-key-documents

util:index-key-documents($nodes as node()*, $value as xs:anyAtomicType, $index as xs:string) as xs:integer?

Return the number of documents for an indexed value.

Parameters:
$nodes* The nodes whose content is indexed
$value The indexed value to search for
$index The index in which the search is made
Returns:
xs:integer? : the number of documents for the indexed value

util:index-key-occurrences

util:index-key-occurrences($nodes as node()*, $value as xs:anyAtomicType) as xs:integer?

Return the number of occurrences for an indexed value.

Parameters:
$nodes* The nodes whose content is indexed
$value The indexed value to search for
Returns:
xs:integer? : the number of occurrences for the indexed value

util:index-key-occurrences

util:index-key-occurrences($nodes as node()*, $value as xs:anyAtomicType, $index as xs:string) as xs:integer?

Return the number of occurrences for an indexed value.

Parameters:
$nodes* The nodes whose content is indexed
$value The indexed value to search for
$index The index in which the search is made
Returns:
xs:integer? : the number of occurrences for the indexed value

util:index-keys

util:index-keys($node-set as node()*, $start-value as xs:anyAtomicType?, $function-reference as function(*), $max-number-returned as xs:int?) as item()*

Can be used to query existing range indexes defined on a set of nodes. All index keys defined for the given node set are reported to a callback function. The function will check for indexes defined on path as well as indexes defined by QName.

Parameters:
$node-set* The node set
$start-value? Only index keys of the same type but being greater than $start-value will be reported for non-string types. For string types, only keys starting with the given prefix are reported.
$function-reference The function reference as created by the util:function function. It can be an arbitrary user-defined function, but it should take exactly 2 arguments: 1) the current index key as found in the range index as an atomic value, 2) a sequence containing three int values: a) the overall frequency of the key within the node set, b) the number of distinct documents in the node set the key occurs in, c) the current position of the key in the whole list of keys returned.
$max-number-returned? The maximum number of returned keys
Returns:
item()* : the results of the eval of the $function-reference

util:index-keys

util:index-keys($node-set as node()*, $start-value as xs:anyAtomicType?, $function-reference as function(*), $max-number-returned as xs:int?, $index as xs:string) as item()*

Can be used to query existing range indexes defined on a set of nodes. All index keys defined for the given node set are reported to a callback function. The function will check for indexes defined on path as well as indexes defined by QName.

Read more
Parameters:
$node-set* The node set
$start-value? Only index keys of the same type but being greater than $start-value will be reported for non-string types. For string types, only keys starting with the given prefix are reported.
$function-reference The function reference as created by the util:function function. It can be an arbitrary user-defined function, but it should take exactly 2 arguments: 1) the current index key as found in the range index as an atomic value, 2) a sequence containing three int values: a) the overall frequency of the key within the node set, b) the number of distinct documents in the node set the key occurs in, c) the current position of the key in the whole list of keys returned.
$max-number-returned? The maximum number of returned keys
$index The index in which the search is made
Returns:
item()* : the results of the eval of the $function-reference

util:index-keys-by-qname

util:index-keys-by-qname($qname as xs:QName*, $start-value as xs:anyAtomicType?, $function-reference as function(*), $max-number-returned as xs:int?, $index as xs:string) as item()*

Can be used to query existing range indexes defined on a set of nodes. All index keys defined for the given node set are reported to a callback function. The function will check for indexes defined on path as well as indexes defined by QName.

Parameters:
$qname* The node set
$start-value? Only index keys of the same type but being greater than $start-value will be reported for non-string types. For string types, only keys starting with the given prefix are reported.
$function-reference The function reference as created by the util:function function. It can be an arbitrary user-defined function, but it should take exactly 2 arguments: 1) the current index key as found in the range index as an atomic value, 2) a sequence containing three int values: a) the overall frequency of the key within the node set, b) the number of distinct documents in the node set the key occurs in, c) the current position of the key in the whole list of keys returned.
$max-number-returned? The maximum number of returned keys
$index The index in which the search is made
Returns:
item()* : the results of the eval of the $function-reference

util:index-type

util:index-type($set-of-nodes as node()*) as xs:string?

Returns the range index type for a set of nodes or an empty sequence if no index is defined.

Parameters:
$set-of-nodes* The set of nodes
Returns:
xs:string? : the range index type

util:inspect-function

util:inspect-function($function as function(*)) as node()

Returns an XML fragment describing the function referenced by the passed function item.

Parameters:
$function The function item to inspect
Returns:
node() : the signature of the function

util:int-to-octal

util:int-to-octal($int as xs:int) as xs:string

Converts an int e.g. 511 to an octal number e.g. 0777.

Parameters:
$int The int to convert to an octal string.
Returns:
xs:string

util:integer-to-base

util:integer-to-base($number as xs:integer, $base as xs:integer) as xs:string

Converts the xs:integer $number (unsigned) into base $base as xs:string. Bases 2, 8, and 16 are supported.

Parameters:
$number The number to convert
$base The base of $number
Returns:
xs:string : the xs:string representation of $number in base $base

util:is-binary-doc

util:is-binary-doc($binary-resource as xs:string?) as xs:boolean

Checks if the resource identified by $binary-resource is a binary resource.

Parameters:
$binary-resource? The path to the binary resource
Returns:
xs:boolean : true if the resource is a binary document

util:is-module-mapped

util:is-module-mapped($namespace-uri as xs:string) as xs:boolean

Returns a Boolean value if the module statically mapped to a source location in the configuration file.

Parameters:
$namespace-uri The namespace URI of the module
Returns:
xs:boolean : true if the namespace URI is mapped as an active function module

util:is-module-registered

util:is-module-registered($namespace-uri as xs:string) as xs:boolean

Returns a Boolean value if the module identified by the namespace URI is registered.

Parameters:
$namespace-uri The namespace URI of the module
Returns:
xs:boolean : true if the namespace URI is registered as an active function module

util:line-number

util:line-number() as xs:integer

Retrieves the line number of the expression

Returns:
xs:integer : The line number of this expression

util:list-functions

util:list-functions() as function(*)*

Returns a sequence of function items for each function in the current module.

Returns:
function(*)* : sequence of function references
Deprecated:
Use inspect:module-functions#0 instead. This function could be removed in the next major release version.

util:list-functions

util:list-functions($namespace-uri as xs:string) as function(*)*

Returns a sequence of function items for each function in the specified module.

Parameters:
$namespace-uri The namespace URI of the function module
Returns:
function(*)* : sequence of function references
Deprecated:
Use inspect:module-functions-by-uri#1 instead. This function could be removed in the next major release version.

util:log

util:log($priority as xs:string, $message as item()*) as item()

Logs the message to the current logger.

Parameters:
$priority The logging priority: 'error', 'warn', 'debug', 'info', 'trace'
$message* The message to log
Returns:
item()

util:log-app

util:log-app($priority as xs:string, $logger-name as xs:string, $message as item()*) as item()

Logs the message to the named logger

Parameters:
$priority The logging priority: 'error', 'warn', 'debug', 'info', 'trace'
$logger-name The name of the logger, eg: my.app.log
$message* The message to log
Returns:
item()

util:log-system-err

util:log-system-err($message as item()*) as item()

Logs the message to System.err.

Parameters:
$message* The message to log
Returns:
item()

util:log-system-out

util:log-system-out($message as item()*) as item()

Logs the message to System.out.

Parameters:
$message* The message to log
Returns:
item()

util:map-module

util:map-module($namespace-uri as xs:string, $location-uri as xs:string) as item()

Map the module to a source location. This function is only available to the DBA role.

Parameters:
$namespace-uri The namespace URI of the module
$location-uri The location URI of the module
Returns:
item() : Returns an empty sequence

util:mapped-modules

util:mapped-modules() as xs:string+

Returns a sequence containing the namespace URIs of all XQuery modules which are statically mapped to a source location in the configuration file. This does not include any built in modules.

Returns:
xs:string+ : the sequence of all of the active function modules namespace URIs

util:node-by-id

util:node-by-id($document as node(), $node-id as xs:string) as node()?

Retrieves a node by its internal node-id. The document is specified via the first argument. It may either be a document node or another node from the same document from which the target node will be retrieved by its id. The second argument is the internal node-id, specified as a string. If a node with the matching node-id is found, it is returned. Otherwise returns the empty sequence.

Parameters:
$document The document whose node is to be retrieved by its id
$node-id The internal node id
Returns:
node()? : the node or an empty sequence if a matching node does not exist

util:node-id

util:node-id($node as node()) as xs:string

Returns the internal node-id of a node. The internal node-id uniquely identifies a node within its document. It is encoded as a long number.

Parameters:
$node The node to get the internal node-id from
Returns:
xs:string : the internal node-id

util:node-xpath

util:node-xpath($node as node()) as xs:string?

Returns the XPath for a Node.

Parameters:
$node The node to retrieve the XPath to
Returns:
xs:string? : the XPath expression of the node

util:octal-to-int

util:octal-to-int($octal as xs:string) as xs:int

Converts an octal string e.g. '0777' to an int e.g. 511.

Parameters:
$octal The octal string to convert to an int.
Returns:
xs:int

util:parse-html

util:parse-html($to-be-parsed as xs:string?) as document-node()?

Parses the passed string value into an XML fragment. The HTML string may not be well-formed XML. It will be passed through the Neko HTML parser to make it well-formed. An empty sequence is returned if the argument is an empty string or sequence.

Parameters:
$to-be-parsed? The string to be parsed
Returns:
document-node()? : the XML fragment parsed from the string

util:qname-index-lookup

util:qname-index-lookup($qname as xs:QName, $comparison-value as xs:anyAtomicType) as node()*

Can be used to query existing qname indexes defined on a set of nodes.

Parameters:
$qname The QName
$comparison-value The comparison value
Returns:
node()* : The result

util:qname-index-lookup

util:qname-index-lookup($qname as xs:QName, $comparison-value as xs:anyAtomicType, $element-or-attribute as xs:boolean) as node()*

Can be used to query existing qname indexes defined on a set of nodes.

Parameters:
$qname The QName
$comparison-value The comparison value
$element-or-attribute true() to lookup an element, false to lookup an attribute
Returns:
node()* : The result

util:random

util:random() as xs:double

Returns a random number between 0.0 and 1.0

Returns:
xs:double : a random number between 0.0 and 1.0

util:random

util:random($max as xs:integer) as xs:integer

Returns a random number between 0 (inclusive) and $max (exclusive), that is, a number greater than or equal to 0 but less than $max

Parameters:
$max A number to be used as the exclusive maximum value for the random number; the return value will be less than this number.
Returns:
xs:integer : a random number between 0 and $max

util:random-ulong

util:random-ulong() as xs:unsignedLong

Returns a random number between 0 and the maximum xs:unsignedLong

Returns:
xs:unsignedLong : a random number between 0 and the maximum xs:unsignedLong

util:registered-functions

util:registered-functions() as xs:string+

Returns a sequence containing the QNames of all functions currently known to the system, including functions in imported and built-in modules.

Returns:
xs:string+ : the sequence of function names

util:registered-functions

util:registered-functions($namespace-uri as xs:string) as xs:string+

Returns a sequence containing the QNames of all functions declared in the module identified by the specified namespace URI. An error is raised if no module is found for the specified URI.

Parameters:
$namespace-uri The namespace URI of the function module
Returns:
xs:string+ : the sequence of function names

util:registered-modules

util:registered-modules() as xs:string+

Returns a sequence containing the namespace URIs of all modules currently known to the system, including built in and imported modules.

Returns:
xs:string+ : the sequence of all of the active function modules namespace URIs

util:shared-lock

util:shared-lock($nodes as node()*, $expression as item()*) as item()*

Puts a shared lock on the owner documents of all nodes in the first argument $nodes. Then evaluates the expressions in the second argument $expression and releases the acquired locks aftertheir completion.

Parameters:
$nodes* The nodes that the shared lock will be placed on their owning documents.
$expression* The expression to be evaluated before the acquired locks are released.
Returns:
item()* : the results of the evaluation of the expression(s)

util:string-to-binary

util:string-to-binary($encoded-string as xs:string?) as xs:base64Binary?

Returns the contents of a string as an base64binary value. The string data is transformed into a binary using the encoding specified in the optional second argument or the default of UTF-8.

Parameters:
$encoded-string? The string containing the encoded binary resource
Returns:
xs:base64Binary? : the binary resource

util:string-to-binary

util:string-to-binary($encoded-string as xs:string?, $encoding as xs:string) as xs:base64Binary?

Returns the contents of a string as a base64binary value. The string data is transformed into a binary using the encoding specified in the optional second argument or the default of UTF-8.

Parameters:
$encoded-string? The string containing the encoded binary resource
$encoding the encoding type. i.e. 'UTF-8'
Returns:
xs:base64Binary? : the binary resource

util:system-date

util:system-date() as xs:date

Returns the current xs:date (with timezone) as reported by the Java method System.currentTimeMillis(). Contrary to fn:current-date, this function is not stable, i.e. the returned xs:date will change during the evaluation time of a query and can be used to measure time differences.

Returns:
xs:date : the current xs:date (with timezone)

util:system-dateTime

util:system-dateTime() as xs:dateTime

Returns the current xs:dateTime (with timezone) as reported by the Java method System.currentTimeMillis(). Contrary to fn:current-dateTime, this function is not stable, i.e. the returned xs:dateTime will change during the evaluation time of a query and can be used to measure time differences.

Returns:
xs:dateTime : the current xs:dateTime (with timezone)

util:system-property

util:system-property($property-name as xs:string) as xs:string?

Returns the value of a system property. Similar to the corresponding XSLT function. Predefined properties are: vendor, vendor-url, product-name, product-version, product-build, and all Java system properties.

Parameters:
$property-name The name of the system property to retrieve the value of.
Returns:
xs:string? : the value of the named system property

util:system-time

util:system-time() as xs:time

Returns the current xs:time (with timezone) as reported by the Java method System.currentTimeMillis(). Contrary to fn:current-time, this function is not stable, i.e. the returned xs:time will change during the evaluation time of a query and can be used to measure time differences.

Returns:
xs:time : the current xs:time (with timezone)

util:unescape-uri

util:unescape-uri($escaped-string as xs:string, $encoding as xs:string) as xs:string

Returns an un-escaped URL escaped string with the encoding scheme (e.g. "UTF-8"). Decodes encoded sensitive characters from a URL, for example "%2F" becomes "/", i.e. does the oposite to escape-uri()

Parameters:
$escaped-string The escaped string to be un-escaped
$encoding The encoding scheme to use in the un-escaping of the string
Returns:
xs:string : the un-escaped string

util:unmap-module

util:unmap-module($namespace-uri as xs:string) as item()

Remove relation between module namespace and source location. This function is only available to the DBA role.

Parameters:
$namespace-uri The namespace URI of the module
Returns:
item() : Returns an empty sequence

util:uuid

util:uuid() as xs:string

Generate a version 4 (random) universally unique identifier (UUID) string, e.g. 154ad200-9c79-44f3-8cff-9780d91552a6

Returns:
xs:string : a generated UUID string

util:uuid

util:uuid($name as item()) as xs:string

Generate a version 3 universally unique identifier (UUID) string, e.g. 2b92ddb6-8e4e-3891-b519-afa1609ced73

Parameters:
$name The input value for UUID calculation.
Returns:
xs:string : a generated UUID string

util:wait

util:wait($interval as xs:integer) as item()

Wait for the specified number of milliseconds

Parameters:
$interval Number of milliseconds to wait.
Returns:
item() : Returns an empty sequence