Struct fluent_uri::UriRef

source ·

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

Expand description

A URI reference, i.e., either a URI or a relative reference.

See the crate-level documentation for an explanation of the above terms.

§Variants

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

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

use fluent_uri::UriRef;

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

§Comparison

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

§Examples

Parse and extract components from a URI reference:

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

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

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

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

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

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

use fluent_uri::UriRef;

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

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

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

// Convert a `UriRef<&str>` to `UriRef<String>`.
let uri_ref_owned: UriRef<String> = uri_ref.to_owned();

// Borrow a `UriRef<String>` as `UriRef<&str>`.
let uri_ref: UriRef<&str> = uri_ref_owned.borrow();

Implementations§

source §

impl<T> UriRef<T>

source

pub fn parse(input: I) -> Result<Self, I::Err>
where I: ToUriRef<Val = T>,

Parses a URI reference from a string into a UriRef.

The return type is

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

§Errors

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

Examples found in repository ?

examples/parse_from_stdin.rs (line 7)

fn main() {
    for line in io::stdin().lines() {
        let line = line.expect("failed to read line");
        match UriRef::parse(line) {
            Ok(r) => println!("{r:#?}"),
            Err(e) => println!("Error: {e}"),
        };
    }
}

source §

impl UriRef<String>

source

pub fn builder() -> Builder<Start>

Creates a new builder for URI reference.

source

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

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

source

pub fn into_string(self) -> String

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

source §

impl UriRef<&str>

source

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

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

source §

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

source

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

Returns the URI reference as a string slice.

source

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

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

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

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

source

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

Returns the optional authority component.

§Examples

use fluent_uri::UriRef;

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

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

source

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

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

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

let uri_ref = UriRef::parse("?lang=en")?;
assert_eq!(uri_ref.path(), "");

source

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

Returns the optional query component.

§Examples

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

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

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

source

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

Returns the optional fragment component.

§Examples

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

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

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

source

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

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

The base URI must contain a scheme and no fragment, i.e., match the absolute-URI ABNF rule from RFC 3986.

This method applies the reference resolution algorithm defined in Section 5 of RFC 3986, except for the following deviations:

If base contains no authority and its path is rootless, then self must either contain a scheme, be empty, or start with '#'.
When the target URI contains 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.
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/.%2E/" yields "foo:/bar/", while first normalizing the base URI and then resolving ".." against it yields "foo:/".
A slash ('/') is appended to the base URI 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 URI and then resolving "." against it yields "foo:/".

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

§Errors

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

§Examples

use fluent_uri::UriRef;

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

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

source

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

Normalizes the URI reference.

This method applies the syntax-based normalization described in Section 6.2.2 of RFC 3986, which is effectively equivalent to taking the following steps in order:

Decode any percent-encoded octet that corresponds to an unreserved character.
Uppercase the hexadecimal digits within all percent-encoded octets.
Lowercase 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 the URI reference 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 resolve_against.
If the URI reference 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::UriRef;

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

source

pub fn is_uri(&self) -> bool

Checks whether the URI reference is a URI, i.e., contains a scheme.

This method is equivalent to has_scheme.

§Examples

use fluent_uri::UriRef;

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

source

pub fn has_scheme(&self) -> bool

Checks whether the URI reference contains a scheme component.

§Examples

use fluent_uri::UriRef;

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

source

pub fn has_authority(&self) -> bool

Checks whether the URI reference contains an authority component.

§Examples

use fluent_uri::UriRef;

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

source

pub fn has_query(&self) -> bool

Checks whether the URI reference contains a query component.

§Examples

use fluent_uri::UriRef;

assert!(UriRef::parse("http://example.com/?lang=en")?.has_query());
assert!(!UriRef::parse("ftp://192.0.2.1/")?.has_query());

source

pub fn has_fragment(&self) -> bool

Checks whether the URI reference contains a fragment component.

§Examples

use fluent_uri::UriRef;

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