Crate percent_encoding_rfc3986

Source
Expand description

URI percent encoding and decoding according to RFC 3986 (as opposed to urlspec).

This crate is a fork of percent_encoding with modifications to support RFC 3986. See below for differences.

URIs use special characters to indicate the parts of the request. For example, a ? question mark marks the end of a path and the start of a query string. In order for that character to exist inside a path, it needs to be encoded differently.

Percent encoding replaces reserved characters with the % escape character followed by a byte value as two hexadecimal digits. For example, an ASCII space is replaced with %20.

When encoding, the set of characters that can (and should, for readability) be left alone depends on the context. The ? question mark mentioned above is not a separator when used literally inside of a query string, and therefore does not need to be encoded. The AsciiSet parameter of percent_encode and utf8_percent_encode. lets callers configure this.

This crate deliberately does not provide many different sets. Users should consider in what context the encoded string will be used, read relevant specifications, and define their own set. This is done by using the add method of an existing set.

§Examples

use percent_encoding_rfc3986::{utf8_percent_encode, AsciiSet, CONTROLS};

/// https://url.spec.whatwg.org/#fragment-percent-encode-set
const FRAGMENT: &AsciiSet = &CONTROLS.add(b' ').add(b'"').add(b'<').add(b'>').add(b'`');

assert_eq!(utf8_percent_encode("foo <bar>", FRAGMENT).to_string(), "foo%20%3Cbar%3E");

§What’s the difference when compared to percent_encoding?

§Encoding differences

The percent_encoding crate uses percent encoding according to URL spec. This crate uses RFC 3986 instead. The difference between them is RFC 3986 mandates that % character is always escaped while URL spec mandates %invalid to be decoded as %invalid - thus ignoring percent decoding if % sign is NOT followed by two hexadecimal digits.

Whether you choose one or the other depends entirely on the format you’re parsing. However, if you are also defining the format, please consider preferring RFC 3986 over URL spec. The author of this crate believes that silently ignoring weird strings leads to more problems than erroring clearly. It’d not be surprising if it even caused security vulnerabilities.

That being said this crate was actually motivated by the need to decode RFC 3986 encoding and not by philosophical differences.

§API differences

The API of this crate is very close to the API of percent_encoding. The only notable difference is percent_decode returning Result. It is not the goal of this crate to stay as close as possible to percent_encoding but it turns out percent_encoding has a good API and there’s little reason to change it at least now.

§Cargo features of this crate

  • alloc - turned on by default, enables integration with types from the alloc crate such as Vec<u8>, String, and Cow<'a, str>.
  • std - implements std::error::Error for error types. Implies alloc

Structs§

Enums§

Constants§

  • CONTROLS
    The set of 0x00 to 0x1F (C0 controls), and 0x7F (DEL).
  • NON_ALPHANUMERIC
    Everything that is not an ASCII letter or digit.

Functions§