XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (556 page)

Many string manipulations that can be done using
ends-with()
(but not those that rely on collations) can also be achieved using the
matches()
function, which allows regular expressions to be used. The above example could also be coded using
replace()
:

See Also

contains()
on page 730

matches()
on page 828

starts-with()
on page 875

string-length()
on page 880

substring()
on page 883

error

The
error()
function can be called when the application detects an error condition; it causes evaluation of the XPath expression as a whole to fail. In XSLT, this will cause the entire transformation to fail.

Signature

The
error()
function in fact has four signatures:

• error()
  
• error(code)
  
• error(code, description)
  
• error(code, description, object)
  

The
code
argument can be an empty sequence if the
description
is present, but not otherwise.

Effect

The
error()
function always reports an error, it never returns a result.

Calling the
error()
function causes the XPath expression as a whole to fail, since XPath provides no try/catch mechanism for catching errors.

Under XSLT, calling the error function causes the whole transformation to fail: the effect is the same as

.

The various arguments can be used to provide information about the error. The exact way in which this information is used depends on the implementation.

Error codes are defined as QNames. The error codes defined by the system (such as
XPTY0004
for the type error that occurs when calling a function with incorrect arguments) are technically local names associated with the namespace
http://www.w3.org/2005/xqt-errors
. User-defined error codes should be in a user-owned namespace. There is an assumption that a calling application will have access to these error codes, either as a QName, or as a URI with a fragment identifier (for example
http://www.w3.org/2005/xqt-errors#XPTY0004
). However, the details depend on the API design.

Examples

Expression	Result
error()	Causes termination, with no explanation
error(xs:QName(“docbook: invalid-page-ref”))	Causes termination, with an error code invalid-page-ref in the namespace associated with the docbook prefix
error((), “Invalid parameter value”)	Causes termination, with a specified message, but no specified error code

Usage

The
error()
function is useful when the application encounters a condition that it is not designed to handle, for example, invalid arguments passed to a function.

Every runtime error defined by the XSLT and XPath suite of specifications itself has a short code, such as FORG0001. These codes (which are listed in Appendix B) are all to be regarded as the local part of a QName, whose namespace URI is
http://www.w3.org/2005/xqt-errors
. The specification suggests that this code might be made available to applications via the API of the XPath processor, though there is nothing prescriptive about this. It makes sense for vendor-defined and user-defined error codes to fit into the same scheme of things by using
xs:QName
values as error values, with an explicit namespace. An implementation that allows error messages to be localized will typically provide some way of using the
xs:QName
as a code to look up a message in a file of message texts appropriate to the user's language.

This error-handling scheme is fine for product-quality applications that need to be delivered to a large number of users, localized to different languages, and so on. If you're just writing a simple stylesheet that's going to be used once and thrown away, it's all rather over the top. In this case, you can just pass a message that says what's gone wrong in the form of a string.

See Also

trace()
on page 896

in Chapter 6 on page 386

Error codes: Appendix B

escape-html-uri

The
escape-html-uri()
function applies the URI escaping conventions defined in the HTML 4.0 specification to an input string.

For example,
escape-html-uri(‘http://www.wikipedia.org/Gerhard Schröder’)
returns
http://www.wikipedia.org/Gerhard Schr%C3%B6der
.

Signature

Effect

The result string is formed from the input string by escaping non-ASCII characters according to the rules defined in the HTML 4.0 specification. Non-ASCII characters are escaped by first encoding them in UTF-8, then representing each byte of the UTF-8 encoding in the form %HH where HH represents the byte as two hexadecimal digits. The digits A–F are always in upper case.