Changes

=Maps=

Maps can be constructed as follows:

map { }, (: empty map :)

map { 'key': true(), 1984: (<a/>, <b/>) }, (: map with two entries :)

return map { $i: 'value' || $i }

)

The function corresponding to the map has the signature {{Code|function($key as xs:anyAtomicType) as item()*}}. The expression {{Code|$map($key)}} returns the associated value; the function call {{Code|map:get($map, $key)}} is equivalent. For example, if {{Code|$books-by-isbn}} is a map whose keys are ISBNs and whose associated values are {{Code|book}} elements, then the expression {{Code|$books-by-isbn("0470192747")}} returns the {{Code|book}} element with the given ISBN. The fact that a map is a function item allows it to be passed as an argument to [[Higher-Order Functions]] that expect a function item as one of their arguments. As an example, the following query uses the higher-order function {{Code|fn:map($f, $seq)}} to extract all bound values from a map:

let $map := map { 'foo': 42, 'bar': 'baz', 123: 456 }

return fn:for-each(map:keys($map), $map)

This returns some permutation of {{Code|(42, 'baz', 456)}}.

Because a map is a function item, functions that apply to functions also apply to maps. A map is an anonymous function, so {{Code|fn:function-name}} returns the empty sequence; {{Code|fn:function-arity}} always returns {{Code|1}}.

Maps may be compared using the {{Code|fn:deep-equal}} function. The [[Map Module]] describes the available set of map functions.

=Arrays=

Arrays can be constructed in two ways. With the square bracket notation, the comma serves as delimiter:

[], (: empty array :)

[ (1, 2) ], (: array with single member :)

[ 1 to 2, 3 ] (: array with two members; same as: [ (1, 2), 3 ] :)

With the {{Code|array}} keyword and curly brackets, the inner expression is evaluated as usual, and the resulting values will be the members of the array:

array { }, (: empty array; same as: array { () } :)

array { (1, 2) }, (: array with two members; same as: array { 1, 2 } :)

array { 1 to 2, 3 } (: array with three members; same as: array { 1, 2, 3 } :)

The function corresponding to the array has the signature {{Code|function($index as xs:integer) as item()*}}. The expression {{Code|$array($index)}} returns an addressed member of the array. The following query returns the five array members {{Code|48 49 50 51 52}} as result:

let $array := array { 48 to 52 }

for $i in 1 to array:size($array)

return $array($i)

==Atomization==

If an array is ''atomized'', all of its members will be atomized. As a result, an atomized item may now result in more than one item. Some examples:

fn:data([1 to 2]) (: returns the sequence 1, 2 :)

[ 'a', 'b', 'c' ] = 'b' (: returns true :)

<a>{ [ 1, 2 ] }</a> (: returns <a>1 2</a> :)

array { 1 to 2 } + 3 (: error: the left operand returns two items :)

Atomization also applies to function arguments. The following query returns 5, because the array will be atomized to a sequence of 5 integers:

let $f := function($x as xs:integer*) { count($x) }

return $f([1 to 5])

However, the next query returns 1, because the array is already of the general type {{Code|item()}}, and no atomization will take place:

let $f := function($x as item()*) { count($x) }

return $f([1 to 5])

Arrays can be compared with the {{Code|fn:deep-equal}} function. The [[Array Module]] describes the available set of array functions.

The following example demonstrates the four alternatives:

let $map := map { 'R': 'red', 'G': 'green', 'B': 'blue' }

return (

$array?(2 to 3) (: 3. returns the second and third values; same as: (1 to 2) ! $array(.) :)

)

The lookup operator can also be used without left operand. In this case, the context item will be used as input. This query returns {{Code|Akureyri}}:

let $maps := (

map { 'name': 'Guðrún', 'city': 'Reykjavík' },

)

return $maps[?name = 'Hildur'] ?city

=Arrow Operator=

The arrow operator <code>=></code> provides a convenient alternative syntax for passing on functions to a value. The expression that precedes the operator will be supplied as first argument of the function that follows the arrow. If <code>$v</code> is a value and <code>f()</code> is a function, then <code>$v => f()</code> is equivalent to <code>f($v)</code>, and <code>$v => f($j)</code> is equivalent to <code>f($v, $j)</code>:

(: Returns 3 :)

count(('A', 'B', 'C')),

(for $i in 'welcome' => string-to-codepoints()

return $i + 1) => codepoints-to-string()

The syntax makes nested function calls more readable, as it is easy to see if parentheses are balanced.

The string constructors syntax uses two backticks and a square bracket for opening and closing a string:

(: Returns "This is a 'new' & 'flexible' syntax." :)

``["This is a 'new' & 'flexible' syntax."]``

XQuery expressions can be embedded via backticks and a curly bracket. The evaluated results will be separated with spaces, and all strings will eventually be concatenated:

(: Returns »Count 1 2 3, and I will be there.« :)

let $c := 1 to 3

=Serialization=

==Adaptive Serialization==

Example:

declare option output:method 'adaptive';

<element id='id0'/>/@id,

map { 'key': 'value' },

true#0

Result:

id="id0"

xs:token("abc"),

}

fn:true#0

==JSON Serialization==

* If an XML node of type {{Code|element(json)}} is found, it will be serialized following the serialization rules of the [[JSON Module]].

The following two queries will both return the JSON snippet <code>{ "key": "value" }</code>:

declare option output:method 'json';

map { "key": "value" }

declare option output:method 'json';

<json type='object'>

<key>value</key>

</json>

=Functions=

