Struct Uri

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

A URI.

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

Variants

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

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

use fluent_uri::Uri;

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

Comparison

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

Examples

Parse and extract components from a URI:

use fluent_uri::{
    component::{Host, Scheme},
    encoding::EStr,
    Uri,
};

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

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

assert_eq!(uri.scheme(), SCHEME_FOO);

let auth = uri.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.path(), "/over/there");
assert_eq!(uri.query().unwrap(), "name=ferret");
assert_eq!(uri.fragment().unwrap(), "nose");

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

use fluent_uri::Uri;

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

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

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

// Convert a `Uri<&str>` to `Uri<String>`.
let uri_owned: Uri<String> = uri.to_owned();

// Borrow a `Uri<String>` as `Uri<&str>`.
let uri: Uri<&str> = uri_owned.borrow();

Implementations

impl<T> Uri<T>

pub fn parse<I>(input: I) -> Result<Uri<T>, <I as Parse>::Err>

where I: Parse<Val = T>,

Parses a URI from a string into a Uri.

The return type is

• Result<Uri<&str>, ParseError> for I = &str;
• Result<Uri<String>, ParseError<String>> for I = String.

Errors

Returns Err if the string does not match the URI 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 Uri<String>

pub fn builder() -> Builder<Uri<String>, NonRefStart>

Creates a new builder for URI.

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

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

pub fn into_string(self) -> String

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

impl Uri<&str>

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

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

impl<'i, 'o, T> Uri<T>

where T: BorrowOrShare<'i, 'o, str>,

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

Returns the URI as a string slice.

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

Returns the 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, Uri};

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

let uri = Uri::parse("http://example.com/")?;
assert_eq!(uri.scheme(), SCHEME_HTTP);

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

Returns the optional authority component.

Examples

use fluent_uri::Uri;

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

let uri = Uri::parse("mailto:user@example.com")?;
assert!(uri.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::Uri;

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

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

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

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

Returns the optional query component.

Examples

use fluent_uri::{encoding::EStr, Uri};

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

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

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

Returns the optional fragment component.

Examples

use fluent_uri::{encoding::EStr, Uri};

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

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

impl<'i, 'o, T> Uri<T>

where T: Bos<str>,

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

Normalizes the URI.

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::Uri;

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

pub fn has_authority(&self) -> bool

Checks whether an authority component is present.

Examples

use fluent_uri::Uri;

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

pub fn has_query(&self) -> bool

Checks whether a query component is present.

Examples

use fluent_uri::Uri;

assert!(Uri::parse("http://example.com/?lang=en")?.has_query());
assert!(!Uri::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::Uri;

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

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

Creates a new URI 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, Uri};

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

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

impl Uri<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, Uri};

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

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

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

Trait Implementations

impl<T> AsRef<str> for Uri<T>

where T: Bos<str>,

fn as_ref(&self) -> &str

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

impl<T> Borrow<str> for Uri<T>

where T: Bos<str>,

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T> Clone for Uri<T>

where T: Clone,

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Uri<T>

where T: Bos<str>,

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

Formats the value using the given formatter.

impl<T> Default for Uri<T>

where T: Value,

fn default() -> Uri<T>

Creates an empty URI.

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

fn deserialize<D>( deserializer: D, ) -> Result<Uri<&'de str>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

fn deserialize<D>( deserializer: D, ) -> Result<Uri<String>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for Uri<T>

where T: Bos<str>,

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

Formats the value using the given formatter.

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

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

Equivalent to as_str.

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

fn from(value: Uri<&str>) -> Uri<String>

Equivalent to to_owned.

impl<T> From<Uri<T>> for Iri<T>

where T: Bos<str>,

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

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

impl<T> From<Uri<T>> for IriRef<T>

where T: Bos<str>,

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

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

impl<T> From<Uri<T>> for UriRef<T>

where T: Bos<str>,

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

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

impl FromStr for Uri<String>

fn from_str(s: &str) -> Result<Uri<String>, <Uri<String> as FromStr>::Err>

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

type Err = ParseError

The associated error which can be returned from parsing.

impl<T> Hash for Uri<T>

where T: Bos<str>,

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

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Uri<T>

where T: Bos<str>,

fn cmp(&self, other: &Uri<T>) -> 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> PartialEq<&str> for Uri<T>

where T: Bos<str>,

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> PartialEq<Uri<T>> for &str

where T: Bos<str>,

fn eq(&self, other: &Uri<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> PartialEq<Uri<T>> for str

where T: Bos<str>,

fn eq(&self, other: &Uri<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, U> PartialEq<Uri<U>> for Uri<T>

where T: Bos<str>, U: Bos<str>,

fn eq(&self, other: &Uri<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> PartialEq<str> for Uri<T>

where T: Bos<str>,

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> PartialOrd for Uri<T>

where T: Bos<str>,

fn partial_cmp(&self, other: &Uri<T>) -> 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> Serialize for Uri<T>

where T: Bos<str>,

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

where S: Serializer,

Serialize this value into the given Serde serializer.

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

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

Equivalent to parse.

type Error = ParseError

The type returned in the event of a conversion error.

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

fn try_from( value: Iri<&'a str>, ) -> Result<Uri<&'a str>, <Uri<&'a str> as TryFrom<Iri<&'a str>>>::Error>

Converts the IRI to a URI if it is ASCII.

type Error = ParseError

The type returned in the event of a conversion error.

impl TryFrom<Iri<String>> for Uri<String>

fn try_from( value: Iri<String>, ) -> Result<Uri<String>, <Uri<String> as TryFrom<Iri<String>>>::Error>

Converts the IRI to a URI if it is ASCII.

type Error = ParseError<Iri<String>>

The type returned in the event of a conversion error.

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

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

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

type Error = ParseError

The type returned in the event of a conversion error.

impl TryFrom<IriRef<String>> for Uri<String>

fn try_from( value: IriRef<String>, ) -> Result<Uri<String>, <Uri<String> as TryFrom<IriRef<String>>>::Error>

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

type Error = ParseError<IriRef<String>>

The type returned in the event of a conversion error.

impl TryFrom<String> for Uri<String>

fn try_from( value: String, ) -> Result<Uri<String>, <Uri<String> as TryFrom<String>>::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<Uri<&'a str>, <Uri<&'a str> as TryFrom<UriRef<&'a str>>>::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<Uri<String>, <Uri<String> as TryFrom<UriRef<String>>>::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 for Uri<T>

where T: Copy,

impl<T> Eq for Uri<T>

where T: Bos<str>,