Crate async_coap_uri

Expand description

§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/sized¹ 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 a String, 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 like UriRef(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 &'static RelRef from a string literal.
rel_ref_format: Creates a Option<RelRefBuf> from the given string format and arguments.
uri: Creates a &'static Uri from a string literal.
uri_format: Creates a Option<UriBuf> from the given string format and arguments.
uri_ref: Creates a &'static UriRef from a string literal.
uri_ref_format: Creates a Option<UriRefBuf> from the given string format and arguments.

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 AnyUriRef with formatters; instantiated by AnyUriRef::display.
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 Aliases§

RelRefCow: Convenience type for Cow<'a, RelRef>.
UriCow: Convenience type for Cow<'a, Uri>.
UriRefCow: Convenience type for Cow<'a, UriRef>.

Crate async_coap_uriCopy item path