Struct async_coap::uri::RelRefBuf

pub struct RelRefBuf(_);

Sized, heap-allocated string type guaranteed to contain a well-formed IETF-RFC3986 relative-reference.

The unsized counterpart is RelRef.

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.

This type implements [std::ops::Deref<RelRef>], so you can also use all of the methods from RelRef on this type.

Methods

impl RelRefBuf

Constructors

pub fn new() -> RelRefBuf

Constructs a new, empty relative reference buffer.

pub fn with_capacity(capacity: usize) -> RelRefBuf

Creates a new, empty RelRefBuf with a capacity of capacity.

pub fn from_str<S>(s: S) -> Result<RelRefBuf, ParseError> where
    S: AsRef<str>, 

Attempts to create a new RelRefBuf from a string reference.

pub fn from_string(s: String) -> Result<RelRefBuf, ParseError>

Attempts to create a new RelRefBuf from a String.

pub fn from_uri_ref<S>(s: S) -> Option<RelRefBuf> where
    S: AsRef<UriRef>, 

Attempts to create a new RelRefBuf from a UriRef reference.

pub fn from_rel_ref<S>(s: S) -> RelRefBuf where
    S: AsRef<RelRef>, 

Attempts to create a new RelRefBuf from a RelRef reference.

impl RelRefBuf

Conversions

pub fn as_rel_ref(&self) -> &RelRef

Borrows a RelRef slice containing this relative reference.

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

Borrows a mutable RelRef slice containing this relative reference.

impl RelRefBuf

Manipulations

pub fn disambiguate(&mut self) -> bool

Modifies this relative reference to be unambiguous.

Specifically:

• this:that is converted to this%3Athat, to avoid confusion with a URI.
• //this/that is converted to /.//this/that, to avoid confusion with a network path.

Note that ambiguous RelRefBuf instances are always displayed/formatted unambiguously, so there should be little need to ever call this method.

#[must_use] pub fn into_unescape_buf(self) -> UriUnescapeBuf

Experimental: Takes ownership of the RelRefBuf and returns a UriUnescapeBuf that allows for in-line unescaping during iteration of path segments and query items without additional memory allocations.

Example:

use async_coap_uri::prelude::*;
let rel_ref_buf = rel_ref!(unsafe "g:a/b/bl%c3%a5b%c3%a6r?q=g:a&q=foo&q=syltet%c3%b8y").to_rel_ref_buf();
let mut unescape_buf = rel_ref_buf.into_unescape_buf();

let mut query_item_iter = unescape_buf.query_items();

assert_eq!(query_item_iter.next(), Some("q=g:a"));
assert_eq!(query_item_iter.next(), Some("q=foo"));
assert_eq!(query_item_iter.next(), Some("q=syltetøy"));
assert_eq!(query_item_iter.next(), None);

core::mem::drop(query_item_iter);

let mut path_seg_iter = unescape_buf.path_segments();

assert_eq!(path_seg_iter.next(), Some("g:a"));
assert_eq!(path_seg_iter.next(), Some("b"));
assert_eq!(path_seg_iter.next(), Some("blåbær"));
assert_eq!(path_seg_iter.next(), None);

Lifetimes are enforced on the returned path items, meaning the following code does not compile:

    let mut uri = rel_ref!("this:is/fun/bl%c3%a5b%c3%a6rsyltet%c3%b8y").to_owned();
    let first_part;
    let second_part;
    {
        // This line takes ownership of `uri`...
        let mut path_set = uri.into_unescape_buf();
        let mut iter = path_set.path_segments();

        // ...so these string slices will be valid
        // for the lifetime of `iter`.
        first_part = iter.next().unwrap();
        second_part = iter.next().unwrap();
    }
    // Iter has been dropped at this point, but the next
    // line uses both `first_part` and `second_part`---so
    // the compiler will flag an error. If it does compile,
    // it represents a use-after-free error.
    panic!("This should not have compiled! {} {}", first_part, second_part);

pub fn resolve<T>(&mut self, dest: T) where
    T: AsRef<RelRef>, 

Using this relative-reference as the base, performs "URI-reference resolution" on another relative reference, updating the content of this RelRefBuf with the result.

pub fn clear(&mut self)

Completely clears this RelRefBuf, leaving it empty.

impl RelRefBuf

Unsafe Methods

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

pub unsafe fn from_string_unchecked(s: String) -> RelRefBuf

Unchecked version of RelRefBuf::from_string.

Safety

This method is marked as unsafe because it allows you to construct a RelRefBuf with a value that is not a well-formed relative-reference.

impl RelRefBuf

Methods inherited from UriRefBuf

pub fn as_str(&self) -> &str

Returns a string slice for this instance.

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

Returns a mutable string slice (&mut str) for this instance.

Safety

