Struct async_coap_uri::UriBuf

pub struct UriBuf(_);

Sized, heap-allocated string type guaranteed to contain a well-formed IETF-RFC3986 URI or network path.

The unsized counterpart is Uri.

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

Methods

impl UriBuf

Unsafe Methods

UriBuf 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) -> UriBuf

Unchecked version of UriBuf::from_string.

Safety

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

impl UriBuf

pub fn new<Sch, Hos, Pat, Que, Frg>(
    scheme: Sch,
    host: Hos,
    port: Option<u16>,
    path: Pat,
    query: Option<Que>,
    fragment: Option<Frg>
) -> UriBuf where
    Sch: Into<String>,
    Hos: AsRef<str>,
    Pat: AsRef<str>,
    Que: AsRef<str>,
    Frg: AsRef<str>, 

Creates a new UriBuf from unescaped component values.

pub fn from_scheme_authority<Sch, Aut>(scheme: Sch, authority: Aut) -> UriBuf where
    Sch: Into<String>,
    Aut: AsRef<str>, 

Constructs a UriBuf from a scheme and authority.

The authority should not be percent encoded. If the given scheme contains invalid characters, this method will panic.

Example

use async_coap_uri::prelude::*;
let authority = "user@[2001:0db8:85a3::1%en2]:8080";

let uri_buf = UriBuf::from_scheme_authority("http", authority);

assert_eq!(uri_buf, uri!("http://user@[2001:0db8:85a3::1%25en2]:8080"));

pub fn from_host_rel_ref<Hos, RR>(host: Hos, rel_ref: RR) -> UriBuf where
    Hos: AsRef<str>,
    RR: AsRef<RelRef>, 

Constructs a network path from a host and a relative reference.

Example

use async_coap_uri::prelude::*;
let host = "example.com";
let rel_ref = rel_ref!("./foobar?q");

let uri_buf = UriBuf::from_host_rel_ref(host, rel_ref);

assert_eq!(uri_buf, uri!("//example.com/foobar?q"));

pub fn from_scheme_host_port<Sch, Hos>(
    scheme: Sch,
    host: Hos,
    port: Option<u16>
) -> UriBuf where
    Sch: Into<String>,
    Hos: AsRef<str>, 

Constructs a UriBuf from a scheme, host and an optional port number.

The host should not be percent encoded. If the given scheme contains invalid characters, this method will panic.

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

Attempts to create a new UriBuf from a string slice.

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

Attempts to create a new UriBuf from a String.

pub fn from_uri<S: AsRef<UriRef>>(s: S) -> Option<UriBuf>

Attempts to create a new UriBuf from a UriRef slice.

impl UriBuf

pub fn as_uri(&self) -> &Uri

Borrows a Uri slice containing this URI.

impl UriBuf

Manipulation

pub fn resolve<T: AnyUriRef + ?Sized>(
    &mut self,
    dest: &T
) -> Result<(), ResolveError>

Using this URI as the base, performs "relative resolution" to the given instance implementing AnyUriRef, updating the content of this UriBuf with the result.

pub fn replace_path(&mut self, rel: &RelRef)

Replaces the path, query, and fragment with that from rel.

impl UriBuf

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

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

Splits this URI into the base and relative portions.

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/"));

Trait Implementations

impl AnyUriRef for UriBuf

fn components(&self) -> UriRawComponents

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

fn write_to<W: Write + ?Sized>(&self, write: &mut W) -> 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 to_uri_ref_buf(&self) -> UriRefBuf

Creates a new UriRefBuf from this AnyUriRef.

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

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: AnyUriRef + ?Sized>(
    &self,
    dest: &W
) -> Result<UriRefBuf, ResolveError>

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 From<UriBuf> for String

fn from(x: UriBuf) -> Self

Performs the conversion.

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

fn from(x: &UriBuf) -> Self

Performs the conversion.

impl From<UriBuf> for UriRefBuf

fn from(x: UriBuf) -> Self

Performs the conversion.

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

fn from(x: &Uri) -> Self

Performs the conversion.

impl Ord for UriBuf

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 UriBuf

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 UriBuf

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 Clone for UriBuf

fn clone(&self) -> UriBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Eq for UriBuf

impl AsRef<str> for UriBuf

fn as_ref(&self) -> &str

Performs the conversion.

impl AsRef<UriBuf> for UriBuf

fn as_ref(&self) -> &UriBuf

Performs the conversion.

impl AsRef<String> for UriBuf

fn as_ref(&self) -> &String

Performs the conversion.

impl AsRef<UriRefBuf> for UriBuf

fn as_ref(&self) -> &UriRefBuf

Performs the conversion.

impl AsRef<Uri> for UriBuf

fn as_ref(&self) -> &Uri

Performs the conversion.

impl Deref for UriBuf

type Target = Uri

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for UriBuf

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

Formats the value using the given formatter.

impl Debug for UriBuf

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

Formats the value using the given formatter.

impl Hash for UriBuf

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.