Struct async_coap_uri::RelRef

pub struct RelRef(_);

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

The sized counterpart is RelRefBuf.

This type cannot hold a network path. If this type contains a path that looks like a network path, it will be considered degenerate and you will not be able to losslessly convert it to a UriRef or UriRefBuf. See "Network Path Support" for more details.

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

    let uri = rel_ref!("/test?query");
    let components = uri.components();
    assert_eq!(None,          components.scheme());
    assert_eq!(None,          components.raw_host());
    assert_eq!(None,          components.port());
    assert_eq!("/test",       components.raw_path());
    assert_eq!(Some("query"), components.raw_query());

RelRef and Deref

You might think that since both relative and absolute URIs are just special cases of URIs that they could both safely implement Deref<Target=UriRef>. This is true for Uri, but not RelRef. This section is dedicated to explaining why.

There is this pesky section 4.2 of RFC3986 that throws a wrench into that noble endeavour:

A path segment that contains a colon character (e.g., "this:that") cannot be used as the first segment of a relative-path reference, as it would be mistaken for a scheme name. Such a segment must be preceded by a dot-segment (e.g., "./this:that") to make a relative- path reference.

This causes big problems for type-safety when derefing a RelRef into a UriRef: there is no way for UriRef to know that it came from a RelRef and thus recognize that something like rel_ref!("this:that") does NOT have a scheme of this.

These are tricky edge cases that have serious security implications---it's important that this case be considered and handled appropriately.

The solution used in this library is to make the transition from RelRef to UriRef not guaranteed. However, a transition from a RelRef to a RelRefBuf is guaranteed, since the offending colon can be escaped in that case. This is preferred instead of prepending a "./", due to the additional complications that could occur when manipulating paths.

You can check any RelRef for this degenerate condition via the method is_degenerate().

Methods

impl RelRef

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

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

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

Determines if the given string can be considered a well-formed [relative-reference]. [relative-reference]: https://tools.ietf.org/html/rfc3986#section-4.2

pub fn to_rel_ref_buf(&self) -> RelRefBuf

Constructs a new RelRefBuf from a &RelRef, disambiguating if degenerate.

pub fn to_uri_ref_buf(&self) -> UriRefBuf

Constructs a new UriRefBuf from a &RelRef, disambiguating if degenerate.

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

Casts this relative reference to a string slice.

pub fn try_as_uri_ref(&self) -> Option<&UriRef>

Casts a non-degenerate relative reference to a &UriRef. Returns None if the relative reference is degenerate.

pub fn as_uri_ref(&self) -> Cow<UriRef>

Returns a [Cow<UriRef>] that usually just contains a reference to this slice, but will contain an owned instance if this relative reference is degenerate.

impl RelRef

URI Component Accessors

#[must_use = "this returns a new slice, without modifying the original"] pub fn path_as_rel_ref(&self) -> &RelRef

Trims the query and fragment from this relative reference, leaving only the path.

See also RelRef::trim_query.

#[must_use = "this returns a new slice, without modifying the original"] pub fn query_as_rel_ref(&self) -> Option<&RelRef>

See UriRef::query_as_rel_ref for more information.

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

See UriRef::raw_path for more information.

#[must_use = "this returns a new slice, without modifying the original"] pub fn raw_query(&self) -> Option<&str>

See UriRef::raw_query for more information.

#[must_use = "this returns a new slice, without modifying the original"] pub fn raw_fragment(&self) -> Option<&str>

See UriRef::raw_fragment for more information.

#[must_use] pub fn raw_path_segments(&self) -> impl Iterator<Item = &str>

See UriRef::raw_path_segments for more information.

#[must_use] pub fn raw_query_items(&self) -> impl Iterator<Item = &str>

See UriRef::raw_query_items for more information.

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

See UriRef::raw_query_key_values for more information.

#[must_use] pub fn fragment(&self) -> Option<Cow<str>>

See UriRef::fragment for more information.

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

See UriRef::path_segments for more information.

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

See UriRef::query_items for more information.

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

See UriRef::query_key_values for more information.

#[must_use] pub fn has_trailing_slash(&self) -> bool

See UriRef::has_trailing_slash for more information.

#[must_use] pub fn colon_in_first_path_segment(&self) -> Option<usize>

Determines if this RelRef is degenerate specifically because it is a relative path with a colon in the first path segment and no special characters appearing before it.

See the section "RelRef" for more details.

pub fn is_degenerate(&self) -> bool

Determines if this RelRef is degenerate.

See the section "RelRef" for more details.

impl RelRef

URI Resolution

#[must_use] pub fn resolved_rel_ref<UF: AsRef<RelRef>>(&self, dest: UF) -> RelRefBuf

Resolves a relative URI against this relative URI, yielding a new relative URI as a RelRefBuf.

impl RelRef

Trimming

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

Returns this relative reference slice without the fragment component.

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

