XQuery 4.0: An XML Query Language

4.5 Functions

Functions in XQuery 4.0 arise in two ways:

• A function definition contains information about a family of functions with the same name and a defined arity range. These functions are in most cases known statically (they appear in the statically known function definitions), but there may be further function definitions that are known only dynamically (appearing in the dynamically known function definitions).

• Function items are XDM items that can be called using a dynamic function call. They are values that can be bound to variables, passed as arguments, returned as function results, and generally manipulated in the same way as other XDM values.

The functions defined by a statically known function definition can be invoked using a static function call. Function items corresponding to these definitions can also be obtained, as dynamic values, by evaluating a named function reference. Function items can also be obtained using the fn:function-lookup function: in this case the function name and arity do not need to be known statically, and the function definition need not be present in the static context, so long as it is in the dynamic context.

Static and dynamic function calls are described in the following sections.

let $incr := 1
let $f := function($i as xs:decimal) as xs:decimal { $i + $incr }
return $f(5)

let $vat := function() { @vat + @price }
return doc('wares.xml')/shop/article/$vat()

let $vat := function($art) { $art/@vat + $art/@price }
return doc('wares.xml')/shop/article/$vat(.)

let $ctx := doc('wares.xml')/shop/article
let $vat := function() { for $a in $ctx return $a/@vat + $a/@price }
return $vat()

let $vat := function { @vat + @price }
return $vat(doc('wares.xml')/shop/article)

