Struct async_coap_uri::UriRef

pub struct UriRef(_);

Unsized string-slice type guaranteed to contain a well-formed IETF-RFC3986 URI-reference.

From IETF-RFC3986 Section 4.1:

[A] URI-reference is used to denote the most common usage of a resource identifier.

URI-reference = URI / relative-ref

A URI-reference is either a URI or a relative reference. If the URI-reference's prefix does not match the syntax of a scheme followed by its colon separator, then the URI-reference is a relative reference.

UriRef is similar to str in that it is an unsized type and is generally only seen in its borrowed form: &UriRef. The big difference between str and UriRef is that UriRef guarantees that it contains a well-formed URI-reference.

The sized counterpart is UriRefBuf, but the underlying data can be owned by just about anything.

Examples

String literals can be made into URI-reference using the uri_ref! macro:

use async_coap_uri::prelude::*;

let uri = uri_ref!("http://example.com/test");

Depending on your needs, you can access the raw (escaped) components individually, or calculate them all at once using UriRawComponents:

// Accessed and calculated individually...
assert_eq!(Some("http"), uri.scheme());
assert_eq!(Some("example.com"), uri.raw_authority());
assert_eq!("/test", uri.raw_path());

// ...or calculate all of them at once.
let components = uri.components();
assert_eq!(Some("http"), components.scheme());
assert_eq!(Some("example.com"), components.raw_authority());
assert_eq!("/test", components.raw_path());

Methods

impl UriRef

pub fn from_str(s: &str) -> Result<&UriRef, ParseError>

Attempts to convert a string slice into a &UriRef, returning Err(ParseError) if the string slice contains data that is not a valid URI reference.

Example:

use async_coap_uri::prelude::*;
assert_eq!(UriRef::from_str("http://example.com"), Ok(uri_ref!("http://example.com")));
assert_eq!(UriRef::from_str("/a/b/c"), Ok(uri_ref!("/a/b/c")));
assert_eq!(UriRef::from_str("I N V A L I D").err().unwrap().span(), Some(1..2));

pub fn is_str_valid<S: AsRef<str>>(s: S) -> bool

Determines if the given string can be considered a valid URI reference.

The key difference between this and Uri::is_str_valid is that this function will return true for relative-references like /a/b/c, whereas Uri::is_str_valid would return false.

Example:

use async_coap_uri::UriRef;
assert!(UriRef::is_str_valid("http://example.com"));
assert!(UriRef::is_str_valid("/a/b/c"));
assert!(!UriRef::is_str_valid("Not a URI or relative reference"));

pub const fn as_str(&self) -> &str

Returns this URI-reference as a string slice.

pub fn as_uri(&self) -> Option<&Uri>

Attempts to interpret this &UriRef as a &Uri, returning None if this UriRef doesn't contain a proper URI.

pub fn as_rel_ref(&self) -> Option<&RelRef>

Attempts to interpret this &UriRef as a &RelRef, returning None if this UriRef doesn't contain a relative-reference.

impl UriRef

Indexing Methods

pub fn heir_part_start(&self) -> usize

Returns the index to the start of heir-part, as defined in IETF-RFC3986.

pub fn path_start(&self) -> usize

Returns the index to the first character in the path. Will return len() if there is no path, query, or fragment. If the return value is zero, then self is guaranteed to be a relative reference.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("a").path_start(),               0);
assert_eq!(uri_ref!("a/b/c?blah#frag").path_start(), 0);
assert_eq!(uri_ref!("/a").path_start(),              0);
assert_eq!(uri_ref!("//foo/?bar").path_start(),      5);
assert_eq!(uri_ref!("http://a/#frag").path_start(),  8);
assert_eq!(uri_ref!("http://a").path_start(),  8);

pub fn path_end(&self) -> usize

Returns the index of the end of the path

pub fn query_start(&self) -> Option<usize>

Returns the index of the start of the query, including the ?. If there is no query, returns None.

pub fn fragment_start(&self) -> Option<usize>

Returns the index of the start of the fragment, including the #. If there is no fragment, returns None.

pub fn authority_range(&self) -> Option<Range<usize>>

Returns the byte index range that contains the authority, if present.

impl UriRef

Splitting

pub fn split(&self) -> (Option<&Uri>, &RelRef)

Splits this URI into the base and relative portions.

