New functions

A number of new experimental functions become available if XPath 4.0 is enabled.

A few of these functions are made available in Saxon in two forms. They are available unconditionally in the Saxon namespace; and if 4.0 extensions are available then they are also available in the standard fn (or where appropriate, the map or array) namespace.

fn:all( $input as item()*, $predicate as function(item()) as xs:boolean := fn:identity#1 ) as xs:boolean

Returns true if every item in $input satisfies the predicate.

For example, fn:all(*, ->{boolean(self::para)}) returns true if every child element of the context item is a para element.

The second argument may be omitted and defaults to fn:identity#1, so fn:all((1=1, 2=2, 3=4)) returns false.

fn:all-different( $values as xs:anyAtomicType*, $collation as xs:string := fn:default-collation() ) as xs:boolean

Returns true if the values in $values are all different (that is, if no two values are equal). A collation may be supplied as the second argument.

fn:all-equal( $values as xs:anyAtomicType*, $collation as xs:string := fn:default-collation() ) as xs:boolean

Returns true if the values in $values are all equal. A collation may be supplied as the second argument.

fn:build-uri( $parts as map(*), $options as map(*) := map{} ) as xs:string

Constructs a URI, given its components. Available from Saxon 12.1.

The $parts may include scheme, authority, userinfo, host, port, path, query, fragment, path-segments (an array of strings), and query-segments (an array of key-value pairs represented as record(key, value)).

The options available are path-separator, query-separator, allow-deprecated-features, and omit-default-ports.

fn:characters( $value as xs:string? ) as xs:string*

Splits a string into a sequence of single-character strings.

For example, fn:characters("red") returns ("r", "e", "d").

fn:contains-sequence( $input as item()*, $subsequence as item()*, $compare as function(item(), item()) as xs:boolean := fn:deep-equal#2 ) as xs:boolean

Tests whether the first sequence contains the second as a subsequence; items are compared using the supplied comparison function, which can be defaulted.

fn:ends-with-sequence( $input as item()*, $subsequence as item()*, $compare as function(item(), item()) as xs:boolean := fn:deep-equal#2 ) as xs:boolean

Tests whether the first sequence contains the second as a final subsequence; items are compared using the supplied comparison function, which can be defaulted.

fn:expanded-QName( $qname as xs:QName? ) as xs:string?

Converts a QName into Q{uri}local notation.

fn:every( $input as item()*, $predicate as function(item()) as xs:boolean := fn:identity#1 ) as xs:boolean

Returns true if every item in $input satisfies the predicate.

For example, fn:every(*, fn{boolean(self::para)}) returns true if every child element of the context item is a para element.

The second argument may be omitted and defaults to fn:identity#1, so fn:every((1=1, 2=2, 3=4)) returns false.

fn:foot( $input as item()* ) as item()?

Returns the last item in a sequence.

fn:highest( $input as item()*, $collation as xs:string? := fn:default-collation(), $key as function(item()) as xs:anyAtomicType* := fn:identity#1 ) as item()*

Returns those items from the input sequence having the highest value for the supplied function, strings being compared using the supplied collation (which defaults to the default collation).

For example, fn:highest(//employee, (), ->{number(@salary)}) returns those employees having the highest salary.

fn:identity( $input as item()* ) as item()*

Returns the value of the argument, unchanged. Useful in situations where a function must be supplied, but the desired action is to do nothing.

fn:index-where( $input as item()*, $predicate as function(item()) as xs:boolean ) as xs:integer*

Returns the positions of the items in the input sequence that satisfy the supplied predicate.

For example, fn:index-where(("red", "pink", "white", "black"), ->{contains(., "e")}) returns (1, 3).

fn:intersperse( $input as item()*, $separator as item()* ) as item()*

Inserts a copy of $separator between adjacent items in the input sequence.

fn:in-scope-namespaces( $element as element() ) as map(union(xs:NCName, enum('')), xs:anyURI)

Returns the in-scope namespaces of an element as a map from prefixes to URIs.

fn:is-NaN( $value as xs:anyAtomicType ) as xs:boolean

Returns true if the supplied value is the xs:float or xs:double value NaN.

fn:items-after( $input as item()*, $predicate as function(item()) as xs:boolean ) as item()*

Returns the items in the input sequence that follow the first one that satisfies the supplied predicate.

fn:items-at( $input as item()*, $at as xs:integer* ) as item()*

Returns the items at the given positions in the input sequence. For example fn:items-at(21 to 30, (3, 2, 1)) returns (23, 22, 21).

fn:items-before( $input as item()*, $predicate as function(item()) as xs:boolean ) as item()*

Returns the items in the input sequence that precede the first one that satisfies the supplied predicate.

fn:items-ending-where( $input as item()*, $predicate as function(item()) as xs:boolean ) as item()*

Returns the items in the input sequence up to and including the first one that satisfies the supplied predicate.

fn:items-starting-where( $input as item()*, $predicate as function(item()) as xs:boolean ) as item()*

Returns the items in the input sequence starting with the first one that satisfies the supplied predicate.

fn:iterate-while( $input as item()*, $predicate as function(item()*) as xs:boolean, $action as function(item()*) as item()* ) as item()*

Applies the $action function to the $input repeatedly so long as the $predicate function returns true. For example fn:iterate-while(2, ->{. lt 20}, ->{.*.}) returns 16.

fn:lowest( $input as item()*, $collation as xs:string? := fn:default-collation(), $key as function(item()) as xs:anyAtomicType* := fn:identity#1 ) as item()*

Returns those items from the input sequence having the lowest value for the supplied function, strings being compared using the supplied collation (which defaults to the default collation).

For example, fn:lowest(//employee, (), ->{number(@salary)}) returns those employees having the lowest salary.

fn:op( $operator as xs:string ) as function(item()*, item()*) as item()*

Returns an arity-2 function corresponding to a supplied binary operator, for example fn:op("is") returns function($x, $y){$x is $y}.

fn:parcel( $input as item()* ) as record(value)

Wraps an arbitrary sequence of items as a parcel: a parcel is a map with a single entry, whose key is the string "value" and whose value is the wrapped sequence. Parcels are useful because they enable an array to be treated as a sequence of items, by wrapping each member of the array as a parcel.

fn:parse-html( $input as xs:string ) as document-node

Parses an HTML5 document (supplied as a string) using the HTML5 parsing algorithm, returning the result as an XDM document. In SaxonJ this is implemented using validator.nu; in SaxonCS the implementation uses AngleSharp.

fn:parse-QName( $eqname as xs:string ) as xs:QName

Parses a string as a QName (using namespace bindings from the static context where necessary). The string may take one of the formats "local", "prefix:local", or "Q{uri}local".

fn:parse-uri( $uri as xs:string, $options as map(*) := map{} ) as map(*)

Parses a URI value, returning a map that identifies the component parts of the URI. Inverse of fn:build-uri(). Available from Saxon 12.1.

fn:parts( $in as item() ) as map(xs:string, xs:anyAtomicType)

Decomposes a composite "atomic" value into its parts, in the form of a map. For example, an xs:dateTime value is decomposed into year, month, day, hour, minute, second, and timezone. Other values that are decomposable include xs:date, xs:time, xs:duration, xs:QName, and xs:anyURI. For values that are not decomposable, the resulting map contains a single entry whose key is "value" and whose corresponding value is the input value.

fn:range()fn:remove( $input as item()*, $positions as xs:integer* ) as item()*

The function is extended in 4.0 to allow several items to be removed at the same time.

fn:replicate( $input as item()*, $count as xs:nonNegativeInteger ) as item()*

Produces a sequence containing $count copies of $input.

fn:slice ( $input as item()*, $start as xs:integer? := (), $end as xs:integer? := (), $step as xs:integer? := () ) as item()*

Selects items from a sequence. $start and $end can be positive integers for 1-based positions counting from the start of the sequence, or negative integers to count from the end; $step can be a positive integer to select every Nth item, or a negative integer to count backwards.

fn:some( $input as item()*, $predicate as function(item()) as xs:boolean := fn:identity#1 ) as xs:boolean

Returns true if at least one item in $input satisfies the predicate.

The second argument may be omitted and defaults to fn:identity#1, so fn:some((1=1, 2=2, 3=4)) returns true.

fn:starts-with-sequence( $input as item()*, $subsequence as item()*, $compare as function(item(), item()) as xs:boolean := fn:deep-equal#2 ) as xs:boolean

Tests whether the first sequence contains the second as a leading subsequence; items are compared using the supplied comparison function, which can be defaulted.

fn:trunk( $input as item()* ) as item()*

Returns all items in a sequence except the last.

fn:unparcel( $parcel as record(value, *) ) as item()*

Reverses the effect of the fn:parcel() function. (Equivalent to $parcel?value.)

fn:void( $input as item()* ) as empty-sequence()

Returns the empty sequence, unconditionally. The Saxon implementation always evaluates the $input argument eagerly, making it useful to force evaluation of an expression that has side-effects.

fn:xdm-to-json($input as item()*, $options as map(*)) as xs:string

Formats an arbitrary XDM value (including of course an XML document) as JSON. Options include indent=true|false to request indentation, uniform=true|false to request that the same format be used for all elements with a given name, escape-solidus=true|false to control whether the character "/" is escaped, and layouts which is a map from QNames (element names) to the names of layout options, overriding the option chosen by default: the layout options are empty, empty-plus, simple, simple-plus, list, list-plus, record, sequence, and mixed.

array:empty( $array as array(*) ) as xs:boolean

Returns true if the size of the array is zero.

array:exists( $array as array(*) ) as xs:boolean

Returns true if the size of the array is not zero.

array:foot( $array as array(*) ) as item()*

Returns the last member of an array.

array:index-where( $array as array(*), $predicate as function(item()*) as xs:boolean ) as xs:integer*

Returns the integer positions of members of the array for which the predicate returns true.

array:members($array as array(*)) as record(value)*

Accepts an array as input, and turns it into a sequence of parcels: the inverse of the array:of() function.

array:of( $input as record(value, *)* ) as array(*)

Accepts a sequence of parcels (as produced by the fn:parcel() function), and returns an array whose members are the sequences obtained by applying fn:unparcel() to each parcel in turn.

array:slice ( $input as array(*), $start as xs:integer? := (), $end as xs:integer? := (), $step as xs:integer? := () ) as array(*)

Same as fn:slice(), but applied to an array.

array:trunk( $array as array(*) ) as array(*)

Returns an array containing all members of the input array except the last.

map:build( $input as item()*, $key as function(item()) as xs:anyAtomicType? := fn:identity#1, $value as function(item()) as item()* := fn:identity#1, $combine as function(item()*, item()*) as item()* := fn:op(',') ) as map(*)

Builds a map that indexes the $input sequence. For each item in $input, a map entry is generated, with its key computed using the $key function, and the corresponding value computed using the $value function. If there are duplicate keys, the values are combined using the $combine function.

map:entries( $map as map(*) ) as map(*)*

Accepts a map as input, and turns it into a sequence of singleton maps representing the key-value pairs contained in the map. Equivalent to map:for-each($map, ->($k, $v){map{$k : $v}}).

map:filter( $map as map(*), $predicate as function(xs:anyAtomicType, item()* ) as xs:boolean) as map(*)

Accepts a map as input, and returns a new map containing those entries from the original map that satisfy the predicate function.

map:keys( $map as map(*), $predicate as function(item()*) as xs:boolean := true#0 ) as xs:atomicValue*

The second argument is new in 4.0; if supplied, map:keys() returns the keys from entries in the map where applying the predicate to the corresponding value returns true.

map:pairs( $map as map(*) ) as record(key as xs:anyAtomicType, value as item()*)*

Accepts a map as input, and turns it into a sequence of maps representing the key-value pairs contained in the map. Equivalent to map:for-each($map, ->($k, $v){map{"key":$k, "value":$v}}). This differs from map:entries in that each entry in the input map is turned into a map with two entries, named "key" and "value", rather than a singleton map with one entry.