# EXSLT - str:encode-uri - Implementer Page

Version: 2 Status: new User Page: index.html XML Definition: str.encode-uri.xml Function Package: str.encode-uri.zip

#### Function Syntax

    string str:encode-uri(string, string, string?)

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.

An implementation of this extension function in the EXSLT str namespace must conform to the behaviour described in this document.

## Implementations

Built-in support for `str:encode-uri` is available in the following XSLT processors:

Processor | Processor Version | Implemented Version
--- | --- | ---
4XSLT, from 4Suite. | 0.12.0a3 | 1

The following implementations of `str:encode-uri` are available:

Language | Implemented Version | Creator | Date | Download
--- | --- | --- | --- | ---
Msxsl | 1 | Chris Bayes | 2001-06-26 | str.encode-uri.msxsl.xsl
Javascript | 1 | Chris Bayes | 2001-06-26 | str.encode-uri.js

## Change History

Previous Version: str.encode-uri.1.html

Version | Modified | By | Details
--- | --- | --- | ---
2 | 2002-12-02 | Mike Brown | Updated the function syntax to more closely reflect `xf:escape-uri()` in [XQFuncs].

http://www.exslt.org/str/functions/encode-uri/str.encode-uri.html last modified 2002-12-02