pub fn split_mut(&mut self) -> (Option<&mut Uri>, &mut RelRef)

Splits this URI into the base and relative portions.

pub fn base(&self) -> Option<&Uri>

Returns the subset of this URI that contains the scheme and authority, without the path, query, or fragment. If this is possible, the result is a &Uri.

pub fn rel(&self) -> &RelRef

Returns this URI as a &RelRef, including only the path, query, and fragment. If this URI is already relative, this method simply returns the given URI unchanged.

pub fn rel_mut(&mut self) -> &mut RelRef

Returns this URI as a &mut RelRef, including only the path, query, and fragment. If this URI is already relative, this method simply returns the given URI unchanged.

impl UriRef

Component Accessors

pub fn scheme(&self) -> Option<&str>

Returns the scheme of this URI, if it has a scheme. The returned string can be used directly and does not need to be unescaped or percent-decoded.

pub fn raw_authority(&self) -> Option<&str>

Returns the percent-encoded authority part of this URI, if it has one.

The unescaped version of this method is UriRef::authority.

In general, this value should not be used directly. Most users will find the method raw_userinfo_host_port to be a more useful extraction.

See StrExt for more details on unescaping.

pub fn authority(&self) -> Option<Cow<str>>

Percent-decoded version of UriRef::raw_authority, using std::borrow::Cow<str> instead of &str.

pub fn raw_userinfo_host_port(
    &self
) -> Option<(Option<&str>, &str, Option<u16>)>

Returns a tuple containing the raw userinfo, raw host, and port number from the authority component.

The percent-decoded version of this method is UriRef::userinfo_host_port.

The userinfo and host should be unescaped before being used. See StrExt for more details.

pub fn userinfo_host_port(
    &self
) -> Option<(Option<Cow<str>>, Cow<str>, Option<u16>)>

Percent-decoded version of UriRef::raw_userinfo_host_port, where the unescaped parts are represented as std::borrow::Cow<str> instances.

pub fn host(&self) -> Option<Cow<str>>

Percent-decoded host as a std::borrow::Cow<str>, if present.

#[must_use] pub fn raw_path(&self) -> &str

Returns a string slice containing the raw, percent-encoded value of the path.

There is no unescaped version of this method because the resulting ambiguity of percent-encoded slashes (/) present a security risk. Use path_segments if you need an escaped version.

If you absolutely must, you can use the following code to obtain a lossy, percent-decoded version of the path that doesn't decode %2F into slash characters:

let path = uri_ref!("%2F../a/%23/")
    .raw_path()
    .unescape_uri()
    .skip_slashes()
    .to_string();

assert_eq!(path, "%2F../a/#/");

pub fn path_as_rel_ref(&self) -> &RelRef

Returns the subset of this URI that is a path, without the scheme, authority, query, or fragment. Since this is itself a valid relative URI, it returns a &RelRef.

pub fn path_query_as_rel_ref(&self) -> &RelRef

Returns the subset of this URI that is a path and query, without the scheme, authority, or fragment. Since this is itself a valid relative URI, it returns a &RelRef.

pub fn raw_path_segments(&self) -> impl Iterator<Item = &str>

An iterator which returns each individual raw, percent-encoded path segment.

The percent-decoded (unescaped) version of this method is UriRef::path_segments.

The values returned by this iterator should be unescaped before being used. See StrExt and StrExt::unescape_uri for more details.

Example

use async_coap_uri::prelude::*;
let rel_ref = uri_ref!("g:a/%2F/bl%c3%a5b%c3%a6r");
let mut iter = rel_ref.raw_path_segments();

assert_eq!(iter.next(), Some("a"));
assert_eq!(iter.next(), Some("%2F"));
assert_eq!(iter.next(), Some("bl%c3%a5b%c3%a6r"));
assert_eq!(iter.next(), None);

pub fn path_segments(&self) -> impl Iterator<Item = Cow<str>>

Percent-decoded (unescaped) version of UriRef::raw_path_segments, using std::borrow::Cow<str> instead of &str.

Example

use async_coap_uri::prelude::*;
use std::borrow::Cow;
let uri_ref = uri_ref!("g:a/%2F/bl%c3%a5b%c3%a6r");
let mut iter = uri_ref.path_segments();

