# XQuery/Using XQuery Functions
## Motivation

You would like to use an existing XQuery function. You need to be able to understand how functions work and how they are documented.

## Method

The XQuery 1.0 specification has many built-in functions for handling strings, URIs and other data. To use a built-in function you need to know what its inputs are and their data types and what form of output it creates.

## Understanding XQuery Parameters and Return Types

XQuery is a strongly typed language, so functions are usually carefully designed to work with a restricted set of data types. When you pass data into a function using a parameter, you must specify its type, using combinations of elements, nodes, items, sequences or any of the XML Schema data types. In addition to the data type, a suffix called an occurrence indicator, such as "+", "?" or "*", follows the data type to indicate whether a parameter is optional or could have multiple values. Here are the three occurrence indicators and their meanings:
* ? matches zero or one items
* * matches zero or more items
* + matches one or more items
Care should be taken to understand the difference between an argument as a single sequence and a repeating set of items.
There are around 111 built-in functions to the XQuery language, but many find that 10% of the XQuery functions are used 90% of the time. Here are some of the most commonly used functions:
Example: string-length("Hello") returns 5, since the string "Hello" is five characters long.
The function does not accept a sequence of values, just individual atomic values passed as separate arguments.
Example: concat('big', 'red', 'ball') returns "bigredball"
Example: string-join(('big', 'red', 'ball'), '-') returns "big-red-ball"
Note that string-join takes as its first argument a single sequence of items, whereas concat takes zero or more strings as arguments.

## Sample data types

* xs:date refers to the built-in atomic schema type named xs:date
* attribute? refers to an optional attribute node
* element refers to any element node
* element(po:shipto, po:address) refers to an element node that has the name po:shipto and has the type annotation po:address (or a schema type derived from po:address)
* element(*, po:address) refers to an element node of any name that has the type annotation po:address (or a type derived from po:address)
* element(customer) refers to an element node named customer with any type annotation
* schema-element(customer) refers to an element node whose name is customer (or is in the substitution group headed by customer) and whose type annotation matches the schema type declared for a customer element in the in-scope element declarations
* node* refers to a sequence of zero or more nodes of any kind
* item+ refers to a sequence of one or more nodes or atomic values

## Returning Results

Each XQuery function you write will return a result.
In the following example, the input is a sequence of 0 to many nodes and the output is a sequence of 0 to many nodes.
In the following example, the input is a single required node and the output is a single required node.
In the following example, the input is a single optional node and the output is a single optional node.

## Useful References

For the authoritative documentation of all the functions available in eXist, including those not defined in XQuery, see eXist XQuery Function Documentation
For detailed information about how to specify sequence types see XQuery Sequence Types
For the standard XQuery and XPath function library, you may also refer to XQuery 1.0 and XPath 2.0 Functions and Operators
See also the detailed documentation of functions with examples from noted XQuery expert Pricilla Walmsley in the FunctX XQuery Function Library