[−][src]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, orNone
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 |