Difference between pages "XQuery 3.1" and "Array Module"

From BaseX Documentation
(Difference between pages)
Jump to navigation Jump to search
m (Grammatical correction)
 
 
Line 1: Line 1:
−
This article is part of the [[XQuery|XQuery Portal]]. It provides a summary of the most important features of the [http://www.w3.org/TR/xquery-31/ XQuery 3.1] Recommendation.
+
This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which has been introduced with [[XQuery 3.1#Arrays|XQuery 3.1]].
  
−
=Maps=
+
=Conventions=
  
−
A ''map'' is a function that associates a set of keys with values, resulting in a collection of key/value pairs. Each key/value pair in a map is called an entry. A key is an arbitrary atomic value, and the associated value is an arbitrary sequence. Within a map, no two entries have the same key, when compared using the {{Code|eq}} operator. It is not necessary that all the keys should be mutually comparable (for example, they can include a mixture of integers and strings).
+
All functions and errors in this module are assigned to the <code><nowiki>http://www.w3.org/2005/xpath-functions/array</nowiki></code> namespace, which is statically bound to the {{Code|array}} prefix.<br/>
  
−
Maps can be constructed as follows:
+
=Functions=
  
−
<pre class="brush:xquery">
+
==array:size==
−
map { },                                    (: empty map :)
 
−
map { 'key': true(), 1984: (<a/>, <b/>) },  (: map with two entries :)
 
−
map:merge(                                  (: map with ten entries :)
 
−
  for $i in 1 to 10
 
−
  return map { $i: 'value' || $i }
 
−
)
 
−
</pre>
 
  
−
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:
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:size|$input as array(*)|xs:integer}}
 +
|-
 +
| '''Summary'''
 +
| Returns the number of members in {{Code|$array}}. Note that because an array is an item, the {{Code|fn:count}} function when applied to an array always returns {{Code|1}}.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
 +
* <code>array:size([1 to 10])</code> returns {{Code|1}}, because the array contains a single sequence with 10 integers.
 +
|}
  
−
<pre class="brush:xquery">
+
==array:get==
−
let $map := map { 'foo': 42, 'bar': 'baz', 123: 456 }
 
−
return fn:for-each(map:keys($map), $map)
 
−
</pre>
 
  
−
This returns some permutation of {{Code|(42, 'baz', 456)}}.
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:get|$array as array(*), $position as xs:integer|item()*}}
 +
|-
 +
| '''Summary'''
 +
| Returns the {{Code|$array}} member at the specified {{Code|$position}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
 +
|}
  
−
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}}.
+
==array:append==
  
−
Like all other values, maps are immutable. For example, the <code>[[Map Module#map:remove|map:remove]]</code> function creates a new map by removing an entry from an existing map, but the existing map is not changed by the operation. Like sequences, maps have no identity. It is meaningful to compare the contents of two maps, but there is no way of asking whether they are "the same map": two maps with the same content are indistinguishable.
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:append|$array as array(*), $member as item()*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a copy of {{Code|$array}} with a new {{Code|$member}} attached.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:append([], 'member1')</code> returns the array {{Code|["member1"]}}.
 +
|}
  
−
Maps may be compared using the {{Code|fn:deep-equal}} function. The [[Map Module]] describes the available set of map functions.
+
==array:subarray==
  
−
=Arrays=
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:subarray|$array as array(*), $position as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as array(*), $position as xs:integer, $length as xs:integer|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Constructs a new array with with {{Code|$length}} members of {{Code|$array}} beginning from the specified {{Code|$position}}.<br/>The two-argument version of the function returns the same result as the three-argument version when called with {{Code|$length}} equal to the value of {{Code|array:size($array) - $position + 1}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is less than one, or if {{Code|$position + $length}} is greater than {{Code|array:size($array) + 1}}.<br/>{{Error|FOAY0002|#Errors}} {{Code|$length}} is less than zero.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}.
 +
|}
  
−
An ''array'' is a function that associates a set of positions, represented as positive integer keys, with values. The first position in an array is associated with the integer {{Code|1}}. The values of an array are called its members. In the type hierarchy, array has a distinct type, which is derived from function. In BaseX, arrays (as well as sequences) are based on an efficient [http://en.wikipedia.org/wiki/Finger_tree Finger Tree] implementation.
+
==array:put==
  
−
Arrays can be constructed in two ways. With the square bracket notation, the comma serves as delimiter:
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:put|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a copy of {{Code|$array}} with {{Code|$member}} replaced at the specified {{Code|$position}}. Equivalent to <code>$array => array:remove($position) => array:insert-before($position, $member)</code>.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}.
 +
|}
  
−
<pre class="brush:xquery">
+
==array:remove==
−
[],            (: empty array :)
 
−
[ (1, 2) ],    (: array with single member :)
 
−
[ 1 to 2, 3 ]  (: array with two members; same as: [ (1, 2), 3 ] :)
 
−
</pre>
 
  
−
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:
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:remove|$array as array(*), $positions as xs:integer*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$positions}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:append(["a"], 1)</code> returns the array {{Code|[]}}.
 +
|}
  