<code>array:size</code>, <code>array:append</code>, <code>array:subarray</code>, <code>array:remove</code>, <code>array:insert-before</code>, <code>array:head</code>, <code>array:tail</code>, <code>array:reverse</code>, <code>array:join</code>, <code>array:flatten</code>, <code>array:for-each</code>, <code>array:filter</code>, <code>array:fold-left</code>, <code>array:fold-right</code>, <code>array:for-each-pair</code>

==JSON Functions==

===fn:parse-json===

Parses the supplied string as JSON text and returns its item representation. The result may be a map, an array, a string, a double, a boolean, or an empty sequence. The allowed options can be looked up in the [https://www.w3.org/TR/xpath-functions-31/#func-parse-json specification].

parse-json('{ "name": "john" }') (: yields { "name": "json" } :),

parse-json('[ 1, 2, 4, 8, 16]') (: yields [ 1, 2, 4, 8, 16 ] :)

===fn:json-doc===

json-doc("http://ip.jsontest.com/")('ip') (: returns your IP address :)

===fn:json-to-xml===

Converts a JSON string to an XML node representation. The allowed options can be looked up in the [https://www.w3.org/TR/xpath-functions-31/#func-json-to-xm specification].

json-to-xml('{ "message": "world" }')

<string key="message">world</string>

</map> :)

===fn:xml-to-json===

(: returns "JSON" :)

xml-to-json(<string xmlns="http://www.w3.org/2005/xpath-functions">JSON</string>)

==fn:sort==

Returns a new sequence with sorted {{Code|$input}} items, using an optional {{Code|$collation}}. If a {{Code|$key}} function is supplied, it will be applied on all items. The items of the resulting values will be sorted using the semantics of the {{Code|lt}} expression.

sort(reverse(1 to 3)) (: yields 1, 2, 3 :),

reverse(sort(1 to 3)) (: returns the sorted order in descending order :),

sort((1,2,3), (), function($x) { -$x }) (: yields 3, 2, 1 :),

sort((1,'a')) (: yields an error, as strings and integers cannot be compared :)

==fn:contains-token==

The supplied strings will be tokenized at whitespace boundaries. The function returns {{Code|true}} if one of the strings equals the supplied token, possibly under the rules of a supplied collation:

contains-token(('a', 'b c', 'd'), 'c') (: yields true :)

<xml class='one two'/>/contains-token(@class, 'one') (: yields true :)

==fn:parse-ietf-date==

Parses a string in the IETF format (which is widely used on the Internet) and returns a {{Code|xs:dateTime}} item:

fn:parse-ietf-date('28-Feb-1984 07:07:07')" (: yields 1984-02-28T07:07:07Z :),

fn:parse-ietf-date('Wed, 01 Jun 2001 23:45:54 +02:00')" (: yields 2001-06-01T23:45:54+02:00 :)

==fn:apply==

The supplied {{Code|$function}} is invoked with the specified {{Code|$arguments}}. The arity of the function must be the same as the size of the array.

Example:

fn:apply(concat#5, array { 1 to 5 }) (: 12345 :)

fn:apply(function($a) { sum($a) }, [ 1 to 5 ]) (: 15 :)

fn:apply(count#1, [ 1,2 ]) (: error. the array has two members :)

==fn:random-number-generator==

Creates a random number generator, using an optional seed. The returned map contains three entries:

Example:

let $rng := fn:random-number-generator()

let $number := $rng('number') (: returns a random number :)

let $permutation := $rng('permute')(1 to 5) (: returns a random permutation of (1,2,3,4,5) :)

return ($number, $next-number, $permutation)

==fn:format-number==

The function has been extended to support scientific notation:

format-number(1984.42, '00.0e0') (: yields 19.8e2 :)

==fn:tokenize==

If no separator is specified as second argument, a string will be tokenized at whitespace boundaries:

fn:tokenize(" a b c d") (: yields "a", "b", "c", "d" :)

==fn:trace==

The second argument can now be omitted:

fn:trace(<xml/>, "Node: ")/node() (: yields the debugging output "Node: <xml/>" :),

fn:trace(<xml/>)/node() (: returns the debugging output "<xml/>" :)

==fn:string-join==

The type of the first argument is now <code>xs:anyAtomicType*</code>, and all items will be implicitly cast to strings:

fn:string-join(1 to 3) (: yields the string "123" :)

==fn:default-language==

Items of type <code>xs:hexBinary</code> and <code>xs:base64Binary</code> can be compared against each other. The following queries all yield {{Code|true}}:

xs:hexBinary('') < xs:hexBinary('bb'),

xs:hexBinary('aa') < xs:hexBinary('bb'),

max((xs:hexBinary('aa'), xs:hexBinary('bb'))) = xs:hexBinary('bb')

=Collations=

XQuery 3.1 provides a default collation, which allows for a case-insensitive comparison of ASCII characters (<code>A-Z</code> = <code>a-z</code>). This query returns <code>true</code>:

declare default collation 'http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive';

'HTML' = 'html'

If the [http://site.icu-project.org/download ICU Library] is downloaded and added to the classpath, the full [https://www.w3.org/TR/xpath-functions-31/#uca-collations Unicode Collation Algorithm] features become available in BaseX:

(: returns 0 (both strings are compared as equal) :)

compare('a-b', 'ab', 'http://www.w3.org/2013/collation/UCA?alternate=shifted')

=Enclosed Expressions=

''Enclosed expression'' is the syntactical term for the expressions that are specified inside a function body, try/catch clauses, node constructors and some other expressions. In the following example expressions, its the empty sequence:

try { () } catch * { () },

element x { () },

text { () }

With XQuery 3.1, the expression can be omitted. The following query is equivalent to the upper one:

declare function local:x() { };

try { } catch * { },

element x { }

text { }

=Changelog=

;Version 8.4

;Version 8.2

;Version 8.1

Introduced with Version 8.0.