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

fn:encode-for-uri

Category:

String functions – analysis and manipulation

Origin:

XPath 2.0

Return value:

A xs:string string in which special characters (reserved characters) are encoded according to the rules of the URI encoding.

Call/Arguments:

fn:encode-for-uri($inputString)

$inputString:

An input string xs:string within which special characters shall be encoded for the use as URI according to the rules of the URI encoding (see RFC 3986, section 2). The function returns the empty string for an empty input sequence.

Purpose of use:

The fn:encode-for-uri() function processes a string passed on to it and returns the string in encoded form so that it can be used as URI string. Reserved characters are replaced by escape sequences encoded to hexadecimal – the space character, for example, is replaced by %20. It should be noted that only those characters are not escaped which are regarded as »unreserved«. Those are digits, letters and various punctuation marks used within URI strings like hyphen-minus, full stop/period, underscore and tilde:

unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

However, other characters used as delimiters, for example colon and slash, are escaped – threrefore the function is considered as »non idempotent«. This means it cannot be applied safely multiple times to the same string (because the escape sequences, in turn, are escaped):

fn:encode-for-uri(fn:encode-for-uri($string)) => problem!

The same problem arises if a string already URI encoded, a string with a slash as path delimiter or an absolute URI string is passed on:

fn:encode-for-uri('http://www.example.org/') unintentionally results in 'http%3A%2F%2Fwww.example.org%2F' because the slashes and the colon contained in the string are replaced by escape sequences.

Since the percent sign also does not belong to the unreserved characters, it is escaped in cases of doubt, even though it is part of an escape sequence:

fn:encode-for-uri('an%20example') results in 'an%2520example'. Here the percent sign with which the escape sequence for a space character begins is escaped once again.

So, the function does not pass on a correct URI string in a transparent manner. The function should only be used in the context of the construction of an URI which, for example, is created by the combination of two substrings. One of the substrings is already an absolute or a relative URI and only the second string concatenated with the first has to be escaped:

fn:concat( 'http://www.example.org/',

encode-for-uri('~my account')

)

results in: 'http://www.example.org/~my%20account'.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:encode-for-uri($uri-part as xs:string?) as xs:string

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany