Struct IriRef 

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

An IRI reference, i.e., either a IRI or a relative reference.

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

Variants

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

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

use fluent_uri::IriRef;

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

Comparison

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

Examples

Parse and extract components from an IRI reference:

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

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

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

assert_eq!(iri_ref.scheme().unwrap(), SCHEME_FOO);

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

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

use fluent_uri::IriRef;

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

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

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

// Convert a `IriRef<&str>` to `IriRef<String>`.
let iri_ref_owned: IriRef<String> = iri_ref.to_owned();

// Borrow a `IriRef<String>` as `IriRef<&str>`.
let iri_ref: IriRef<&str> = iri_ref_owned.borrow();

Implementations

impl<T: Bos<str>> IriRef<T>

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

Available on crate feature alloc only.

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

Punycode encoding is not performed during conversion.

Examples

use fluent_uri::IriRef;

let iri_ref = IriRef::parse("résumé.html").unwrap();
assert_eq!(iri_ref.to_uri_ref(), "r%C3%A9sum%C3%A9.html");

let iri_ref = IriRef::parse("//résumé.example.org").unwrap();
assert_eq!(iri_ref.to_uri_ref(), "//r%C3%A9sum%C3%A9.example.org");

impl<T> IriRef<T>

pub fn parse<I>(input: I) -> Result<Self, I::Err>

where I: Parse<Val = T>,

Parses an IRI reference from a string into an IriRef.

The return type is

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

Errors

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

impl IriRef<String>

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

Available on crate feature alloc only.

Creates a new builder for IRI reference.

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

Available on crate feature alloc only.

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

pub fn into_string(self) -> String

Available on crate feature alloc only.

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

impl IriRef<&str>

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

Available on crate feature alloc only.

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

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

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

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

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

let iri_ref = IriRef::parse("http://example.com/")?;
assert_eq!(iri_ref.scheme(), Some(SCHEME_HTTP));

let iri_ref = IriRef::parse("/path/to/file")?;
assert_eq!(iri_ref.scheme(), None);

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

Returns the optional authority component.

Examples

use fluent_uri::IriRef;

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

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

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

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

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

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

Returns the optional query component.

Examples

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

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

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

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

Returns the optional fragment component.

Examples

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

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

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

impl<T: Bos<str>> IriRef<T>

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

Available on crate feature alloc only.

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

The base IRI must have no fragment, i.e., match the absolute-IRI ABNF rule from RFC 3987.

To prepare a base IRI, you can use strip_fragment, with_fragment or set_fragment to remove the fragment from any IRI. 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 has a rootless path and no authority, then self must either have a scheme, be empty, or start with '#'.
• When the target has 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/baz/.%2E/" yields "foo:/bar/baz/", 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:/".
• When base has an absolute path and self has an empty path and no scheme nor authority, dot segments are removed from the base path before using it as the target path. This closes a loophole in the original algorithm that resolving "" against "foo:/." yields "foo:/." in which dot segments are not removed.

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

If you need to resolve multiple references against a common base or configure the behavior of resolution, consider using Resolver instead.

Errors

Returns Err if any of the above two musts is violated.

Examples

use fluent_uri::{Iri, IriRef};

let base = Iri::parse("http://example.com/foo/bar")?;

let iri_ref = IriRef::parse("baz")?;
assert_eq!(iri_ref.resolve_against(&base).unwrap(), "http://example.com/foo/baz");

let iri_ref = IriRef::parse("../baz")?;
assert_eq!(iri_ref.resolve_against(&base).unwrap(), "http://example.com/baz");

let iri_ref = IriRef::parse("?baz")?;
assert_eq!(iri_ref.resolve_against(&base).unwrap(), "http://example.com/foo/bar?baz");

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

Available on crate feature alloc only.

Normalizes the IRI reference.

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

let iri_ref = IriRef::parse("eXAMPLE://a/./b/../b/%63/%7bfoo%7d")?;
assert_eq!(iri_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::IriRef;

assert!(IriRef::parse("http://example.com/")?.has_scheme());
assert!(!IriRef::parse("/path/to/file")?.has_scheme());

pub fn has_authority(&self) -> bool

Checks whether an authority component is present.

Examples

use fluent_uri::IriRef;

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

pub fn has_query(&self) -> bool

Checks whether a query component is present.

Examples

use fluent_uri::IriRef;

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

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

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

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

Examples

use fluent_uri::IriRef;

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

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

Available on crate feature alloc only.

Creates a new IRI 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::{pct_enc::EStr, IriRef};

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

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

impl IriRef<String>

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

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

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

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

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

Trait Implementations

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

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<T: Clone> Clone for IriRef<T>

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Creates an empty IRI reference.

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

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

Formats the value using the given formatter.

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<'a> From<IriRef<&'a str>> for &'a str

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

Equivalent to as_str.

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

Available on crate feature alloc only.

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

Equivalent to to_owned.

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

Available on crate feature alloc only.

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

Equivalent to into_string.

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<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 IriRef<String>

Available on crate feature alloc only.

fn from_str(s: &str) -> Result<Self, Self::Err>

Equivalent to IriRef::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 IriRef<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 IriRef<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 IriRef<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<IriRef<T>> for &str

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

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

fn eq(&self, other: &IriRef<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 IriRef<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 IriRef<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 IriRef<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 IriRef<&'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 Iri<&'a str>

fn try_from(value: IriRef<&'a str>) -> Result<Self, Self::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<'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<'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 = 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<Self, Self::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<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<IriRef<String>> for UriRef<String>

Available on crate feature alloc only.

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

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

type Error = (ConvertError, IriRef<String>)

The type returned in the event of a conversion error.

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

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