Struct Iri 

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

An IRI.

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

Variants

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

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

use fluent_uri::Iri;

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

Comparison

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

Examples

Parse and extract components from an IRI:

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

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

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

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

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

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

use fluent_uri::Iri;

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

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

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

// Convert a `Iri<&str>` to `Iri<String>`.
let iri_owned: Iri<String> = iri.to_owned();

// Borrow a `Iri<String>` as `Iri<&str>`.
let iri: Iri<&str> = iri_owned.borrow();

Implementations

impl<T> Iri<T>

where T: Bos<str>,

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

Converts the IRI to a URI by percent-encoding non-ASCII characters.

Punycode encoding is not performed during conversion.

Examples

use fluent_uri::Iri;

let iri = Iri::parse("http://www.example.org/résumé.html").unwrap();
assert_eq!(iri.to_uri(), "http://www.example.org/r%C3%A9sum%C3%A9.html");

let iri = Iri::parse("http://résumé.example.org").unwrap();
assert_eq!(iri.to_uri(), "http://r%C3%A9sum%C3%A9.example.org");

impl<T> Iri<T>

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

where I: Parse<Val = T>,

Parses an IRI from a string into an Iri.

The return type is

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

Errors

Returns Err if the string does not match the IRI ABNF rule from RFC 3987.

impl Iri<String>

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

Creates a new builder for IRI.

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

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

pub fn into_string(self) -> String

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

impl Iri<&str>

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

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

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

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

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

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

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

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

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

Returns the optional authority component.

Examples

use fluent_uri::Iri;

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

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

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

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

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

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

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

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

Returns the optional query component.

Examples

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

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

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

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

Returns the optional fragment component.

Examples

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

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

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

impl<T> Iri<T>

where T: Bos<str>,

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

Normalizes the IRI.

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

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

pub fn has_authority(&self) -> bool

Checks whether an authority component is present.

Examples

use fluent_uri::Iri;

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

pub fn has_query(&self) -> bool

Checks whether a query component is present.

Examples

use fluent_uri::Iri;

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

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

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

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

Examples

use fluent_uri::Iri;

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

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

Creates a new IRI 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, Iri};

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

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

impl Iri<String>

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

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, Iri};

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

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

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

Trait Implementations

impl<T> AsRef<str> for Iri<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 Iri<T>

where T: Bos<str>,

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T> Clone for Iri<T>

where T: Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Iri<T>

where T: Bos<str>,

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

Formats the value using the given formatter.

impl<T> Default for Iri<T>

where T: Value,

fn default() -> Iri<T>

Creates an empty IRI.

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

Available on crate feature serde only.

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

Available on crate feature serde only.

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for Iri<T>

where T: Bos<str>,

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

Formats the value using the given formatter.

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

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

Equivalent to as_str.

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

Available on crate feature alloc only.

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

Equivalent to to_owned.

impl<T> From<Iri<T>> for IriRef<T>

where T: Bos<str>,

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

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

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

Available on crate feature alloc only.

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

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

type Err = ParseError

The associated error which can be returned from parsing.

impl<T> Hash for Iri<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 Iri<T>

where T: Bos<str>,

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

where T: Bos<str>,

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

where T: Bos<str>,

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

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

fn eq(&self, other: &Iri<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 Iri<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 Iri<T>

where T: Bos<str>,

fn partial_cmp(&self, other: &Iri<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 Iri<T>

where T: Bos<str>,

Available on crate feature serde only.

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 Iri<&'a str>

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

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

Converts the IRI reference to an IRI if it has a scheme.

type Error = ConvertError

The type returned in the event of a conversion error.

impl TryFrom<IriRef<String>> for Iri<String>

Available on crate feature alloc only.

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

Converts the IRI reference to an IRI if it has a scheme.

type Error = (ConvertError, IriRef<String>)

The type returned in the event of a conversion error.

impl TryFrom<String> for Iri<String>

Available on crate feature alloc only.

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

Equivalent to parse.

type Error = (ParseError, String)

The type returned in the event of a conversion error.

impl<T> Copy for Iri<T>

where T: Copy,

impl<T> Eq for Iri<T>

where T: Bos<str>,