Struct async_coap_uri::Uri

pub struct Uri(_);

Unsized string-slice type guaranteed to contain a well-formed IETF-RFC3986 URI or network path.

The sized counterpart is crate::UriBuf.

You can create static constants with this class by using the uri! macro:

    let uri = uri!("http://example.com/test");
    let components = uri.components();
    assert_eq!(Some("http"),        components.scheme());
    assert_eq!(Some("example.com"), components.raw_host());
    assert_eq!(None,                components.port());
    assert_eq!("/test",             components.raw_path());

Methods

impl Uri

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

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

Example:

use async_coap_uri::prelude::*;
assert_eq!(Uri::from_str("http://example.com"), Ok(uri!("http://example.com")));
assert!(Uri::from_str("/a/b/c").is_err());

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

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

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

Example:

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

pub const fn as_uri_ref(&self) -> &UriRef

Reinterpret this &Uri as a &UriRef.

pub fn to_uri_buf(&self) -> UriBuf

Copy the content of this &Uri into a new UriBuf and return it.

impl Uri

Splitting

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

Splits this URI into the base and relative portions.

impl Uri

Trimming

pub fn trim_fragment(&self) -> &Uri

Returns this URI without a fragment.

Examples

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

pub fn trim_query(&self) -> &Uri

Returns this URI without a query or fragment.

Examples

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

pub fn trim_path(&self) -> &Uri

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

Examples

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

pub fn trim_resource(&self) -> &Uri

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!("//foo/?bar").trim_resource(),      uri!("//foo/"));
assert_eq!(uri!("http://a/#frag").trim_resource(),  uri!("http://a/"));

impl Uri

Unsafe Methods

Uri 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) -> &Uri

Creates a Uri slice from a string slice without checking that the content of the string slice is a valid URI.

Since containing a valid URI is a fundamental guarantee of the Uri type, this method is unsafe.

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

Creates a mutable Uri slice from a mutable string slice without checking that the content of the mutable string slice is a valid URI.

Since containing a valid URI is a fundamental guarantee of the Uri type, this method is unsafe.

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 Uri's promise that it can only ever contain a valid URI.

Methods from Deref<Target = UriRef>

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.

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.

pub fn split(&self) -> (Option<&Uri>, &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 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.

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());

#[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);

Trait Implementations

impl AnyUriRef for Uri

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

Determines what kind of URI this is.

This function may return any one of the following values:

• UriType::Uri
• UriType::UriNoAuthority
• UriType::UriCannotBeABase
• UriType::NetworkPath

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<'_> From<&'_ Uri> for String

fn from(x: &Uri) -> Self

Performs the conversion.

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

fn from(x: &Uri) -> Self

Performs the conversion.

impl<'_> From<&'_ Uri> for UriBuf

fn from(x: &Uri) -> Self

Performs the conversion.

impl Ord for Uri

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 ToOwned for Uri

type Owned = UriBuf

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<T: AsRef<str> + ?Sized> PartialOrd<T> for Uri

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<T: AsRef<str> + ?Sized> PartialEq<T> for Uri

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 AsRef<str> for Uri

fn as_ref(&self) -> &str

Performs the conversion.

impl AsRef<Uri> for Uri

fn as_ref(&self) -> &Uri

Performs the conversion.

impl AsRef<UriRef> for Uri

fn as_ref(&self) -> &UriRef

Performs the conversion.

impl AsRef<Uri> for UriBuf

fn as_ref(&self) -> &Uri

Performs the conversion.

impl Eq for Uri

impl Display for Uri

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

Formats the value using the given formatter.

impl Debug for Uri

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

Formats the value using the given formatter.

impl Deref for Uri

type Target = UriRef

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for Uri

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 Borrow<Uri> for UriBuf

fn borrow(&self) -> &Uri

Immutably borrows from an owned value.