XPath/XQuery encode-for-uri function

Summary

Encodes reserved characters in a string that is intended to be used in the path segment of a URI.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $uri-part is the empty sequence, the function returns the zero-length string.

This function applies the URI escaping rules defined in section 2 of to the xs:string supplied as $uri-part. The effect of the function is to escape reserved characters. Each such character in the string is replaced with its percent-encoded form as described in .

Since recommends that, for consistency, URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings, this function must always generate hexadecimal values using the upper-case letters A-F.

Examples

The expression fn:encode-for-uri("http://www.example.com/00/Weather/CA/Los%20Angeles#ocean") returns "http%3A%2F%2Fwww.example.com%2F00%2FWeather%2FCA%2FLos%2520Angeles%23ocean".

The expression concat("http://www.example.com/", encode-for-uri("~bébé")) returns "http://www.example.com/~b%C3%A9b%C3%A9".

The expression concat("http://www.example.com/", encode-for-uri("100% organic")) returns "http://www.example.com/100%25%20organic".

Notes

All characters are escaped except those identified as "unreserved" by , that is the upper- and lower-case letters A-Z, the digits 0-9, HYPHEN-MINUS ("-"), LOW LINE ("_"), FULL STOP ".", and TILDE "~".

This function escapes URI delimiters and therefore cannot be used indiscriminately to encode "invalid" characters in a path segment.

This function is invertible but not idempotent. This is because a string containing a percent character will be modified by applying the function: for example 100% becomes 100%25, while 100%25 becomes 100%2525.