−
<pre class="brush:xquery">
+
==array:insert-before==
−
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 } :)
 
−
</pre>
 
  
−
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:
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:insert-before|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a copy of {{Code|$array}} with one new {{Code|$member}} at the specified {{Code|$position}}. Setting {{Code|$position}} to the value {{Code|array:size($array) + 1}} yields the same result as {{Code|array:append($array, $insert)}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array) + 1}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
 +
|}
  
−
<pre class="brush:xquery">
+
==array:head==
−
let $array := array { 48 to 52 }
 
−
for $i in 1 to array:size($array)
 
−
return $array($i)
 
−
</pre>
 
  
−
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.
+
{| width='100%'
−
 
+
| width='120' | '''Signatures'''
−
==Atomization==
+
|{{Func|array:head|$array as array(*)|item()*}}
−
 
+
|-
−
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:
+
| '''Summary'''
−
 
+
| Returns the first member of {{Code|$array}}. This function is equivalent to the expression {{Code|$array(1)}}.
−
<pre class="brush:xquery">
+
|-
−
fn:data([1 to 2])       (: returns the sequence 1, 2 :)
+
| '''Errors'''
−
[ 'a', 'b', 'c' ] = 'b'  (: returns true :)
+
|{{Error|FOAY0001|#Errors}} The array is empty.
−
<a>{ [ 1, 2 ] }</a>      (: returns <a>1 2</a> :)
+
|-
−
array { 1 to 2 } + 3    (: error: the left operand returns two items :)
+
| '''Examples'''
−
</pre>
+
|
 +
* <code>array:head(["a", "b"])</code> returns {{Code|"a"}}.
 +
* <code>array:head([["a", "b"], ["c", "d"]])</code> returns the array {{Code|["a", "b"]}}.
 +
|}
  
−
Atomization also applies to function arguments. The following query returns 5, because the array will be atomized to a sequence of 5 integers:
+
==array:tail==
  
−
<pre class="brush:xquery">
+
{| width='100%'
−
let $f := function($x as xs:integer*) { count($x) }
+
| width='120' | '''Signatures'''
−
return $f([1 to 5])
+
|{{Func|array:tail|$array as array(*)|array(*)}}
−
</pre>
+
|-
 +
| '''Summary'''
 +
| Returns a new array with all members except the first from {{Code|$array}}. This function is equivalent to the expression {{Code|array:remove($array, 1)}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} The array is empty.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
 +
|}
  
−
However, the next query returns 1, because the array is already of the general type {{Code|item()}}, and no atomization will take place:
+
==array:reverse==
  
−
<pre class="brush:xquery">
+
{| width='100%'
−
let $f := function($x as item()*) { count($x) }
+
| width='120' | '''Signatures'''
−
return $f([1 to 5])
+
|{{Func|array:reverse|$array as array(*)|array(*)}}
−
</pre>
+
|-
 +
| '''Summary'''
 +
| Returns a new array with all members of {{Code|$array}} in reverse order.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}.
 +
|}
  
−
Arrays can be compared with the {{Code|fn:deep-equal}} function. The [[Array Module]] describes the available set of array functions.
+
==array:join==
  
−
=Lookup Operator=
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:join|$arrays as array(*)*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Concatenates the contents of several {{Code|$arrays}} into a single array.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:join(())</code> returns the array {{Code|[]}}.
 +
* <code>array:join((1 to 3) ! array { . })</code> returns the array {{Code|[1, 2, 3]}}.
 +
|}
  
−
The lookup operator provides some syntactic sugar to access values of maps or array members. It is introduced by the question mark ({{Code|?}}) and followed by a specifier. The specifier can be:
+
==array:flatten==
  