Returns this relative reference slice without the query or fragment components.

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

See UriRef::trim_resource for more information.

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

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!(rel_ref!("a").trim_trailing_slash(),               rel_ref!("a"));
assert_eq!(rel_ref!("a/b/c/?blah#frag").trim_trailing_slash(),rel_ref!("a/b/c"));
assert_eq!(rel_ref!("/").trim_trailing_slash(),               rel_ref!("/"));
assert_eq!(rel_ref!(unsafe "//").trim_trailing_slash(),       rel_ref!("/"));
assert_eq!(rel_ref!(unsafe "//foo/?bar").trim_trailing_slash(),rel_ref!(unsafe "//foo"));

Note that the behavior of this method is different than the behavior for UriRef::trim_trailing_slash: "//" is considered to be a path starting with two slashes rather than a network path with an empty authority and an empty path:

assert_eq!(rel_ref!(unsafe "//").trim_trailing_slash(),    rel_ref!("/"));
assert_eq!(rel_ref!(unsafe "///").trim_trailing_slash(),   rel_ref!(unsafe "//"));
assert_eq!(rel_ref!(unsafe "////").trim_trailing_slash(),  rel_ref!(unsafe "///"));

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

Returns this relative reference slice without any leading slashes.

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

Returns this relative reference slice without any leading instances of "./" or "/.".

#[must_use = "this returns the leading path item trimmed uri as a new slice, without modifying the original"] pub fn trim_leading_path_segment(&self) -> (&str, &RelRef)

Returns this relative reference slice without its first path segment.

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_leading_n_path_segments(&self, n: usize) -> (&str, &RelRef)

Returns a tuple with a string slice contianing the first n path segments and a &RelRef containing the rest of the relative reference.

#[must_use = "this returns the trimmed uri as a new slice, without modifying the original"] pub fn trim_to_shorten(&self, base: &RelRef) -> Option<&RelRef>

Attempts to return a shortened version of this relative reference that is relative to base.

impl RelRef

Unsafe Methods

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

Converts a string slice to a RelRef 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 RelRef

Converts a string slice to a RelRef 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.

pub const unsafe fn as_uri_ref_unchecked(&self) -> &UriRef

Directly converts this &RelRef to a &UriRef, without performing the checks that as_uri_ref() does.

This is unsafe for the reasons described here.

#[must_use] pub unsafe fn unsafe_path_segment_iter(&mut self) -> impl Iterator<Item = &str>

Experimental: Similar to raw_path_segment_iter(), but uses the space of the mutable UriRef to individually unescape the items.

Safety

This method is marked as unsafe because the contents of self is undefined after it terminates. The method can be used safely as long the buffer which held self is no longer accessed directly. See UriUnescapeBuf for an example.

#[must_use] pub unsafe fn unsafe_query_item_iter(&mut self) -> impl Iterator<Item = &str>

Experimental: Similar to raw_query_item_iter(), but uses the space of the mutable UriRef to individually unescape the query items.

Safety

This method is marked as unsafe because the contents of self is undefined after it terminates. The method can be used safely as long the &mut UriRef (and its owner) is never directly used again. See UriUnescapeBuf for an example.

Trait Implementations

impl AnyUriRef for RelRef

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 relative reference this is:

This function may return any one of the following values:

• UriType::Fragment
• UriType::Query
• UriType::AbsolutePath
• UriType::RelativePath

fn components(&self) -> UriRawComponents

Breaks down this relative reference into its raw components.

#[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<&'_ RelRef> for String

fn from(x: &RelRef) -> Self

Performs the conversion.

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

fn from(x: &RelRef) -> Self

Performs the conversion.

impl<'_> From<&'_ RelRef> for RelRefBuf

fn from(x: &RelRef) -> Self

Performs the conversion.

impl Ord for RelRef

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 RelRef

type Owned = RelRefBuf

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 RelRef

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 RelRef

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<'_> Default for &'_ RelRef

fn default() -> Self

Returns an empty relative reference.

Empty relative references do nothing but clear the base fragment when resolved against a base.

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

fn default() -> Self

Mutable version of (&RelRef)::default.

Despite being marked mutable, since the length is zero the value is effectively immutable.

impl AsRef<str> for RelRef

fn as_ref(&self) -> &str

Performs the conversion.

impl AsRef<RelRef> for RelRef

fn as_ref(&self) -> &RelRef

Performs the conversion.

impl AsRef<RelRef> for RelRefBuf

fn as_ref(&self) -> &RelRef

Performs the conversion.

impl Eq for RelRef

impl Display for RelRef

RelRef will always format the relative reference for display in an unambiguous fashion.

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

Formats the value using the given formatter.

impl Debug for RelRef

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

Formats the value using the given formatter.

impl Deref for RelRef

type Target = str

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for RelRef

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<RelRef> for RelRefBuf

fn borrow(&self) -> &RelRef

Immutably borrows from an owned value.