Struct UriRef 

pub struct UriRef<T> { /* private fields */ }

A URI reference, i.e., either a URI or a relative reference.

See the crate-level documentation for an explanation of the above term(s).

Variants

Two variants of UriRef are available: UriRef<&str> (borrowed) and UriRef<String> (owned).

UriRef<&'a str> outputs references with lifetime 'a where possible (thanks to borrow-or-share):

use fluent_uri::UriRef;

// Keep a reference to the path after dropping the `UriRef`.
let path = UriRef::parse("foo:bar")?.path();
assert_eq!(path, "bar");

Comparison

UriRefs are compared lexicographically by their byte values. Normalization is not performed prior to comparison.

Examples

Parse and extract components from a URI reference:

use fluent_uri::{
    component::{Host, Scheme},
    pct_enc::EStr,
    UriRef,
};

const SCHEME_FOO: &Scheme = Scheme::new_or_panic("foo");

let s = "foo://user@example.com:8042/over/there?name=ferret#nose";
let uri_ref = UriRef::parse(s)?;

assert_eq!(uri_ref.scheme().unwrap(), SCHEME_FOO);

let auth = uri_ref.authority().unwrap();
assert_eq!(auth.as_str(), "user@example.com:8042");
assert_eq!(auth.userinfo().unwrap(), "user");
assert_eq!(auth.host(), "example.com");
assert!(matches!(auth.host_parsed(), Host::RegName(name) if name == "example.com"));
assert_eq!(auth.port().unwrap(), "8042");
assert_eq!(auth.port_to_u16(), Ok(Some(8042)));

assert_eq!(uri_ref.path(), "/over/there");
assert_eq!(uri_ref.query().unwrap(), "name=ferret");
assert_eq!(uri_ref.fragment().unwrap(), "nose");

Parse into and convert between UriRef<&str> and UriRef<String>:

use fluent_uri::UriRef;

let s = "http://example.com/";

// Parse into a `UriRef<&str>` from a string slice.
let uri_ref: UriRef<&str> = UriRef::parse(s)?;

// Parse into a `UriRef<String>` from an owned string.
let uri_ref_owned: UriRef<String> = UriRef::parse(s.to_owned()).map_err(|e| e.0)?;

// Convert a `UriRef<&str>` to `UriRef<String>`.
let uri_ref_owned: UriRef<String> = uri_ref.to_owned();

// Borrow a `UriRef<String>` as `UriRef<&str>`.
let uri_ref: UriRef<&str> = uri_ref_owned.borrow();

Implementations

impl<T> UriRef<T>

pub fn parse<I>(input: I) -> Result<Self, I::Err>

where I: Parse<Val = T>,

Parses a URI reference from a string into a UriRef.

The return type is

• Result<UriRef<&str>, ParseError> for I = &str;
• Result<UriRef<String>, (ParseError, String)> for I = String.

Errors

Returns Err if the string does not match the URI-reference ABNF rule from RFC 3986.

impl UriRef<String>

pub fn builder() -> Builder<Self, Start>

Available on crate feature alloc only.

Creates a new builder for URI reference.

pub fn borrow(&self) -> UriRef<&str>

Available on crate feature alloc only.

Borrows this UriRef<String> as UriRef<&str>.

pub fn into_string(self) -> String

Available on crate feature alloc only.

Consumes this UriRef<String> and yields the underlying String.

impl UriRef<&str>

pub fn to_owned(&self) -> UriRef<String>

Available on crate feature alloc only.

Creates a new UriRef<String> by cloning the contents of this UriRef<&str>.

impl<'i, 'o, T: BorrowOrShare<'i, 'o, str>> UriRef<T>

