    let mut uri = uri_ref!("http://example.com/blah/bleh?query").to_uri_ref_buf();
    uri.truncate_query();
    assert_eq!("http://example.com/blah/bleh", uri.as_str());

    let mut uri = uri_ref!("http://example.com/blah/bleh#foobar").to_uri_ref_buf();
    uri.truncate_query();
    assert_eq!("http://example.com/blah/bleh", uri.as_str());

    let mut uri = uri_ref!("another?foo#bar").to_uri_ref_buf();
    uri.truncate_query();
    assert_eq!("another", uri.as_str());

`pub fn truncate_path(&mut self)`[src]

Truncates the path, query, and fragments components of a UriRefBuf.

`pub fn truncate_resource(&mut self)`[src]

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

    let mut uri = uri_ref!("http://example.com/blah/bleh").to_uri_ref_buf();
    uri.truncate_resource();
    assert_eq!("http://example.com/blah/", uri.as_str());

    let mut uri = uri_ref!("http://example.com/blah/").to_uri_ref_buf();
    uri.truncate_resource();
    assert_eq!("http://example.com/blah/", uri.as_str());

    let mut uri = uri_ref!("foo#bar").to_uri_ref_buf();
    uri.truncate_resource();
    assert_eq!("", uri.as_str());

http://example.com/blah/bleh becomes http://example.com/blah/
http://example.com/blah/ becomes http://example.com/blah/
foo#bar becomes ``

`pub fn truncate_last_path_segment(&mut self)`[src]

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

This method will only result in an empty path if the path was empty to begin with.

E.g.:

    let mut uri = uri_ref!("http://example.com/blah/bleh").to_uri_ref_buf();
    uri.truncate_last_path_segment();
    assert_eq!("http://example.com/blah/", uri.as_str());
    uri.truncate_last_path_segment();
    assert_eq!("http://example.com/", uri.as_str());
    uri.truncate_last_path_segment();
    assert_eq!("http://example.com/", uri.as_str());

    let mut uri = uri_ref!("foo#bar").to_uri_ref_buf();
    uri.truncate_last_path_segment();
    assert_eq!("./", uri.as_str());

http://example.com/blah/bleh becomes http://example.com/blah/
http://example.com/blah/ becomes http://example.com/
foo#bar becomes ``

`pub fn clear(&mut self)`[src]

Completely clears this UriRefBuf, leaving it empty.

`pub fn add_trailing_slash(&mut self) -> bool`[src]

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

`pub fn add_leading_slash(&mut self) -> bool`[src]

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

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

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

`pub fn push_path_segment(&mut self, segment: &str, trailing_slash: bool)`[src]

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

If this URI-reference 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.

Special Cases

Calling x.push_path_segment(".", false) will do nothing.

Calling x.push_path_segment(".", true) is the same as calling x.add_trailing_slash().

Calling x.push_path_segment("..", _) is the same as calling x.truncate_last_path_segment(). In this case the value of trailing_slash is ignored.

Example

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

uri.push_path_segment("foobar", false);
assert_eq!(uri, uri_ref!("http://example.com/foobar"));

uri.push_path_segment("a/b/c", true);
assert_eq!(uri, uri_ref!("http://example.com/foobar/a%2Fb%2Fc/"));

`pub fn push_query_item(&mut self, item: &str)`[src]

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.

Example

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

uri.push_query_item("foobar");
assert_eq!(uri, uri_ref!("http://example.com?foobar"));

uri.push_query_item("q=a vast query");
assert_eq!(uri, uri_ref!("http://example.com?foobar&q=a+vast+query"));

`pub fn push_query_key_value(&mut self, key: &str, value: &str)`[src]

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.

Example

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

uri.push_query_key_value("foo","bar");
assert_eq!(uri, uri_ref!("http://example.com?foo=bar"));

uri.push_query_key_value("q","a vast query");
assert_eq!(uri, uri_ref!("http://example.com?foo=bar&q=a+vast+query"));

`pub fn replace_path(&mut self, rel: &RelRef)`[src]

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

Unsafe Methods

UriRefBuf 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) -> UriRefBuf`[src]

Unchecked version of UriRefBuf::from_string.

Safety

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

`pub unsafe fn as_mut_str(&mut self) -> &mut str`[src]

Borrows a mutable string slice containing this URI reference.

This method is marked as unsafe because it allows you to change the content of the URI reference without any checks on syntax.

`pub unsafe fn as_mut_string_ref(&mut self) -> &mut String`[src]

Borrows a mutable String reference containing this URI reference.

This method is marked as unsafe because it allows you to change the content of the URI reference without any checks on syntax.

Methods from Deref<Target = UriRef>

`pub const fn as_str(&self) -> &str`[src]

Returns this URI-reference as a string slice.

`pub fn as_uri(&self) -> Option<&Uri>`[src]

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>`[src]

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`[src]

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

`pub fn path_start(&self) -> usize`[src]

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`[src]

Returns the index of the end of the path

`pub fn query_start(&self) -> Option<usize>`[src]

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>`[src]

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>>`[src]

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

`pub fn split(&self) -> (Option<&Uri>, &RelRef)`[src]

Splits this URI into the base and relative portions.

`pub fn base(&self) -> Option<&Uri>`[src]

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`[src]

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>`[src]

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>`[src]

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>>`[src]

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>)>`[src]

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>)>`[src]

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>>`[src]

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

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

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`[src]

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`[src]

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>`[src]

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>>`[src]

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>`[src]

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>`[src]

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>`[src]

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>`[src]

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)>`[src]

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>>`[src]

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>)>`[src]

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>`[src]

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>`[src]

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>>`[src]

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

`pub fn has_trailing_slash(&self) -> bool`[src]

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`[src]

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`[src]

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`[src]

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`[src]

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`[src]

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`[src]

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>`[src]

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