assert_eq!(iter.next(), Some(Cow::from("a")));
assert_eq!(iter.next(), Some(Cow::from("/")));
assert_eq!(iter.next(), Some(Cow::from("blåbær")));
assert_eq!(iter.next(), None);

pub fn query_fragment_as_rel_ref(&self) -> Option<&RelRef>

Returns the subset of this URI that is the query and fragment, without the scheme, authority, or path. This method includes the ? prefix, making it a valid relative URI.

pub fn query_as_rel_ref(&self) -> Option<&RelRef>

Returns the subset of this URI that is the query, without the scheme, authority, path, or fragment. This method includes the ? prefix, making it a valid relative URI.

pub fn raw_query(&self) -> Option<&str>

Returns the escaped slice of the URI that contains the "query", if present.

There is no unescaped version of this method because the resulting ambiguity of percent-encoded ampersands (&) and semicolons (;) present a security risk. Use query_items or query_key_values if you need a percent-decoded version.

pub fn raw_query_items(&self) -> impl Iterator<Item = &str>

Returns an iterator that iterates over all of the query items.

Both ; and & are acceptable query item delimiters.

The percent-decoded version of this method is UriRef::query_items.

The values returned by this iterator should be unescaped before being used. See StrExt and StrExt::unescape_uri for more details.

Example

use async_coap_uri::prelude::*;
let uri_ref = uri_ref!("/a/b/c?q=this:is&q=fun&q=bl%c3%a5b%c3%a6rsyltet%c3%b8y");
let mut iter = uri_ref.raw_query_items();

assert_eq!(iter.next(), Some("q=this:is"));
assert_eq!(iter.next(), Some("q=fun"));
assert_eq!(iter.next(), Some("q=bl%c3%a5b%c3%a6rsyltet%c3%b8y"));
assert_eq!(iter.next(), None);

pub fn raw_query_key_values(&self) -> impl Iterator<Item = (&str, &str)>

Similar to raw_query_items(), but additionally separates the key from the value for each query item.

The percent-decoded version of this method is UriRef::query_key_values.

Both keys and values are in their raw, escaped form. If you want escaped values, consider query_key_values().

Example

use async_coap_uri::prelude::*;
let uri_ref = uri_ref!("/a/b/c?inc&a=ok&b=q=q&c=bl%c3%a5b%c3%a6r");
let mut iter = uri_ref.raw_query_key_values();

assert_eq!(iter.next(), Some(("inc", "")));
assert_eq!(iter.next(), Some(("a", "ok")));
assert_eq!(iter.next(), Some(("b", "q=q")));
assert_eq!(iter.next(), Some(("c", "bl%c3%a5b%c3%a6r")));
assert_eq!(iter.next(), None);

pub fn query_items(&self) -> impl Iterator<Item = Cow<str>>

Percent-decoded version of UriRef::raw_query_items, using std::borrow::Cow<str> instead of &str.

pub fn query_key_values(&self) -> impl Iterator<Item = (Cow<str>, Cow<str>)>

Similar to query_items(), but additionally separates the key from the value for each query item.

Both keys and values are percent-decoded and ready-to-use. If you want them in their raw, percent-encoded in form, use raw_query_key_values().

This method uses the Copy-on-write type (std::borrow::Cow) to avoid unnecessary memory allocations.

Example

use async_coap_uri::prelude::*;
use std::borrow::Cow;
let uri_ref = uri_ref!("/a/b/c?inc&a=ok&b=q=q&c=bl%c3%a5b%c3%a6r");
let mut iter = uri_ref.query_key_values();

assert_eq!(iter.next(), Some((Cow::from("inc"), Cow::from(""))));
assert_eq!(iter.next(), Some((Cow::from("a"), Cow::from("ok"))));
assert_eq!(iter.next(), Some((Cow::from("b"), Cow::from("q=q"))));
assert_eq!(iter.next(), Some((Cow::from("c"), Cow::from("blåbær"))));
assert_eq!(iter.next(), None);

pub fn fragment_as_rel_ref(&self) -> Option<&RelRef>

Returns the subset of this URI that is the query, without the scheme, authority, path, or query. This method includes the # prefix, making it a valid relative URI.

pub fn raw_fragment(&self) -> Option<&str>

Returns a string slice containing the fragment, if any.

The percent-decoded version of this method is UriRef::fragment.

This value should be unescaped before being used. See StrExt for more details.

