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

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

pub fn parse<I>(input: I) -> Result<Self, I::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.

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

impl Iri<String>

pub fn builder() -> Builder<Self, 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: BorrowOrShare<'i, 'o, str>> Iri<T>

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<IAuthority<'o>>

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

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

Normalizes the IRI.

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

impl<T: Bos<str>> Iri<T>

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");

Trait Implementations

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

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T: Clone> Clone for Iri<T>

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: Bos<str>> Debug for Iri<T>

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

Formats the value using the given formatter.

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

fn default() -> Self

Creates an empty IRI.

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

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

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>

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

Equivalent to to_owned.

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

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

Equivalent to into_string.

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

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

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

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

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

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

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

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

type Error = ParseError

The type returned in the event of a conversion error.

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

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

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

type Error = ParseError<IriRef<String>>

The type returned in the event of a conversion error.

impl TryFrom<String> for Iri<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<T: Copy> Copy for Iri<T>

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