xkr.us/articles/javascript

Comparing escape(), encodeURI(), andencodeURIComponent()

The purpose of this article is to examine the differences between these three methods and decide on the appropriate times to use each.

escape() method

Defined in: JavaScript 1.0

Descriptions

MSDN JScript Reference [REF]

The escape method returns a string value (in Unicode format) that contains the contents of [the argument]. All spaces, punctuation, accented characters, and any other non-ASCII characters are replaced with %xx encoding, where xx is equivalent to the hexadecimal number representing the character. For example, a space is returned as "%20."

Mozilla Developer Core Javascript Guide [REF]

The escape and unescape functions let you encode and decode strings. The escape function returns the hexadecimal encoding of an argument in the ISO Latin character set. The unescape function returns the ASCII string for the specified hexadecimal encoding value.

Example

The easiest way to understand the behavior is to see it:

escape('~!@#$%^&*(){}[]=:/,;?+\'"\\'): -->

encodeURI() method

Defined in: JavaScript 1.5

Descriptions

MSDN JScript Reference [REF]

The encodeURI method returns an encoded URI. If you pass the result to decodeURI, the original string is returned. The encodeURI method does not encode the following characters: ":", "/", ";", and "?". Use encodeURIComponent to encode these characters.

Mozilla Developer Core Javascript Guide [REF]

Encodes a Uniform Resource Identifier (URI) by replacing each instance of certain characters by one, two, or three escape sequences representing the UTF-8 encoding of the character.

Example

The easiest way to understand the behavior is to see it:

encodeURI('~!@#$%^&*(){}[]=:/,;?+\'"\\'): -->

encodeURIComponent() method

Defined in: JavaScript 1.5

Descriptions

MSDN JScript Reference [REF]

The encodeURIComponent method returns an encoded URI. If you pass the result to decodeURIComponent, the original string is returned. Because the encodeURIComponent method encodes all characters, be careful if the string represents a path such as /folder1/folder2/default.html. The slash characters will be encoded and will not be valid if sent as a request to a web server. Use the encodeURI method if the string contains more than a single URI component.

Mozilla Developer Core Javascript Guide [REF]

Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, or three escape sequences representing the UTF-8 encoding of the character.

Example

The easiest way to understand the behavior is to see it:

encodeURIComponent('~!@#$%^&*(){}[]=:/,;?+\'"\\'): -->

All three of them

-->

escape():

encodeURI():

encodeURIComponent():

Summary: What does this mean?

When to use which?

The escape() method does not encode the + character which is interpreted as a space on the server side as well as generated by forms with spaces in their fields. Due to this shortcoming and the fact that this function fails to handle non-ASCII characters correctly, you should avoid use of escape() whenever possible. The best alternative is usually encodeURIComponent().

escape() will not encode: @*/+

Use of the encodeURI() method is a bit more specialized than escape() in that it encodes for URIs [REF] as opposed to the querystring, which is part of a URL. Use this method when you need to encode a string to be used for any resource that uses URIsand needs certain characters to remain un-encoded. Note that this method does not encode the ' character, as it is a valid character within URIs.

encodeURI() will not encode: ~!@#$&*()=:/,;?+'

Lastly, the encodeURIComponent() method should be used in most cases when encoding a single component of a URI. This method will encode certain chars that would normally be recognized as special chars for URIs so that many components may be included. Note that this method does not encode the ' character, as it is a valid character within URIs.

encodeURIComponent() will not encode: ~!*()'

References

MSDN JScript Reference - escape(), encodeURI(), encodeURIComponent()

Mozilla Developer Core Javascript Guide - escape(), encodeURI(), encodeURIComponent()

ASCII Table - http://www.asciitable.com/

W3C's URIs, URLs, and URNs: Clarifications and Recommendations 1.0 - http://www.w3.org/TR/uri-clarification/

Credits: yossarian and Jumper on #javascript (EFNet) for editing and consulting; Joseph Tatroult for additional test cases.

Brad Fults