pub fn fragment(&self) -> Option<Cow<str>>

Percent-decoded version of UriRef::raw_fragment, using std::borrow::Cow<str> instead of &str.

impl UriRef

pub fn has_trailing_slash(&self) -> bool

Returns true if the path has a trailing slash.

Examples

use async_coap_uri::prelude::*;
assert!(uri_ref!("http://a/").has_trailing_slash());
assert!(uri_ref!("/a/").has_trailing_slash());
assert!(uri_ref!("a/").has_trailing_slash());
assert!(uri_ref!("http://a/?q=foo").has_trailing_slash());

assert!(!uri_ref!("http://a").has_trailing_slash());
assert!(!uri_ref!("a/b").has_trailing_slash());
assert!(!uri_ref!("").has_trailing_slash());

impl UriRef

Trimming

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_fragment(&self) -> &UriRef

Returns this URI-reference without a fragment.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("http://a/#frag").trim_fragment(),  uri_ref!("http://a/"));
assert_eq!(uri_ref!("a/b/c?blah#frag").trim_fragment(), uri_ref!("a/b/c?blah"));

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_query(&self) -> &UriRef

Returns this URI without a query or fragment.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("//foo/?bar").trim_query(),      uri_ref!("//foo/"));
assert_eq!(uri_ref!("a/b/c?blah#frag").trim_query(), uri_ref!("a/b/c"));
assert_eq!(uri_ref!("http://a/#frag").trim_query(),  uri_ref!("http://a/"));

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_path(&self) -> &UriRef

Returns this URI without a path, query, or fragment.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("a/b/c?blah#frag").trim_path(), uri_ref!(""));
assert_eq!(uri_ref!("//foo/?bar").trim_path(),      uri_ref!("//foo"));
assert_eq!(uri_ref!("http://a/#frag").trim_path(),  uri_ref!("http://a"));

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_heir_part(&self) -> &UriRef

Returns this URI without the "heir-part", or anything thereafter.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("a/b/c?blah#frag").trim_heir_part(), uri_ref!(""));
assert_eq!(uri_ref!("//foo/?bar").trim_heir_part(), uri_ref!(""));
assert_eq!(uri_ref!("http://a/#frag").trim_heir_part(), uri_ref!("http:"));

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_resource(&self) -> &UriRef

Returns this URI without the trailing part of the path that would be removed during relative-reference resolution.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("a").trim_resource(),               uri_ref!(""));
assert_eq!(uri_ref!("a/b/c?blah#frag").trim_resource(), uri_ref!("a/b/"));
assert_eq!(uri_ref!("/a").trim_resource(),              uri_ref!("/"));
assert_eq!(uri_ref!("//foo/?bar").trim_resource(),      uri_ref!("//foo/"));
assert_eq!(uri_ref!("http://a/#frag").trim_resource(),  uri_ref!("http://a/"));

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_trailing_slash(&self) -> &UriRef

Removes any trailing slash that might be at the end of the path, along with the query and fragment.

If the path consists of a single slash ("/"), then it is not removed.

Examples

use async_coap_uri::prelude::*;
assert_eq!(uri_ref!("a").trim_trailing_slash(),                uri_ref!("a"));
assert_eq!(uri_ref!("a/b/c/?blah#frag").trim_trailing_slash(), uri_ref!("a/b/c"));
assert_eq!(uri_ref!("/").trim_trailing_slash(),                uri_ref!("/"));
assert_eq!(uri_ref!("//foo/?bar").trim_trailing_slash(),       uri_ref!("//foo/"));
assert_eq!(uri_ref!("http://a/#frag").trim_trailing_slash(),   uri_ref!("http://a/"));

Note that the uri-ref "//" (a network path with an empty authority and an empty path) does not get its trailing slash removed because it technically isn't a part of the path. Likewise, the uri-ref "///" doesn't get the last slash removed because this method won't remove the first slash in the path. The uri-ref "////" however will have its trailing slash removed:

assert_eq!(uri_ref!("//").trim_trailing_slash(),    uri_ref!("//"));
assert_eq!(uri_ref!("///").trim_trailing_slash(),   uri_ref!("///"));
assert_eq!(uri_ref!("////").trim_trailing_slash(),  uri_ref!("///"));

#[must_use] pub fn trim_to_shorten(&self, base: &UriRef) -> Option<&RelRef>

