EXSLT - str:encode-uri - Implementer Page

This function applies the URI escaping rules defined in section 2 of [RFC 2396], as amended by [RFC 2732], to the string supplied as the first argument, which typically represents all or part of a URI, URI reference or IRI. The effect of the function is to replace any special character in the string by an escape sequence of the form %xx%yy..., where xxyy... is the hexadecimal representation of the octets used to represent the character in US-ASCII for characters in the ASCII repertoire, and a different character encoding for non-ASCII characters.

The set of characters that are escaped depends on the setting of the second argument.

If the second argument is true, all characters are escaped other than lower case letters a-z, upper case letters A-Z, digits 0-9, and the characters referred to in [RFC 2396] as "marks": specifically, "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")". The "%" character itself is escaped only if it is not followed by two hexadecimal digits (that is, 0-9, a-f, and A-F).

If the second argument is false, the behavior differs in that characters referred to in [RFC 2396] and [RFC 2732] as reserved characters are not escaped. These characters are ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," | "[" | "]".

[RFC 2396] does not define whether escaped URIs should use lower case or upper case for hexadecimal digits. To ensure that escaped URIs can be compared using string comparison functions, this function must always use the upper-case letters A-F.

Generally, the second argument should be set to true when escaping a string that is to form a single part of a URI, URI reference or IRI, and to false when escaping an entire URI, URI reference or IRI.

The character encoding used as the basis for determining the octets depends on the setting of the optional third argument. If the argument is given, it should be an encoding name listed in [Charsets], and may be given case-insensitively. The default encoding, if the argument is not given, is UTF-8. UTF-8 is the only encoding required to be supported by an implementation of this function. If the given encoding is not supported, then the function returns an empty string. If the encoding is supported but a character in the string cannot be represented in that encoding, then the character is escaped as if it were a question mark ("%3F").

Examples:

str:encode-uri('http://www.example.com/my résumé.html',false())
returns
http://www.example.com/my%20r%E9sum%C3%A9.html

str:encode-uri('http://www.example.com/my résumé.html',true())
returns
http%3A%2F%2Fwww.example.com%2Fmy%20r%C3%A9sum%C3%A9.html

str:encode-uri('http://www.example.com/my résumé.html',false(),'iso-8859-1')
returns
http://www.example.com/my%20r%E9sum%E9.html if the implementation supports iso-8859-1, or an empty string otherwise.