(abs#1, round#1, floor#1, ceiling#1)(3.2)

csv-to-arrays( string-join(("a,b,c", "p,q,r", "x,y,z"), char(10)) ) (2)

4.14 Maps and Arrays

Most modern programming languages have support for collections of key/value pairs, which may be called maps, dictionaries, associative arrays, hash tables, keyed lists, or objects (these are not the same thing as objects in object-oriented systems). In XQuery 4.0, we call these maps. Most modern programming languages also support ordered lists of values, which may be called arrays, vectors, or sequences. In XQuery 4.0, we have both sequences and arrays. Unlike sequences, an array is an item, and can appear as an item in a sequence.

let $rectangle := {
  'height':    3,
  'width':     4,
  'area':      fn ($rect) { 
                  $rect?height × $rect?width 
               },
  'perimeter': fn ($rect) { 
                 2 × ($rect?height + $rect?width) 
               },
  'resize':    fn ($rect, $factor) { 
                  $rect 
                     => map:put('height', $rect?height × $factor)
                     => map:put('width', $rect?width × $factor)
               }
}

let $rectangle := {
  'height': 3,
  'width': 4,
  'area': fn { ?height × ?width }
}

for $map as map(*) in M
let $f as function(*) := $map?N                 
return $f($map, X, Y, ...)

let $lib := {
  'product': fn($map as map(*), $in as xs:double*) {
    if (empty( $in ))
    then 1
    else head($in) × $map =?> product(tail($in))
  }
}
return $lib =?> product((1.2, 1.3, 1.4))

declare record my:rectangle (
   height as xs:double,
   width as xs:double,
   children as my:rectangle* 
     := (),
   area as fn(my:rectangle) as xs:double 
     := fn{?height × ?width},
   resize as fn(my:rectangle, xs:double) as my:rectangle 
     := fn($rect, $factor) {
           $rect => map:put('height', $rect?height × $factor)
             => map:put('width', $rect?width × $factor)
             => map:put('children', $rect?children =?> resize($factor))
        },
   contents as fn(my:rectangle) as my:rectangle*
     := fn{?children}
);

4.24 Arrow Expressions

Arrow expressions apply a function (or more generally, a sequence of functions) to a value, using the value of the left-hand expression as the first argument to the function.

The arrow syntax is particularly helpful when applying multiple functions to a value in turn. For example, the following expression invites syntax errors due to misplaced parentheses:

tokenize((normalize-unicode(upper-case($string))),"\s+")

In the following reformulation, it is easier to see that the parentheses are balanced:

$string => upper-case() => normalize-unicode() => tokenize("\s+")

When the operator is written as =!>, the function is applied to each item in the sequence in turn. Assuming that $string is a single string, the above example could equally be written:

$string =!> upper-case() =!> normalize-unicode() =!> tokenize("\s+")

The difference between the two operators is seen when the left-hand operand evaluates to a sequence:

(1, 2, 3) => avg()

returns a value of only one item, 2, the average of all three items.

This example could also be written as using the pipeline operator as:

(1, 2, 3) -> avg(.)

By contrast, an expression using the mapping arrow operator:

(1, 2, 3) =!> avg()

would return the original sequence of three items, (1, 2, 3), each item being the average of itself.

There are two significant differences between the pipeline operator-> and the sequence arrow operator=>:

• The -> operator takes an arbitrary expression as its right-hand operand, whereas the => operator only accepts a function call.The -> operator takes an arbitrary expression as its right-hand operand, whereas the => operator requires the right-hand operand to be a function call.The -> operator takes an arbitrary expression as its right-hand operand, whereas the => operator only acceptsrequires the right-hand operand to be a function call.

• When the right hand operand is a function call, the first argument is omitted in the case of the => operator, but is included explicitly (as a context value expression, .) in the case of the -> operator.

The following example:

"The cat sat on the mat"
=> tokenize()
=!> concat(".")
=!> upper-case()
=> string-join(" ")

returns "THE. CAT. SAT. ON. THE. MAT.". The first arrow could be written either as => or =!> because the operand is a singleton; the next two arrows have to be =!> because the function is applied to each item in the tokenized sequence individually; the final arrow must be => because the string-join function applies to the sequence as a whole.

The following example introduces an inline function to the pipeline:

(1 to 5) =!> xs:double() =!> math:sqrt() =!> fn($a) { $a + 1 }() => sum()

This is equivalent to sum((1 to 5) ! (math:sqrt(xs:double(.)) + 1)).

The same effect can be achieved using a focus function:

(1 to 5) =!> xs:double() =!> math:sqrt() =!> fn { . + 1 }() => sum()

It could also be expressed using the mapping operator !:

(1 to 5) ! xs:double(.) ! math:sqrt(.) ! (. + 1) => sum()

The sequence arrow operator thus applies the supplied function to the left-hand operand as a whole, while the mapping arrow operator applies the function to each item in the value of the left-hand operand individually. In the case where the result of the left-hand operand is a single item, the two operators have the same effect.

The construct on the right-hand side of the arrow operator (=>) can either be a static function call, or a restricted form of dynamic function call. The restrictions are there to ensure that the two forms can be distinguished by the parser with limited lookahead. For a dynamic call, the function item to be called can be expressed as a variable reference, an inline function expression, a named function reference, a map constructor, or an array constructor. Any other expression used to return the required function item must be enclosed in parentheses.The construct on the right-hand side of the arrow operator (=>) can either be a static function call, or a restricted form of dynamic function call. The restrictions are there to ensure that the two forms can be distinguished by the parser with limited lookahead. For a dynamic call, the function item(s) to be called can be expressed as a variable reference, an inline function expression, a named function reference, a map constructor, or an array constructor. Any other expression used to return the required function item must be enclosed in parentheses.The construct on the right-hand side of the arrow operator (=>) can either be a static function call, or a restricted form of dynamic function call. The restrictions are there to ensure that the two forms can be distinguished by the parser with limited lookahead. For a dynamic call, the function item(s) to be called can be expressed as a variable reference, an inline function expression, a named function reference, a map constructor, or an array constructor. Any other expression used to return the required function item must be enclosed in parentheses.

Because the semantics of the arrow operator (=>) are defined in terms of static and dynamic functions calls, it is possible for the right-hand side to deliver a sequence of functions; the result of the arrow expression is the sequence-concatenation of the results of the function calls. For example,

"London" => (upper-case#1, lower-case#1, string-length#1)

returns the sequence ("LONDON", "london", 6).