−
# A wildcard {{Code|*}},
+
{| width='100%'
−
# The name of the key,
+
| width='120' | '''Signatures'''
−
# The integer offset, or
+
|{{Func|array:flatten|$items as item()*|item()*}}
−
# Any other parenthesized expression.
+
|-
 +
| '''Summary'''
 +
| Recursively flattens all arrays that occur in the supplied {{Code|$items}}.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:flatten(["a","b"])</code> returns the sequence {{Code|"a", "b"}}.
 +
* <code>array:flatten([1,[2,3],4]])</code> returns the sequence {{Code|1, 2, 3, 4}}.
 +
|}
  
−
The following example demonstrates the four alternatives:
+
==array:for-each==
  
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:for-each|$array as array(*), $function as function(item()*) as item()*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a new array, in which each member is computed by applying {{Code|$function}} to the corresponding member of {{Code|$array}}.
 +
|-
 +
| '''Examples'''
 +
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
−
let $map := map { 'R': 'red', 'G': 'green', 'B': 'blue' }
+
array:for-each(
−
return (
+
   array { 1 to 5 },
−
  $map?*          (: 1. returns all values; same as: map:keys($map) ! $map(.) :),
+
   function($i) { $i + 1}
−
  $map?R          (: 2. returns the value associated with the key 'R'; same as: $map('R') :),
 
−
  $map?('G','B')  (: 3. returns the values associated with the key 'G' and 'B' :)
 
−
),
 
−
 
 
−
let $array := [ 'one', 'two', 'three' ]
 
−
return (
 
−
   $array?*        (: 1. returns all values; same as: (1 to array:size($array)) ! $array(.) :),
 
−
   $array?1        (: 2. returns the first value; same as: $array(1) :),
 
−
  $array?(2 to 3)  (: 3. returns the second and third values; same as: (1 to 2) ! $array(.) :)
 
 
)
 
)
 
</pre>
 
</pre>
 +
|}
  
−
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}}:
+
==array:filter==
  
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:filter|$array as array(*), $function as function(item()*) as xs:boolean|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a new array with those members of {{Code|$array}} for which {{Code|$function}} returns {{Code|true}}.
 +
|-
 +
| '''Examples'''
 +
|The following query returns the array {{Code|[0, 1, 3]}}:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
−
let $maps := (
+
array:filter(
−
   map { 'name': 'Guðrún', 'city': 'Reykjavík' },
+
   array { 0, 1, -2, 3, -4 },
−
   map { 'name': 'Hildur', 'city': 'Akureyri' }
+
   function($i) { $i > 0 }
 
)
 
)
−
return $maps[?name = 'Hildur'] ?city
 
 
</pre>
 
</pre>
 +
|}
  
−
=Arrow Operator=
+
==array:fold-left==
−
 
 
−
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>:
 
  
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:fold-left|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
 +
|-
 +
| '''Summary'''
 +
| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from left to right and using {{Code|$zero}} as first argument.
 +
|-
 +
| '''Examples'''
 +
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
−
(: Returns 3 :)
+
array:fold-left(
−
count(('A', 'B', 'C')),
+
  array { 1 to 10 },
−
('A', 'B', 'C') => count(),
+
  0,
−
('A', 'B', 'C') => (function( $sequence) { count( $sequence)})(),
+
  function($a, $b) { $a + $b }
−
 
+
)
−
(: Returns W-E-L-C-O-M-E :)
 
−
string-join(tokenize(upper-case('w e l c o m e')), '-'),
 
−
'w e l c o m e' => upper-case() => tokenize() => string-join('-'),
 
−
 
 
−
(: Returns xfmdpnf :)
 
−
codepoints-to-string(
 
−
  for $i in string-to-codepoints('welcome')
 
−
  return $i + 1
 
−
),
 
−
(for $i in 'welcome' => string-to-codepoints()
 
−
return $i + 1) => codepoints-to-string()
 
 
</pre>
 
</pre>
 +
|}
  
−
The syntax makes nested function calls more readable, as it is easy to see if parentheses are balanced.
+
==array:fold-right==
−
 
 
−
=String Constructor=
 
