Functions

Array Functions

XPath ordered array operations — like List<T> in .NET

#Array Functions

Arrays are ordered, indexable collections introduced in XPath 3.1. Sequences are flat, but arrays can be nested. An array can contain other arrays.

All array functions are in the array: namespace.

For C# developers: an XPath array resembles List<object> in C#. It also matches the structure of a JSON array.

#Sequences vs Arrays

#Contents

• Construction

• Access

• Modification

• Transformation

• Searching

#Construction

#Array Literals

[1, 2, 3]                    (: array of integers :)
["a", "b", "c"]              (: array of strings :)
[[1, 2], [3, 4]]             (: nested arrays :)
[]                            (: empty array :)
                                    

#array:build()

Builds an array from a sequence using a function. New in XPath 4.0.

Signature: array:build($seq as item()*, $fn as function(item()) as item()*) as array(*)

array:build(1 to 5, function($n) { $n * $n })
=> [1, 4, 9, 16, 25]
                                      

C# equivalent: Enumerable.Range(1, 5).Select(n => n * n).ToList()

#array:join()

Concatenates multiple arrays into one.

Signature: array:join($arrays as array(*)*) as array(*)

array:join(([1, 2], [3, 4], [5]))   => [1, 2, 3, 4, 5]
                                        

C# equivalent: lists.SelectMany(x => x).ToList()

#Access

#array:size()

Returns the number of members.

array:size([10, 20, 30])   => 3
array:size([])              => 0
                                          

C# equivalent: list.Count

#array:get()

Returns the member at a position (1-based).

array:get(["a", "b", "c"], 2)   => "b"
                                            

Shorthand: $arr?2 — the lookup operator works on arrays with integer keys.

C# equivalent: list[1] (0-based in C#)

#array:head() / array:tail() / array:foot() / array:trunk()

Same semantics as their sequence counterparts:

array:head([1, 2, 3])    => 1
array:tail([1, 2, 3])    => [2, 3]
array:foot([1, 2, 3])    => 3         (: XPath 4.0 :)
array:trunk([1, 2, 3])   => [1, 2]    (: XPath 4.0 :)
                                              

#array:subarray()

Extracts a contiguous slice.

array:subarray([10, 20, 30, 40, 50], 2, 3)   => [20, 30, 40]
                                                

#array:slice()

Advanced slicing with start, stop, step. New in XPath 4.0.

array:slice([1, 2, 3, 4, 5, 6, 7, 8], 2, 7, 2)   => [2, 4, 6]
                                                  

#Modification

Arrays are immutable. These functions return new arrays.

#array:put()

Returns a new array with the value at a position replaced.

array:put(["a", "b", "c"], 2, "X")   => ["a", "X", "c"]
                                                    

C# equivalent: list[1] = "X" (but immutable)

#array:append()

Appends a member to the end.

array:append([1, 2], 3)   => [1, 2, 3]
                                                      

C# equivalent: list.Add(3) (immutable version)

#array:insert-before()

Inserts a member at a position.

array:insert-before([1, 2, 3], 2, 99)   => [1, 99, 2, 3]
                                                        

#array:remove()

Removes the member at a position.

array:remove([1, 2, 3], 2)   => [1, 3]
                                                          

#array:reverse()

array:reverse([1, 2, 3])   => [3, 2, 1]
                                                            

#Transformation

#array:for-each()

Applies a function to each member.

array:for-each([1, 2, 3], function($n) { $n * 2 })
=> [2, 4, 6]
                                                              

C# equivalent: list.Select(n => n * 2).ToList()

#array:filter()

Keeps members where the predicate is true.

array:filter([1, 2, 3, 4, 5], function($n) { $n mod 2 = 0 })
=> [2, 4]
                                                                

C# equivalent: list.Where(n => n % 2 == 0).ToList()

#array:fold-left() / array:fold-right()

Reduces an array to a single value.

array:fold-left([1, 2, 3, 4], 0, function($acc, $n) { $acc + $n })
=> 10
                                                                  

C# equivalent: list.Aggregate(0, (acc, n) => acc + n)

#array:for-each-pair()

Applies a function to pairs of members from two arrays.

array:for-each-pair([1, 2, 3], [10, 20, 30],
  function($a, $b) { $a + $b })
=> [11, 22, 33]
                                                                    

C# equivalent: a.Zip(b, (x, y) => x + y).ToList()

#array:sort() / array:sort-by()

array:sort(["banana", "apple", "cherry"])
=> ["apple", "banana", "cherry"]
array:sort-by($books, function($b) { $b?price })
                                                                      

#array:flatten()

Recursively flattens nested arrays into a sequence.

array:flatten([[1, 2], [3, [4, 5]]])   => (1, 2, 3, 4, 5)
                                                                        

C# equivalent: list.SelectMany(x => x is IEnumerable e ? e.Cast<object>() : new[] { x })

#Searching

#array:index-of()

Returns positions where a value appears. New in XPath 4.0.

array:index-of(["a", "b", "c", "b"], "b")   => (2, 4)
                                                                          

#array:index-where()

Returns positions where a predicate is true. New in XPath 4.0.

array:index-where([3, 1, 4, 1, 5], function($n) { $n > 3 })
=> (3, 5)
                                                                            

#Conversion

#array:members()

Converts an array to a sequence of its members (each wrapped in a single-item array). New in XPath 4.0.

#array:items()

Converts an array to a flat sequence. New in XPath 4.0.

array:items([1, 2, 3])   => (1, 2, 3)
                                                                              

#array:of-members()

Creates an array from a sequence of single-item arrays. New in XPath 4.0.