XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

unparsed-text-available

Category:

Association and localisation of nodes and resources at runtime

Origin:

XSLT 2.0

Return value:

A xs:boolean Boolean value being true or false, depending on whether the unparsed-text() function called up with the same arguments would return a text string (a non-empty text resource).

Call/Arguments:

unparsed-text-available($URI-string?, $encoding-indication?)

$URI-string:

Optional. A xs:string string which lexically must have the form of a xs:anyURI URI string, but which must not contain a fragment identifier. If it is a relative URI, it is resolved according to the base URI of the static context. The resolved URI has to point at a resource readable as text. If the empty sequence is passed on as first argument, the function returns false.

$encoding-indication:

Optional. The second argument names the encoding of the external resource in order to enable its conversion into a string. According to RFC 2278, the encoding describes the binary coding of the character data (example: UTF-8, ISO-8859-1). If the desired encoding is not recognised or not supported by the processor, UTF-8 is used as standard encoding. If the empty sequence is passed on as second argument, the argument is ignored.

Purpose of use:

In XSLT 2.0 the unparsed-text-available() function is additionally provided to unparsed-text() in order to avoid aborts which result from calling unparsed-text() with erroneous arguments or useless external resources. The fact that also the encoding of the external resource is tested requires its actual reading in and processing (for instance in order to determine wrong character octets). The function accepts the same arguments like unparsed-text(), but returns a Boolean value.

This value is always true if the call of the partner function with the same arguments would not result in an error and returns a non-empty text resource.

In case the call leads to a potential error, false is returned. However, the return value is also false, if the first argument (the URI of the resource) is the empty sequence – because in this case, no non-empty text resource could be returned.

Remark: The call of unparsed-text() would »just« return an empty sequence (surely not always useful) and not result in an error; it would have been acceptable to determine true as return value. This incongruence was accepted in order to adapt the behaviour of unparsed-text-available() to the XPath function fn:doc-available().

The function is stable in the sense of the specification, which means at runtime for the same arguments it always results in an unchanged return value.

Example:

A test for availability of a resource for unparsed-text() may be executed in the scope of the same XPath expression by means of an if expression. Here, the example from unparsed-text() is extended accordingly:

However, this leads to the fact that the template outputs in each case a <result> ... </result> container, even if no resource is accessible (at least an error is avoided for this case). In order to avoid the output of an empty container, the example can be extended in the following:

In this example, too, a test is made whether unparsed-text() can be successfully applied. Only in this case, the template outputs a result. If an empty sequence is passed on as first argument, the unparsed-text-available() function also prevents by the return value false the instantiation of the instruction block and as a consequence, also the output of an empty <result></result> container.

Function definition:

XSLT 1.0:

The function is not available.

XSLT 2.0:

unparsed-text-available($href as xs:string?) as xs:boolean

unparsed-text-available($href as xs:string?, $encoding as xs:string?) as xs:boolean