Attempts to shorten this URI-reference given a base URI reference.

The returned reference can then be resolved using the base to recover the original URI reference.

use async_coap_uri::prelude::*;
let base = uri_ref!("http://example.com/a/b");
let target = uri_ref!("http://example.com/a/x/y/");

let shortened = target.trim_to_shorten(base).expect("Unable to shorten");
assert_eq!(shortened, rel_ref!("x/y/"));

let resolved = base.resolved(shortened).expect("Unable to resolve");
assert_eq!(resolved, target);

impl UriRef

Unsafe Methods

UriRef needs some unsafe methods in order to function properly. This section is where they are all located.

pub unsafe fn from_str_unchecked(s: &str) -> &UriRef

Converts a string slice to a UriRef slice without checking that the string contains valid URI-Reference.

See the safe version, from_str, for more information.

Safety

This function is unsafe because it does not check that the string passed to it is a valid URI-reference. If this constraint is violated, undefined behavior results.

pub unsafe fn from_str_unchecked_mut(s: &mut str) -> &mut UriRef

Converts a string slice to a UriRef slice without checking that the string contains valid URI-Reference; mutable version.

See the immutable version, from_str_unchecked, for more information.

pub unsafe fn as_mut_str(&mut self) -> &mut str

Returns this slice as a mutable str slice.

Safety

This is unsafe because it allows you to change the contents of the slice in such a way that would make it no longer consistent with the UriRef's promise that it can only ever contain a valid URI-reference.

Trait Implementations

impl AnyUriRef for UriRef

fn write_to<T: Write + ?Sized>(&self, write: &mut T) -> Result<(), Error>

Serializes this URI to anything implementing core::fmt::Write. Override with care!

fn is_empty(&self) -> bool

Returns true if the underlying URI-reference is actually the empty reference.

fn uri_type(&self) -> UriType

Gets the [UriType] of the underlying URI-reference.

fn components(&self) -> UriRawComponents

Returns a UriRawComponents instance which contains all of the components for this URI reference.

#[must_use] fn display(&self) -> UriDisplay<Self>

Wraps this AnyUriRef instance in a [UriDisplay] object for use with formatting macros like write! and format!.

#[must_use] fn to_uri_ref_buf(&self) -> UriRefBuf

Creates a new UriRefBuf from this AnyUriRef.

fn write_resolved<T: Write + ?Sized, D: AnyUriRef + ?Sized>(
    &self,
    target: &D,
    f: &mut T
) -> Result<(), ResolveError>

Writes out to a core::fmt::Write instance the result of performing URI resolution against target, with self being the base URI.

#[must_use] fn resolved<T: AnyUriRef + ?Sized>(
    &self,
    dest: &T
) -> Result<UriRefBuf, ResolveError>

Creates a new UriRefBuf that contains the result of performing URI resolution with dest.

impl<'_> Default for &'_ UriRef

The default &UriRef is an empty URI-reference.

fn default() -> Self

Returns the "default value" for a type.

impl<'_> Default for &'_ mut UriRef

The default &mut UriRef is an empty URI-reference.

Note that even though it is technically mutable, because the slice is empty it is mutable in name only.

fn default() -> Self

Returns the "default value" for a type.

impl Ord for UriRef

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: AsRef<str> + ?Sized> PartialOrd<T> for UriRef

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl ToOwned for UriRef

type Owned = UriRefBuf

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning.

impl<'_> From<&'_ UriRef> for String

fn from(x: &UriRef) -> Self

Performs the conversion.

impl<'_> From<&'_ UriRef> for UriRefBuf

fn from(x: &UriRef) -> Self

Performs the conversion.

impl AsRef<str> for UriRef

fn as_ref(&self) -> &str

Performs the conversion.

impl AsRef<UriRef> for UriRef

fn as_ref(&self) -> &UriRef

Performs the conversion.

impl AsRef<UriRef> for Uri

fn as_ref(&self) -> &UriRef

Performs the conversion.

impl Eq for UriRef

impl<T: AsRef<str> + ?Sized> PartialEq<T> for UriRef

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Deref for UriRef

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for UriRef

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Display for UriRef

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Debug for UriRef

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Borrow<UriRef> for UriRefBuf

fn borrow(&self) -> &UriRef

Immutably borrows from an owned value.