pub fn as_str(&'i self) -> &'o str

Returns the URI reference as a string slice.

pub fn scheme(&'i self) -> Option<&'o Scheme>

Returns the optional scheme component.

Note that the scheme component is case-insensitive. See the documentation of Scheme for more details on comparison.

Examples

use fluent_uri::{component::Scheme, UriRef};

const SCHEME_HTTP: &Scheme = Scheme::new_or_panic("http");

let uri_ref = UriRef::parse("http://example.com/")?;
assert_eq!(uri_ref.scheme(), Some(SCHEME_HTTP));

let uri_ref = UriRef::parse("/path/to/file")?;
assert_eq!(uri_ref.scheme(), None);

pub fn authority(&'i self) -> Option<Authority<'o>>

Returns the optional authority component.

Examples

use fluent_uri::UriRef;

let uri_ref = UriRef::parse("http://example.com/")?;
assert!(uri_ref.authority().is_some());

let uri_ref = UriRef::parse("mailto:user@example.com")?;
assert!(uri_ref.authority().is_none());

pub fn path(&'i self) -> &'o EStr<Path>

Returns the path component.

The path component is always present, although it may be empty.

The returned EStr slice has extension methods for the path component.

Examples

use fluent_uri::UriRef;

let uri_ref = UriRef::parse("http://example.com/")?;
assert_eq!(uri_ref.path(), "/");

let uri_ref = UriRef::parse("mailto:user@example.com")?;
assert_eq!(uri_ref.path(), "user@example.com");

let uri_ref = UriRef::parse("http://example.com")?;
assert_eq!(uri_ref.path(), "");

pub fn query(&'i self) -> Option<&'o EStr<Query>>

Returns the optional query component.

Examples

use fluent_uri::{pct_enc::EStr, UriRef};

let uri_ref = UriRef::parse("http://example.com/?lang=en")?;
assert_eq!(uri_ref.query(), Some(EStr::new_or_panic("lang=en")));

let uri_ref = UriRef::parse("ftp://192.0.2.1/")?;
assert_eq!(uri_ref.query(), None);

pub fn fragment(&'i self) -> Option<&'o EStr<Fragment>>

Returns the optional fragment component.

Examples

use fluent_uri::{pct_enc::EStr, UriRef};

let uri_ref = UriRef::parse("http://example.com/#usage")?;
assert_eq!(uri_ref.fragment(), Some(EStr::new_or_panic("usage")));

let uri_ref = UriRef::parse("ftp://192.0.2.1/")?;
assert_eq!(uri_ref.fragment(), None);

impl<T: Bos<str>> UriRef<T>

pub fn resolve_against<U: Bos<str>>( &self, base: &Uri<U>, ) -> Result<Uri<String>, ResolveError>

Available on crate feature alloc only.

Resolves the URI reference against the given base URI and returns the target URI.

The base URI must have no fragment, i.e., match the absolute-URI ABNF rule from RFC 3986.

To prepare a base URI, you can use strip_fragment, with_fragment or set_fragment to remove the fragment from any URI. Note that a base without fragment does not guarantee a successful resolution (see the must below).

This method applies the reference resolution algorithm defined in Section 5 of RFC 3986, except for the following deviations:

• If base has a rootless path and no authority, then self must either have a scheme, be empty, or start with '#'.
• When the target has no authority and its path would start with "//", the string "/." is prepended to the path. This closes a loophole in the original algorithm that resolving ".//@@" against "foo:/" yields "foo://@@" which is not a valid URI/IRI.
• Percent-encoded dot segments (e.g. "%2E" and ".%2e") are also removed. This closes a loophole in the original algorithm that resolving ".." against "foo:/bar/baz/.%2E/" yields "foo:/bar/baz/", while first normalizing the base and then resolving ".." against it yields "foo:/".
• A slash ('/') is appended to the base when it ends with a double-dot segment. This closes a loophole in the original algorithm that resolving "." against "foo:/bar/.." yields "foo:/bar/", while first normalizing the base and then resolving "." against it yields "foo:/".
• When base has an absolute path and self has an empty path and no scheme nor authority, dot segments are removed from the base path before using it as the target path. This closes a loophole in the original algorithm that resolving "" against "foo:/." yields "foo:/." in which dot segments are not removed.

No normalization except the removal of dot segments will be performed. Use normalize if necessary.

This method has the property that self.resolve_against(base).map(|r| r.normalize()).ok() equals self.normalize().resolve_against(&base.normalize()).ok().

If you need to resolve multiple references against a common base or configure the behavior of resolution, consider using Resolver instead.

Errors

Returns Err if any of the above two musts is violated.

Examples

use fluent_uri::{Uri, UriRef};

let base = Uri::parse("http://example.com/foo/bar")?;

let uri_ref = UriRef::parse("baz")?;
assert_eq!(uri_ref.resolve_against(&base).unwrap(), "http://example.com/foo/baz");

let uri_ref = UriRef::parse("../baz")?;
assert_eq!(uri_ref.resolve_against(&base).unwrap(), "http://example.com/baz");

let uri_ref = UriRef::parse("?baz")?;
assert_eq!(uri_ref.resolve_against(&base).unwrap(), "http://example.com/foo/bar?baz");

pub fn normalize(&self) -> UriRef<String>

Available on crate feature alloc only.

Normalizes the URI reference.

This method applies syntax-based normalization described in Section 6.2.2 of RFC 3986 and Section 5.3.2 of RFC 3987, along with IPv6 address and default port normalization. This is effectively equivalent to taking the following steps in order:

• Decode any percent-encoded octets that correspond to an allowed character which is not reserved.
• Uppercase the hexadecimal digits within all percent-encoded octets.
• Lowercase all ASCII characters within the scheme and the host except the percent-encoded octets.
• Turn any IPv6 literal address into its canonical form as per RFC 5952.
• If the port is empty or equals the scheme’s default, remove it along with the ':' delimiter.
• If self has a scheme and an absolute path, apply the remove_dot_segments algorithm to the path, taking account of percent-encoded dot segments as described at UriRef::resolve_against.
• If self has no authority and its path would start with "//", prepend "/." to the path.

This method is idempotent: self.normalize() equals self.normalize().normalize().

If you need to configure the behavior of normalization, consider using Normalizer instead.

Examples

use fluent_uri::UriRef;

let uri_ref = UriRef::parse("eXAMPLE://a/./b/../b/%63/%7bfoo%7d")?;
assert_eq!(uri_ref.normalize(), "example://a/b/c/%7Bfoo%7D");

pub fn has_scheme(&self) -> bool

Checks whether a scheme component is present.

Examples

use fluent_uri::UriRef;

assert!(UriRef::parse("http://example.com/")?.has_scheme());
assert!(!UriRef::parse("/path/to/file")?.has_scheme());

pub fn has_authority(&self) -> bool

Checks whether an authority component is present.

Examples

use fluent_uri::UriRef;

assert!(UriRef::parse("http://example.com/")?.has_authority());
assert!(!UriRef::parse("mailto:user@example.com")?.has_authority());

pub fn has_query(&self) -> bool

Checks whether a query component is present.

Examples

use fluent_uri::UriRef;

assert!(UriRef::parse("http://example.com/?lang=en")?.has_query());
assert!(!UriRef::parse("ftp://192.0.2.1/")?.has_query());

pub fn has_fragment(&self) -> bool

Checks whether a fragment component is present.

Examples

use fluent_uri::UriRef;

assert!(UriRef::parse("http://example.com/#usage")?.has_fragment());
assert!(!UriRef::parse("ftp://192.0.2.1/")?.has_fragment());

pub fn strip_fragment(&self) -> UriRef<&str>

Returns a slice of this URI reference with the fragment component removed.

Examples

use fluent_uri::UriRef;

let uri_ref = UriRef::parse("http://example.com/#fragment")?;
assert_eq!(uri_ref.strip_fragment(), "http://example.com/");

pub fn with_fragment(&self, opt: Option<&EStr<Fragment>>) -> UriRef<String>

Available on crate feature alloc only.

Creates a new URI reference by replacing the fragment component of self with the given one.

The fragment component is removed when opt.is_none().

Examples

use fluent_uri::{pct_enc::EStr, UriRef};

let uri_ref = UriRef::parse("http://example.com/")?;
assert_eq!(
    uri_ref.with_fragment(Some(EStr::new_or_panic("fragment"))),
    "http://example.com/#fragment"
);

let uri_ref = UriRef::parse("http://example.com/#fragment")?;
assert_eq!(uri_ref.with_fragment(None), "http://example.com/");

impl UriRef<String>

pub fn set_fragment(&mut self, opt: Option<&EStr<Fragment>>)

Available on crate feature alloc only.

Replaces the fragment component of self with the given one.

The fragment component is removed when opt.is_none().

Examples

use fluent_uri::{pct_enc::EStr, UriRef};

let mut uri_ref = UriRef::parse("http://example.com/")?.to_owned();

uri_ref.set_fragment(Some(EStr::new_or_panic("fragment")));
assert_eq!(uri_ref, "http://example.com/#fragment");

uri_ref.set_fragment(None);
assert_eq!(uri_ref, "http://example.com/");

Trait Implementations

impl<T: Bos<str>> AsRef<str> for UriRef<T>

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Bos<str>> Borrow<str> for UriRef<T>

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T: Clone> Clone for UriRef<T>

fn clone(&self) -> UriRef<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Bos<str>> Debug for UriRef<T>

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

Formats the value using the given formatter.

impl<T: Value> Default for UriRef<T>

fn default() -> Self

Creates an empty URI reference.

impl<'de> Deserialize<'de> for UriRef<&'de str>

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de> Deserialize<'de> for UriRef<String>

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Bos<str>> Display for UriRef<T>

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

Formats the value using the given formatter.

impl<T: Bos<str>> From<Uri<T>> for UriRef<T>

fn from(value: Uri<T>) -> Self

Consumes the Uri and creates a new UriRef with the same contents.

impl<'a> From<UriRef<&'a str>> for &'a str

fn from(value: UriRef<&'a str>) -> &'a str

Equivalent to as_str.

impl From<UriRef<&str>> for UriRef<String>

Available on crate feature alloc only.

fn from(value: UriRef<&str>) -> Self

Equivalent to to_owned.

impl<'a> From<UriRef<String>> for String

Available on crate feature alloc only.

fn from(value: UriRef<String>) -> String

Equivalent to into_string.

impl<T: Bos<str>> From<UriRef<T>> for IriRef<T>

fn from(value: UriRef<T>) -> Self

Consumes the UriRef and creates a new IriRef with the same contents.

impl FromStr for UriRef<String>

Available on crate feature alloc only.

fn from_str(s: &str) -> Result<Self, Self::Err>

Equivalent to UriRef::parse(s).map(|r| r.to_owned()).

type Err = ParseError

The associated error which can be returned from parsing.

impl<T: Bos<str>> Hash for UriRef<T>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Bos<str>> Ord for UriRef<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: Bos<str>> PartialEq<&str> for UriRef<T>

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Bos<str>> PartialEq<UriRef<T>> for &str

fn eq(&self, other: &UriRef<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Bos<str>> PartialEq<UriRef<T>> for str

fn eq(&self, other: &UriRef<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Bos<str>, U: Bos<str>> PartialEq<UriRef<U>> for UriRef<T>

fn eq(&self, other: &UriRef<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Bos<str>> PartialEq<str> for UriRef<T>

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Bos<str>> PartialOrd for UriRef<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Bos<str>> Serialize for UriRef<T>

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> TryFrom<&'a str> for UriRef<&'a str>

fn try_from(value: &'a str) -> Result<Self, Self::Error>

Equivalent to parse.

type Error = ParseError

The type returned in the event of a conversion error.

impl<'a> TryFrom<IriRef<&'a str>> for UriRef<&'a str>

fn try_from(value: IriRef<&'a str>) -> Result<Self, Self::Error>

Converts the IRI reference to a URI reference if it is ASCII.

type Error = ConvertError

The type returned in the event of a conversion error.

impl TryFrom<IriRef<String>> for UriRef<String>

Available on crate feature alloc only.

fn try_from(value: IriRef<String>) -> Result<Self, Self::Error>

Converts the IRI reference to a URI reference if it is ASCII.

type Error = (ConvertError, IriRef<String>)

The type returned in the event of a conversion error.

impl TryFrom<String> for UriRef<String>

Available on crate feature alloc only.

fn try_from(value: String) -> Result<Self, Self::Error>

Equivalent to parse.

type Error = (ParseError, String)

The type returned in the event of a conversion error.

impl<'a> TryFrom<UriRef<&'a str>> for Uri<&'a str>

fn try_from(value: UriRef<&'a str>) -> Result<Self, Self::Error>

Converts the URI reference to a URI if it has a scheme.

type Error = ConvertError

The type returned in the event of a conversion error.

impl TryFrom<UriRef<String>> for Uri<String>

Available on crate feature alloc only.

fn try_from(value: UriRef<String>) -> Result<Self, Self::Error>

Converts the URI reference to a URI if it has a scheme.

type Error = (ConvertError, UriRef<String>)

The type returned in the event of a conversion error.

impl<T: Copy> Copy for UriRef<T>

impl<T: Bos<str>> Eq for UriRef<T>