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},
    encoding::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.strip_input())?;

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

From a ParseError<String>, you may recover or strip the input by calling into_input or strip_input on it.

impl UriRef<String>

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

Creates a new builder for URI reference.

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

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

pub fn into_string(self) -> String

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

impl UriRef<&str>

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

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::{encoding::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::{encoding::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<'i, 'o, T: Bos<str>> UriRef<T>

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

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

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

To prepare a base URI, you can use 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 contains no authority and its path is rootless, then self must either contain a scheme, be empty, or start with '#'.
• When the target contains 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/.%2E/" yields "foo:/bar/", 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:/".

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().

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>

Normalizes the URI reference.

This method applies the syntax-based normalization described in Section 6.2.2 of RFC 3986 and Section 5.3.2 of RFC 3987, which 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, remove its ':' delimiter.
• If self contains 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 contains no authority and its path would start with "//", prepend "/." to the path.

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

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 with_fragment(&self, opt: Option<&EStr<Fragment>>) -> UriRef<String>

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::{encoding::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>>)

Replaces the fragment component of self with the given one.

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

Examples

use fluent_uri::{encoding::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 copy 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>

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

Equivalent to to_owned.

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

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>

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

The type returned in the event of a conversion error.

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

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

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

type Error = ParseError<IriRef<String>>

The type returned in the event of a conversion error.

impl TryFrom<String> for UriRef<String>

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 contains a scheme.

type Error = ParseError

The type returned in the event of a conversion error.

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

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

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

type Error = ParseError<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>