Module async_coap_uri::escape

URI percent encoding/decoding ("URI Escaping")

This module was written before the author was aware of the percent-encode crate. Nonetheless, it has some convenient features that are not present in that crate, so it remains in the X-URI crate for now.

It focuses solely on percent encoding/decoding of UTF8-encoded strings, treating all percent-encoded strings that would otherwise decode to invalid UTF8 as themselves invalid.

The primary interface to encoding and decoding is a provided trait that extends str: StrExt.

Percent encoding is performed by escape_uri(), which returns an iterator that escapes the string. Likewise, percent decoding is performed by unescape_uri().

As a special case, the trait also provides unescape_uri_in_place(), which performs in-place percent-decoding for a mutable string slice.

Usage Patterns

The iterators returned by escape_uri() and unescape_uri() both implement core::fmt::Display, and thus also implement std::string::ToString:

use async_coap_uri::prelude::*;
let escaped_string = "This needs escaping".escape_uri().to_string();

assert_eq!(&escaped_string, "This%20needs%20escaping");

Both methods also implent From<Cow<str>>:

use std::borrow::Cow;
use std::convert::From;
let escaped_cow_str = Cow::from("This needs escaping?+3".escape_uri());

assert_eq!(&escaped_cow_str, "This%20needs%20escaping%3F+3");

Changing Behavior

There is no one-size-fits-all escaping strategy for URIs: Some parts need to be excaped differently than others. For example, path segments must have the ? character escaped to %3F, but this character is perfectly acceptable in the query component. Also, query components have historically escaped the space character ( ) to the plus (+) character, so pluses need to be escaped to %2B.

By default, StrExt::escape_uri produces an iterator suitable for encoding path segments, but other cases are handled by calling a modifier method on the EscapeUri iterator:

let escaped_string = "This needs escaping?+3".escape_uri().for_query().to_string();

assert_eq!(&escaped_string, "This+needs+escaping?%2B3");

The EscapeUri iterator also provides the modifier methods for_fragment() and full() for encoding URI fragments and performing full percent encoding, respectively.

Skipping Slashes

The UnescapeUri iterator provides a modifier method for assisting in decoding the entire URI path component (as opposed to individual path segments) where encoded slashes (%2F) are not decoded, preserving the hierarchy:

let escaped_string = "/this/p%20a%20t%20h/has%2Fextra/segments";

let unescaped = escaped_string.unescape_uri().to_string();
assert_eq!(&unescaped, "/this/p a t h/has/extra/segments");

let unescaped = escaped_string.unescape_uri().skip_slashes().to_string();
assert_eq!(&unescaped, "/this/p a t h/has%2Fextra/segments");

Handling Encoding Errors

While escape_uri() cannot fail, an escaped string can contain errors. In situations where escaped characters cannot be properly decoded, the unescape_uri() iterator will by default insert replacement characters where errors are detected:

• Illegal escaped UTF8 errors are replaced with U+FFFD REPLACEMENT CHARACTER (�).
• Escaped ASCII control codes are decoded as Unicode Control Pictures like ␀ and ␊.
• Unescaped ASCII control codes are dropped entirely.

In cases where this is not appropriate, the iterator for unescape_uri() (UnescapeUri) provides the following methods:

• first_error(): Returns the location of the first detected encoding error, or None if there are no encoding errors.
• try_to_string(): Returns an unescaped String only if no encoding errors were present.
• try_to_cow(): Returns an unescaped [Cow<str>] only if no encoding errors were present.

Structs

EscapeUri	An iterator used to apply URI percent encoding to strings.
UnescapeUri	An iterator used to apply URI percent decoding to strings.

Traits

StrExt

Trait for str adding URI percent encoding/decoding