−
 
 
−
The string constructor has been inspired by [https://en.wikipedia.org/wiki/Here_document here document] literals of the Unix shell and script languages. It allows you to generate strings that contain various characters that would otherwise be interpreted as XQuery delimiters.
 
−
 
 
−
The string constructors syntax uses two backticks and a square bracket for opening and closing a string:
 
  
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:fold-right|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
 +
|-
 +
| '''Summary'''
 +
| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from right to left and using {{Code|$zero}} as first argument.
 +
|-
 +
| '''Examples'''
 +
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
−
(: Returns "This is a 'new' & 'flexible' syntax." :)
+
array {
−
``["This is a 'new' & 'flexible' syntax."]``
+
  array:fold-right(
−
</pre>
+
    array { 1 to 5 },
−
 
+
    (),
−
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:
+
    function($a, $b) { $b, $a }
−
 
+
   )
−
<pre class="brush:xquery">
 
−
(: Returns »Count 1 2 3, and I will be there.« :)
 
−
let $c := 1 to 3
 
−
return ``[»Count `{ $c }`, and I will be there.«]``</pre>
 
−
 
 
−
=Serialization=
 
−
 
 
−
Two [[Serialization]] methods have been added to the [http://www.w3.org/TR/xslt-xquery-serialization-31 Serialization spec]:
 
−
 
 
−
==Adaptive Serialization==
 
−
 
 
−
The {{Code|adaptive}} serialization provides an intuitive textual representation for all XDM types, including maps and arrays, functions, attributes, and namespaces. All items will be separated by the value of the {{Code|item-separator}} parameter, which by default is a newline character. It is utilized by the functions <code>[[Profiling Module#prof:dump|prof:dump]]</code> and <code>[http://www.w3.org/TR/xpath-functions-31/#func-trace fn:trace]</code>.
 
−
 
 
−
Example:
 
−
 
 
−
<pre class="brush:xquery">
 
−
declare option output:method 'adaptive';
 
−
<element id='id0'/>/@id,
 
−
xs:token("abc"),
 
−
map { 'key': 'value' },
 
−
true#0
 
−
</pre>
 
−
 
 
−
Result:
 
−
 
 
−
<pre class="brush:xml">
 
−
id="id0"
 
−
xs:token("abc"),
 
−
map {
 
−
   "key": "value"
 
 
}
 
}
−
fn:true#0
 
 
</pre>
 
</pre>
 +
|}
  
−
==JSON Serialization==
+
==array:for-each-pair==
−
 
 
−
The new {{Code|json}} serialization output method can be used to serialize XQuery maps, arrays, atomic values and empty sequences as JSON.
 
−
 
 
−
The {{Code|json}} output method has been introduced in BaseX before it was added to the official specification. It complies with the standard serialization rules and, at the same time, preserves the existing semantics:
 
−
 
 
−
* If an XML node of type {{Code|element(json)}} is found, it will be serialized following the serialization rules of the [[JSON Module]].
 
−
* Any other node or atomic value, map, array, or empty sequence will be serialized according to the [http://www.w3.org/TR/xslt-xquery-serialization-31/#json-output rules in the specification].
 
−
 
 
−
The following two queries will both return the JSON snippet <code>{ "key": "value" }</code>:
 
  
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:for-each-pair|$array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*|array(*)}}
 +
|-
 +
| '''Summary'''
 +
| Returns a new array obtained by evaluating the supplied {{Code|$function}} for each pair of members at the same position in {{Code|$array1}} and {{Code|$array2}}.
 +
|-
 +
| '''Examples'''
 +
|The following query returns the array {{Code|[5, 7, 9]}}:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
−
declare option output:method 'json';
+
array:for-each-pair(
−
map { "key": "value" }
+
  array { 1 to 3 },
−
</pre>
+
   array { 4 to 6 },
−
 
+
  function($a + $b) { $a + $b }
−
<pre class="brush:xquery">
+
)
−
declare option output:method 'json';
 
−
<json type='object'>
 
−
  <key>value</key>
 
−
</json>
 
−
</pre>
 
−
 
 
−
=Functions=
 
−
 
 
−
The following functions have been added in the [http://www.w3.org/TR/xpath-functions-31/ XQuery 3.1 Functions and Operators] Specification:
 
−
 
 
−
==Map Functions==
 
−
 
 
−
<code>map:merge</code>, <code>map:size</code>, <code>map:keys</code>, <code>map:contains</code>, <code>map:get</code>, <code>map:entry</code>, <code>map:put</code>, <code>map:remove</code>, <code>map:for-each</code>
 
−
 
 
−
Please check out the [[Map Module]] for more details.
 
−
 
 
−
==Array 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==
 
−
 
 
−
With XQuery 3.1, native support for JSON objects was added. Strings and resources can be parsed to XQuery items and, as [[#JSON Serialization|shown above]], serialized back to their original form.
 
−
 
 
−
===fn:parse-json===
 
−
 
 
−
; Signatures
 
−
* <code>fn:parse-json($input as xs:string) as item()?</code>
 
−
* <code>fn:parse-json($input as xs:string, $options as map(*)) as item()?</code>
 
−
 
 
−
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].
 
−
 
 
−
<pre class="brush:xquery">
 
−
parse-json('{ "name": "john" }')  (: yields { "name": "json" } :),
 
−
parse-json('[ 1, 2, 4, 8, 16]')    (: yields [ 1, 2, 4, 8, 16 ] :)
 
−
</pre>
 
−
 
 
−
===fn:json-doc===
 
−
 
 
−
; Signatures
 
−
* <code>fn:json-doc($uri as xs:string) as item()?</code>
 
−
* <code>fn:json-doc($uri as xs:string, $options as map(*)) as item()?</code>
 
−
 
 
−
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).
 
−
 
 
−
<pre class="brush:xquery">
 
−
json-doc("http://ip.jsontest.com/")('ip')  (: returns your IP address :)
 
−
</pre>
 
−
 
 
−
===fn:json-to-xml===
 
−
 
 
−
; Signatures
 
−
* <code>fn:json-to-xml($string as xs:string?) as node()?</code>
 
−
 
 
−
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].
 
−
 
 
−
<pre class="brush:xquery">
 
−
json-to-xml('{ "message": "world" }')
 
−
 
 
−
(: result:
 
−
<map xmlns="http://www.w3.org/2005/xpath-functions">
 
−
   <string key="message">world</string>
 
−
</map> :)
 
−
</pre>
 
−
 
 
−
===fn:xml-to-json===
 
−
 
 
−
; Signatures
 
−
* <code>fn:xml-to-json($node as node()?) as xs:string?</code>
 
−
 
 
−
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].
 
−
 
 
−
<pre class="brush:xquery">
 
−
(: returns "JSON" :)
 
−
xml-to-json(<string xmlns="http://www.w3.org/2005/xpath-functions">JSON</string>)
 
−
</pre>
 
−
 
 
−
==fn:sort==
 
−
 
 
−
; Signatures
 
−
* <code>fn:sort($input as item()*) as item()*</code>
 
−
* <code>fn:sort($input as item()*, $collation as xs:string?) as xs:anyAtomicType*)) as item()*</code>
 
