[−][src]Crate async_coap_uri
Safe, In-place URI Abstraction
This crate provides safe, efficient, full-featured support for using and manipulating Uniform Resource Identifiers.
What makes this crate unique is that it provides URI-specific types that have the same
unsized/sized1 type duality that is used for &str
/String
, except with specific
guarantees on the content, as well as convenient domain-specific methods to access the
URI components. The API was designed to be easy-to-use while making as few
heap allocations as possible. Most common operations require no allocations at all,
and those that do are provided as a convenience rather than a fundamental requirement.
For example, you can parse and fully percent-decode a URI without doing a single allocation.
Similar to how you can specify a &'static str
inline as a string literal,
you can specify in-line "URI literals" that are checked for well-formedness at compile
time.
Important Types
This crate provides three fundamental types named after their IETF-RFC3986 counterparts:
URI-references are contained in the unsized string slice
subtype &UriRef
,with UriRefBuf
being the sized, heap-allocated version. This
is the most flexible and commonly used type, since it can contain either a URI
(like "http://example.com/
") or a relative-reference (Like "/a/b/c?q=foo
").
URI-reference literals for this type can be created using the uri_ref!
macro.
Actual full URIs (like "http://example.com/
") can be contained in the unsized
string slice subtype &Uri
,with UriBuf
being the sized, heap-allocated version.
This type is less flexible than UriRef
because it cannot hold a relative-reference:
if you have a &Uri
, you are guaranteed that it does not contain a relative-reference.
URI literals for this type can be created using the uri!
macro.
Relative-references (Like "/a/b/c?q=foo
") are contained in the
unsized string slice
subtype &RelRef
,with RelRefBuf
being the sized, heap-allocated version.
This type is less flexible than UriRef
because it cannot hold a full URI.
If you have a &RelRef
, you are guaranteed that it can only contain a path, query,
and/or fragment.
Relative-reference literals for this type can be created using the rel_ref!
macro.
Each type above provides methods for accessing the individual URI components in both raw and percent-decoded form. Additionally, they also provide iterator accessors for parsing path segments and query items—again both in raw and percent-decoded forms.
In some cases it can be more efficient to pre-compute the offsets of all of the URI components
rather than recalculate them individually, as the methods on the above types do.
For such cases, UriRawComponents
pre-computes each component of the URI internally,
allowing for more efficient repeated access. The type uses no memory allocations and is
scoped to the lifetime of the type that was used to create it.
A common trait—AnyUriRef
—for all of these types (Including UriRawComponents
) is
provided to make usage in generic contexts easier by allowing you to pass a borrowed reference
to of the above types as an argument.
Network Path Support
This crate aims for complete IETF-RFC3986 compliance while still being fast and efficient, but there is one part where it deviates very slightly: network paths.
A network path is essentially a full URI without a scheme, but with an authority.
For example, //example.com/a/b/c?q=123#body
is a network path.
According to IETF-RFC3986 section 4.2, network paths are relative-references.
However, this crate considers them to belong to
&Uri
/UriBuf
, not &RelRef
/RelRefBuf
as IETF-RFC3986 would imply.
This was done to simplify typical usage patterns by guaranteeing that a
&RelRef
/RelRefBuf
will never have a scheme or an authority component.
Casting and Deref
UriRef
implements Deref<Target=str>
, allowing you to use all of the
non-mutating methods from str
, like len()
. as well as create new string slices using
the [begin..end]
syntax. A &UriRef
can be cast to a &str
for free via the method
UriRef.as_str()
.
Uri
implements Deref<Target=UriRef>
, allowing you to use a &Uri
anywhere a &UriRef
is called for, and since UriRef
implements Deref<Target=str>
,
you can also use all of the str
methods, too. A &Uri
can be cast to a &UriRef
for
free via the method Uri.as_uri_ref()
, and likewise to a &str
via the method Uri.as_str()
.
You might think that RelRef
would implement Deref<Target=UriRef>
, too, but this actually
isn't safe. So while there is a RelRef.as_uri_ref()
, it returns a Cow<UriRef>
instead of
a &UriRef
. For more information, see this section.
URI "Literals"
For cases where you need a URI "literal", you can use the uri_ref!
, rel_ref!
,
and/or uri!
macros:
use async_coap_uri::prelude::*; let uri: &Uri = uri!("http://example.com/foo/bar/"); let (abs_part, rel_part) = uri.split(); assert_eq!(uri!("http://example.com"), abs_part); assert_eq!(rel_ref!("/foo/bar/"), rel_part);
These "literals" are checked for correctness at compile time:
// This will not compile. let x = uri!("%00 invalid %ff");
This unsized/sized pattern is useful because there are often cases where you would want to have a method or function take a URI as an argument. If you just passed a
&str
or aString
, you would need to verify that the URI was well-formed each time the method or function was called. You could fix this by creating a wrapper struct (something likeUriRef(String)
, which is similar to rust-url does it), but this requires the use of alloc and is inefficient in many cases, so this crate uses the unsized/sized pattern. ↩
Modules
escape | URI percent encoding/decoding ("URI Escaping") |
Macros
rel_ref | Creates a |
rel_ref_format | Creates a |
uri | Creates a |
uri_format | Creates a |
uri_ref | Creates a |
uri_ref_format | Creates a |
Structs
ParseError | URI parse error type. |
RelRef | Unsized string-slice type guaranteed to contain a well-formed IETF-RFC3986 relative reference. |
RelRefBuf | Sized, heap-allocated string type guaranteed to contain a well-formed IETF-RFC3986 relative-reference. |
Uri | Unsized string-slice type guaranteed to contain a well-formed IETF-RFC3986 URI or network path. |
UriBuf | Sized, heap-allocated string type guaranteed to contain a well-formed IETF-RFC3986 URI or network path. |
UriDisplay | Helper class to assist with using |
UriRawComponents | Struct that holds parsed URI components. |
UriRef | Unsized string-slice type guaranteed to contain a well-formed IETF-RFC3986 URI-reference. |
UriRefBuf | Sized, heap-allocated string type containing either a URI or a relative-reference. |
UriUnescapeBuf | Experimental: In-place unescaping iteration helper |
Enums
ResolveError | Error type for resolving a target URI against a base URI. |
UriType | Enum describing the type of a URI. |
Traits
AnyUriRef | Trait for objects that represent logical URI-references. Useful for generic programming. |
Type Definitions
RelRefCow | Convenience type for |
UriCow | Convenience type for |
UriRefCow | Convenience type for |