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},
    pct_enc::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.0)?;

// 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<Self, I::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.

impl Uri<String>

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

Available on crate feature alloc only.

Creates a new builder for URI.

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

Available on crate feature alloc only.

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

pub fn into_string(self) -> String

Available on crate feature alloc only.

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

impl Uri<&str>

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

Available on crate feature alloc only.

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

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

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::{pct_enc::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::{pct_enc::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<T: Bos<str>> Uri<T>

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

Available on crate feature alloc only.

Normalizes the URI.

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::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 strip_fragment(&self) -> Uri<&str>

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

Examples

use fluent_uri::Uri;

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

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

Available on crate feature alloc only.

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

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, 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: Bos<str>> AsRef<str> for Uri<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 Uri<T>

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T: Clone> Clone for Uri<T>

fn clone(&self) -> Uri<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 Uri<T>

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

Formats the value using the given formatter.

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

fn default() -> Self

Creates an empty URI.

impl<'de> Deserialize<'de> for Uri<&'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 Uri<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 Uri<T>

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

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>

Available on crate feature alloc only.

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

Equivalent to to_owned.

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

Available on crate feature alloc only.

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

Equivalent to into_string.

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

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

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

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

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

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

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 FromStr for Uri<String>

Available on crate feature alloc only.

fn from_str(s: &str) -> Result<Self, Self::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: Bos<str>> Hash for Uri<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 Uri<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 Uri<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<Uri<T>> for &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: Bos<str>> PartialEq<Uri<T>> for 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: Bos<str>, U: Bos<str>> PartialEq<Uri<U>> for Uri<T>

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: Bos<str>> PartialEq<str> for Uri<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 Uri<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 Uri<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 Uri<&'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<Iri<&'a str>> for Uri<&'a str>

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

Converts the IRI to a URI if it is ASCII.

type Error = ConvertError

The type returned in the event of a conversion error.

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

Available on crate feature alloc only.

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

Converts the IRI to a URI if it is ASCII.

type Error = (ConvertError, 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<Self, Self::Error>

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

type Error = ConvertError

The type returned in the event of a conversion error.

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

Available on crate feature alloc only.

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

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

type Error = (ConvertError, IriRef<String>)

The type returned in the event of a conversion error.

impl TryFrom<String> for Uri<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 Uri<T>

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