−
* <code>fn:sort($input as item()*, $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*)) as item()*</code>
 
−
 
 
−
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.
 
−
 
 
−
<pre class="brush:xquery">
 
−
sort(reverse(1 to 3))                    (: yields 1, 2, 3 :),
 
−
reverse(sort(1 to 3))                    (: returns the sorted order in descending order :),
 
−
sort((3,-2,1), (), abs#1)                (: yields 1, -2, 3 :),
 
−
sort((1,2,3), (), function($x) { -$x })  (: yields 3, 2, 1 :),
 
−
sort((1,'a'))                            (: yields an error, as strings and integers cannot be compared :)
 
−
</pre>
 
−
 
 
−
==fn:contains-token==
 
−
 
 
−
; Signatures
 
−
* <code>fn:contains-token($input as xs:string*, $token as string) as xs:boolean</code>
 
−
* <code>fn:contains-token($input as xs:string*, $token as string, $collation as xs:string) as xs:boolean</code>
 
−
 
 
−
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:
 
−
 
 
−
<pre class="brush:xquery">
 
−
contains-token(('a', 'b c', 'd'), 'c')                (: yields true :)
 
−
<xml class='one two'/>/contains-token(@class, 'one')  (: yields true :)
 
−
</pre>
 
−
 
 
−
==fn:parse-ietf-date==
 
−
 
 
−
; Signature
 
−
* <code>fn:parse-ietf-date($input as xs:string?) as xs:string?</code>
 
−
 
 
−
Parses a string in the IETF format (which is widely used on the Internet) and returns a {{Code|xs:dateTime}} item:
 
−
 
 
−
<pre class="brush:xquery">
 
−
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 :)
 
−
</pre>
 
−
 
 
−
==fn:apply==
 
−
 
 
−
; Signatures
 
−
* <code>fn:apply($function as function(*), $arguments as array(*)) as item()*</code>
 
−
 
 
−
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:
 
−
 
 
−
<pre class="brush:xquery">
 
−
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 :)
 
−
</pre>
 
−
 
 
−
==fn:random-number-generator==
 
−
 
 
−
; Signatures
 
−
* <code>fn:random-number-generator() as map(xs:string, item())</code>
 
−
* <code>fn:random-number-generator($seed as xs:anyAtomicType) as map(xs:string, item())</code>
 
−
 
 
−
Creates a random number generator, using an optional seed. The returned map contains three entries:
 
−
 
 
−
* {{Code|number}} is a random double between 0 and 1
 
−
* {{Code|next}} is a function that returns another random number generator
 