This method is not safe because this type makes guarantees about the structure of the content it contains, which may be violated by using this method.

pub fn as_mut_uri_ref(&mut self) -> &mut UriRef

Borrows a reference to this mutable instance as a mutable URI-Reference (&mut UriRef).

pub fn truncate_heir_part(&mut self)

Removes the authority, path, query, and fragment components, if present.

pub fn truncate_path(&mut self)

Removes the path, query, and fragment components, if present.

pub fn truncate_query(&mut self)

Removes the query, and fragment components, if present.

pub fn truncate_fragment(&mut self)

Removes fragment component, if present.

pub fn truncate_resource(&mut self)

Removes the last path component (up to, but not including, the last slash), along with the query and fragment components, if present.

See UriRefBuf::truncate_resource for more information.

pub fn truncate_last_path_segment(&mut self)

Removes the last path item, along with the query and fragment components, if present.

See UriRefBuf::truncate_last_path_segment for more information.

pub fn add_trailing_slash(&mut self) -> bool

Adds a trailing slash to the path if there isn't a trailing slash already present.

pub fn add_leading_slash(&mut self) -> bool

Adds a leading slash to the path if there isn't one already present.

pub fn push_path_segment(&mut self, segment: &str, trailing_slash: bool)

Percent-encodes and appends the given path segment to this instance, truncating any existing query or fragment in the process.

If this instance isn't empty and doesn't end with a slash, one is first added. A trailing slash will be appended depending on the value of the trailing_slash argument.

pub fn push_query_item(&mut self, item: &str)

Percent-encodes and appends the given query item to this instance, truncating any existing fragment in the process.

If no query is present, the query item is preceded with a '?' to indicate the start of the query component. Otherwise, this method uses & to separate query items.

This method follows the common convention where spaces are encoded as + characters instead of %20.

pub fn push_query_key_value(&mut self, key: &str, value: &str)

Percent-encodes and appends the given query key/value pair to this URI-reference, truncating any existing fragment in the process.

If no query is present, the query item is preceded with a '?' to indicate the start of the query component. Otherwise, this method uses & to separate query items.

This method follows the common convention where spaces are encoded as + characters instead of %20.

Methods from Deref<Target = RelRef>

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.

#[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.

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

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

#[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.

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.

Trait Implementations

impl AsRef<RelRef> for RelRefBuf

fn as_ref(&self) -> &RelRef

Performs the conversion.

impl AsRef<UriRefBuf> for RelRefBuf

fn as_ref(&self) -> &UriRefBuf

Performs the conversion.

impl AsRef<String> for RelRefBuf

fn as_ref(&self) -> &String

Performs the conversion.

impl AsRef<RelRefBuf> for RelRefBuf

fn as_ref(&self) -> &RelRefBuf

Performs the conversion.

impl AsRef<str> for RelRefBuf

fn as_ref(&self) -> &str

Performs the conversion.

impl Display for RelRefBuf

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

Formats the value using the given formatter.

impl Eq for RelRefBuf

impl Ord for RelRefBuf

fn cmp(&self, other: &RelRefBuf) -> 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> PartialOrd<T> for RelRefBuf where
    T: AsRef<str> + ?Sized, 

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

type Target = RelRef

The resulting type after dereferencing.

fn deref(&self) -> &<RelRefBuf as Deref>::Target

Dereferences the value.

impl Debug for RelRefBuf

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

Formats the value using the given formatter.

impl Clone for RelRefBuf

fn clone(&self) -> RelRefBuf

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl AnyUriRef for RelRefBuf

fn components(&self) -> UriRawComponents

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

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

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 to_uri_ref_buf(&self) -> UriRefBuf

Creates a new [UriRefBuf] from this [AnyUriRef].

fn write_resolved<W, D>(
    &self,
    dest: &D,
    output: &mut W
) -> Result<(), ResolveError> where
    D: AnyUriRef + ?Sized,
    W: Write + ?Sized, 

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

fn resolved<W>(&self, dest: &W) -> Result<UriRefBuf, ResolveError> where
    W: AnyUriRef + ?Sized, 

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

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

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

impl Default for RelRefBuf

fn default() -> RelRefBuf

Returns the "default value" for a type.

impl Hash for RelRefBuf

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

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

fn from(x: &RelRefBuf) -> RelRefBuf

Performs the conversion.

impl From<RelRefBuf> for UriRefBuf

fn from(x: RelRefBuf) -> UriRefBuf

Performs the conversion.

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

fn from(x: &RelRef) -> RelRefBuf

Performs the conversion.

impl Borrow<RelRef> for RelRefBuf

fn borrow(&self) -> &RelRef

Immutably borrows from an owned value.

impl<T> PartialEq<T> for RelRefBuf where
    T: AsRef<str> + ?Sized, 

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 !=.