Changes

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)}}.

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)

Like all other values, arrays are immutable. For example, the <code>[[Array Module#array:reverse|array:reverse]]</code> function creates a new array containing a re-ordering of the members of an existing array, but the existing array is not changed by the operation. Like sequences, arrays have no identity. It is meaningful to compare the contents of two arrays, but there is no way of asking whether they are "the same array": two arrays with the same content are indistinguishable.

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=

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==

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=

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 [http://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===

Retrieves the text from the specified URI, parses the supplied string as JSON text and returns its item representation (see [[#fn:parse-json|fn:parse-json]] for more details).

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 [http://www.w3.org/TR/xslt-30/#func-json-to-xml specification].

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

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

</map> :)

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

Converts an XML node, whose format conforms to the results created by [[#fn:json-to-xml|fn:json-to-xml]], to a JSON string representation. The allowed options can be looked up in the [http://www.w3.org/TR/xslt-30/#func-xml-to-json specification].

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

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==

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 [http://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:

declare function local:x() { () }; i

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=