−
* {{Code|permute}} is a function that returns a random permutation of its argument
 
−
 
 
−
The returned random generator is ''deterministic'': If the function is called twice with the same arguments and in the same execution scope, it will always return the same result.
 
−
 
 
−
Example:
 
−
 
 
−
<pre class="brush:xquery">
 
−
let $rng := fn:random-number-generator()
 
−
let $number := $rng('number')              (: returns a random number :)
 
−
let $next-rng := $rng('next')()            (: returns a new generator :)
 
−
let $next-number := $next-rng('number')    (: returns another random number :)
 
−
let $permutation := $rng('permute')(1 to 5) (: returns a random permutation of (1,2,3,4,5) :)
 
−
return ($number, $next-number, $permutation)
 
−
</pre>
 
−
 
 
−
==fn:format-number==
 
−
 
 
−
The function has been extended to support scientific notation:
 
−
 
 
−
<pre class="brush:xquery">
 
−
format-number(1984.42, '00.0e0')  (: yields 19.8e2 :)
 
−
</pre>
 
−
 
 
−
==fn:tokenize==
 
−
 
 
−
If no separator is specified as second argument, a string will be tokenized at whitespace boundaries:
 
−
 
 
−
<pre class="brush:xquery">
 
−
fn:tokenize("  a b c d")  (: yields "a", "b", "c", "d" :)
 
−
</pre>
 
−
 
 
−
==fn:trace==
 
−
 
 
−
The second argument can now be omitted:
 
−
 
 
−
<pre class="brush:xquery">
 
−
fn:trace(<xml/>, "Node: ")/node()  (: yields the debugging output "Node: <xml/>" :),
 
−
fn:trace(<xml/>)/node()            (: returns the debugging output "<xml/>" :)
 
−
</pre>
 
−
 
 
−
==fn:string-join==
 
−
 
 
−
The type of the first argument is now <code>xs:anyAtomicType*</code>, and all items will be implicitly cast to strings:
 
−
 
 
−
<pre class="brush:xquery">
 
−
fn:string-join(1 to 3)  (: yields the string "123" :)
 
−
</pre>
 
−
 
 
−
==fn:default-language==
 
−
 
 
−
Returns the default language used for formatting numbers and dates. BaseX always returns {{Code|en}}.
 
−
 
 
−
==Appendix==
 
−
 
 
−
The three functions <code>fn:transform</code>, <code>fn:load-xquery-module</code> and <code>fn:collation-key</code> may be added in a future version of BaseX as their implementation might require the use of additional external libraries.
 
−
 
 
−
=Binary Data=
 
−
 
 
−
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}}:
 
−
 
 
−
<pre class="brush:xquery">
 
−
xs:hexBinary('') < xs:hexBinary('bb'),
 
−
xs:hexBinary('aa') < xs:hexBinary('bb'),
 
−
max((xs:hexBinary('aa'), xs:hexBinary('bb'))) = xs:hexBinary('bb')
 
 
</pre>
 
</pre>
 +
|}
  
−
=Collations=
+
==array:sort==
  
−
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>:
+
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:sort|$array as array(*)|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*|array(*)}}<br/>
 +
|-
 +
| '''Summary'''
 +
| Returns a new array with sorted {{Code|$array}} members, using an optional {{Code|$collation}}. If a {{Code|$key}} function is supplied, it will be applied on all array members. The items of the resulting values will be sorted using the semantics of the {{Code|lt}} expression.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:sort(array { reverse(1 to 3) })</code> returns <code>[1, 2, 3]</code>
 +
* <code>array:sort([3,-2,1], (), abs#1)</code> returns <code>[1, -2, 3]</code>
 +
* <code>array:sort([1,2,3], (), function($x) { -$x })</code> returns <code>[3, 2, 1]</code>
 +
* <code>array:sort((1,'a'))</code> returns an error (strings and integers cannot be compared)
 +
|}
  
−
<pre class="brush:xquery">
+
=Errors=
−
declare default collation 'http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive';
 
−
'HTML' = 'html'
 
−
</pre>
 
  
−
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:
+
{| class="wikitable" width="100%"
−
 
+
! width="110"|Code
−
<pre class="brush:xquery">
+
|Description
−
(: returns 0 (both strings are compared as equal) :)
+
|-
−
compare('a-b', 'ab', 'http://www.w3.org/2013/collation/UCA?alternate=shifted')
+
|{{Code|FOAY0001}}
−
</pre>
+
|The specified index extends beyonds the bounds of an array.
−
 
+
|-
−
=Enclosed Expressions=
+
|{{Code|FOAY0002}}
−
 
+
|The specified length is less than zero.
−
''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:
+
|}
−
 
 
−
<pre class="brush:xquery">
 
