.. _error:

=====
error
===== 

Raises a custom error

Description
~~~~~~~~~~~
The fn:error function allows you to stop execution of the query, with a specific 
error message. This is useful if an unexpected or invalid condition exists, such 
as a missing or invalid data item. You can incorporate calls to the fn:error 
function in your query to signal such problems to the query user.

It is implementation-dependent how a processor will use the optional 
$description and $error-object arguments. Most processors will report the 
$description as part of the error message to the user.

Some processors may report the error name as a URI, where the local part is a 
fragment identifier, as in http://datypic.com/err#ProdNumReq.

The fn:error function is the same function that the processor calls implicitly 
whenever there is an error during query evaluation. The return type of none is 
only used for the fn:error function and is not available to query authors. It 
simply means that the fn:error function never returns any value; evaluation of 
the query stops once the fn:error function is called.

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - **Parameters**
     - **Description**
   * - error:string()
     - a qualified name for the error
   * - description:string()
     - a description of the error
   * - error-object:item()
     - the item(s) that raised the error

Examples
~~~~~~~~
.. list-table::
   :widths: 25 25 50
   :header-rows: 1

   * - **XPath**
     - **Results**
     - **Explanation**
   * - error()
     - Error
     - 
   * - error(xs:QName('dty:ProdNumReq'))
     - Error
     - Assumes the dty prefix has been declared.
   * - error(QName('http://datypic.com/err', 'ProdNumReq'), 'Missing number.')
     - Error
     - 
   * - error(QName('http://datypic.com/err', 'ProdNumReq'), 'Missing number.', $prod)
     - Error
     -