−
declare function local:x() { () }; i
 
−
try { () } catch * { () },
 
−
element x { () },
 
−
text { () }
 
−
</pre>
 
−
 
 
−
With XQuery 3.1, the expression can be omitted. The following query is equivalent to the upper one:
 
−
 
 
−
<pre class="brush:xquery">
 
−
declare function local:x() { };
 
−
try { } catch * { },
 
−
element x { }
 
−
text { }
 
−
</pre>
 
  
 
=Changelog=
 
=Changelog=
  
 
;Version 8.6
 
;Version 8.6
 +
* Updated: [[#array:put|array:put]] collation argument was inserted between first and second argument.
  
−
* Updated: Collation argument was inserted between first and second argument.
+
;Version 8.5
 +
* Added: [[#array:put|array:put]]
  
 
;Version 8.4
 
;Version 8.4
−
 
+
* Removed: array:serialize (use fn:serialize instead)
−
* Added: [[#String Constructors|String Constructors]], [[#fn:default-language|fn:default-language]], [[#Enclosed Expressions|Enclosed Expressions]]
 
−
* Updated: [[#Adaptive Serialization|Adaptive Serialization]], [[#fn:string-join|fn:string-join]]
 
−
 
 
−
;Version 8.2
 
−
 
 
−
* Added: [[#fn:json-to-xml|fn:json-to-xml]], [[#fn:xml-to-json|fn:xml-to-json]].
 
−
 
 
−
;Version 8.1
 
−
 
 
−
* Updated: arrays are now based on a [http://en.wikipedia.org/wiki/Finger_tree Finger Tree] implementation.
 
  
 
Introduced with Version 8.0.
 
Introduced with Version 8.0.

Revision as of 18:38, 17 February 2020

This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1.

Conventions

All functions and errors in this module are assigned to the http://www.w3.org/2005/xpath-functions/array namespace, which is statically bound to the array prefix.

Functions

array:size

Signatures array:size($input as array(*)) as xs:integer
Summary Returns the number of members in $array. Note that because an array is an item, the fn:count function when applied to an array always returns 1.
Examples
  • array:size(array { 1 to 10 }) returns 10.
  • array:size([1 to 10]) returns 1, because the array contains a single sequence with 10 integers.

array:get

Signatures array:get($array as array(*), $position as xs:integer) as item()*
Summary Returns the $array member at the specified $position.
Errors FOAY0001: $position is not in the range 1 to array:size($array) inclusive.
Examples
  • array:get(array { reverse(1 to 5) }, 5) returns the value 1.

array:append

Signatures array:append($array as array(*), $member as item()*) as array(*)
Summary Returns a copy of $array with a new $member attached.
Examples
  • array:append([], 'member1') returns the array ["member1"].

array:subarray

Signatures array:subarray($array as array(*), $position as xs:integer) as array(*)
array:subarray($array as array(*), $position as xs:integer, $length as xs:integer) as array(*)
Summary Constructs a new array with with $length members of $array beginning from the specified $position.
The two-argument version of the function returns the same result as the three-argument version when called with $length equal to the value of array:size($array) - $position + 1.
Errors FOAY0001: $position is less than one, or if $position + $length is greater than array:size($array) + 1.
FOAY0002: $length is less than zero.
Examples
  • array:subarray(["a", "b", "c"], 2) returns the array ["b", "c"].

array:put

Signatures array:put($array as array(*), $position as xs:integer, $member as item()*) as array(*)
Summary Returns a copy of $array with $member replaced at the specified $position. Equivalent to $array => array:remove($position) => array:insert-before($position, $member).
Errors FOAY0001: $position is not in the range 1 to array:size($array) inclusive.
Examples
  • array:put(["a", "b", "c"], 2, "d") returns the array ["a", "d", "c"].

array:remove

Signatures array:remove($array as array(*), $positions as xs:integer*) as array(*)
Summary Returns a copy of $array without the member at the specified $positions.
Errors FOAY0001: A position is not in the range 1 to array:size($array) inclusive.
Examples
  • array:append(["a"], 1) returns the array [].

array:insert-before

Signatures array:insert-before($array as array(*), $position as xs:integer, $member as item()*) as array(*)
Summary Returns a copy of $array with one new $member at the specified $position. Setting $position to the value array:size($array) + 1 yields the same result as array:append($array, $insert).
Errors FOAY0001: $position is not in the range 1 to array:size($array) + 1 inclusive.
Examples
  • array:insert-before(["a"], 1, "b") returns the array ["b", "a"].

array:head

Signatures array:head($array as array(*)) as item()*
Summary Returns the first member of $array. This function is equivalent to the expression $array(1).
Errors FOAY0001: The array is empty.
Examples
  • array:head(["a", "b"]) returns "a".
  • array:head([["a", "b"], ["c", "d"]]) returns the array ["a", "b"].

array:tail

Signatures array:tail($array as array(*)) as array(*)
Summary Returns a new array with all members except the first from $array. This function is equivalent to the expression array:remove($array, 1).
Errors FOAY0001: The array is empty.
Examples
  • array:insert-before(["a"], 1, "b") returns the array ["b", "a"].

array:reverse

Signatures array:reverse($array as array(*)) as array(*)
Summary Returns a new array with all members of $array in reverse order.
Examples
  • array:reverse(array { 1 to 3 }) returns the array [3, 2, 1].

array:join

Signatures array:join($arrays as array(*)*) as array(*)
Summary Concatenates the contents of several $arrays into a single array.
Examples
  • array:join(()) returns the array [].
  • array:join((1 to 3) ! array { . }) returns the array [1, 2, 3].

array:flatten

Signatures array:flatten($items as item()*) as item()*
Summary Recursively flattens all arrays that occur in the supplied $items.
Examples
  • array:flatten(["a","b"]) returns the sequence "a", "b".
  • array:flatten([1,[2,3],4]]) returns the sequence 1, 2, 3, 4.

array:for-each

Signatures array:for-each($array as array(*), $function as function(item()*) as item()*) as array(*)
Summary Returns a new array, in which each member is computed by applying $function to the corresponding member of $array.
Examples The following query returns the array [2, 3, 4, 5, 6]: 
array:for-each(
  array { 1 to 5 },
  function($i) { $i + 1}
)

array:filter

Signatures array:filter($array as array(*), $function as function(item()*) as xs:boolean) as array(*)
Summary Returns a new array with those members of $array for which $function returns true.
Examples The following query returns the array [0, 1, 3]: 
array:filter(
  array { 0, 1, -2, 3, -4 },
  function($i) { $i > 0 }
)

array:fold-left

Signatures array:fold-left($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
Summary Evaluates the supplied $function cumulatively on successive members of the supplied $array from left to right and using $zero as first argument.
Examples The following query returns 55 (the sum of the integers 1 to 10): 
array:fold-left(
  array { 1 to 10 },
  0,
  function($a, $b) { $a + $b }
)

array:fold-right

Signatures array:fold-right($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
Summary Evaluates the supplied $function cumulatively on successive members of the supplied $array from right to left and using $zero as first argument.
Examples The following query is equivalent to the expression array:reverse(array { 1 to 5 }): 
array {
  array:fold-right(
    array { 1 to 5 },
    (),
    function($a, $b) { $b, $a }
  )
}

array:for-each-pair

Signatures array:for-each-pair($array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*) as array(*)
Summary Returns a new array obtained by evaluating the supplied $function for each pair of members at the same position in $array1 and $array2.
Examples The following query returns the array [5, 7, 9]: 
array:for-each-pair(
  array { 1 to 3 },
  array { 4 to 6 },
  function($a + $b) { $a + $b }
)

array:sort

Signatures array:sort($array as array(*)) as array(*)
array:sort($array as array(*), $collation as xs:string?) as array(*)
array:sort($array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*) as array(*)
Summary Returns a new array with sorted $array members, using an optional $collation. If a $key function is supplied, it will be applied on all array members. The items of the resulting values will be sorted using the semantics of the lt expression.
Examples
  • array:sort(array { reverse(1 to 3) }) returns [1, 2, 3]
  • array:sort([3,-2,1], (), abs#1) returns [1, -2, 3]
  • array:sort([1,2,3], (), function($x) { -$x }) returns [3, 2, 1]
  • array:sort((1,'a')) returns an error (strings and integers cannot be compared)

Errors

Code Description
FOAY0001 The specified index extends beyonds the bounds of an array.
FOAY0002 The specified length is less than zero.

Changelog

Version 8.6
  • Updated: array:put collation argument was inserted between first and second argument.
Version 8.5
Version 8.4
  • Removed: array:serialize (use fn:serialize instead)

Introduced with Version 8.0.

Retrieved from "http://docs.basex.org/index.php?title=XQuery_3.1&oldid=14837"