Struct Reference

pub struct Reference<'a> { /* private fields */ }

A URI-reference with optional scheme, authority, relative path, query, and fragment parts.

Structure

The following diagram illustrates the syntactic structure of a URI reference with all optional parts:

 http://user:pass@domain.com:4444/foo/bar?some=query#and-fragment
 |--|  |------------------------||------| |--------| |----------|
scheme          authority          path      query     fragment

All parts are optional. When a scheme and authority are not present, the path may be relative: foo/bar?baz#cat.

Conversion

All other URI types (Origin, Absolute, and so on) are valid URI references. As such, conversion between the types is lossless:

use rocket::http::uri::Reference;

let absolute = uri!("http://rocket.rs");
let reference: Reference = absolute.into();
assert_eq!(reference.scheme(), Some("http"));
assert_eq!(reference.authority().unwrap().host(), "rocket.rs");

let origin = uri!("/foo/bar");
let reference: Reference = origin.into();
assert_eq!(reference.path(), "/foo/bar");

Note that uri!() macro always prefers the more specific URI variant to Reference when possible, as is demonstrated above for absolute and origin.

(De)serialization

Reference is both Serialize and Deserialize:

use serde::{Serialize, Deserialize};
use rocket::http::uri::Reference;

#[derive(Deserialize, Serialize)]
struct UriOwned {
    uri: Reference<'static>,
}

#[derive(Deserialize, Serialize)]
struct UriBorrowed<'a> {
    uri: Reference<'a>,
}

Implementations

impl<'a> Reference<'a>

pub fn parse(string: &'a str) -> Result<Reference<'a>, Error<'a>>

Parses the string string into an Reference. Parsing will never allocate. Returns an Error if string is not a valid origin URI.

Example

use rocket::http::uri::Reference;

// Parse a valid URI reference.
let uri = Reference::parse("/a/b/c?query").expect("valid URI");
assert_eq!(uri.path(), "/a/b/c");
assert_eq!(uri.query().unwrap(), "query");

// Invalid URIs fail to parse.
Reference::parse("foo bar").expect_err("invalid URI");

// Prefer to use `uri!()` when the input is statically known:
let uri = uri!("/a/b/c?query#fragment");
assert_eq!(uri.path(), "/a/b/c");
assert_eq!(uri.query().unwrap(), "query");
assert_eq!(uri.fragment().unwrap(), "fragment");

pub fn parse_owned(string: String) -> Result<Reference<'static>, Error<'static>>

Parses the string string into a Reference. Allocates minimally on success and error.

This method should be used instead of Reference::parse() when the source URI is already a String. Returns an Error if string is not a valid URI reference.

Example

use rocket::http::uri::Reference;

let source = format!("/foo?{}#3", 2);
let uri = Reference::parse_owned(source).unwrap();
assert_eq!(uri.path(), "/foo");
assert_eq!(uri.query().unwrap(), "2");
assert_eq!(uri.fragment().unwrap(), "3");

pub fn scheme(&self) -> Option<&str>

Returns the scheme. If Some, is non-empty.

Example

let uri = uri!("http://rocket.rs?foo#bar");
assert_eq!(uri.scheme(), Some("http"));

let uri = uri!("ftp:/?foo#bar");
assert_eq!(uri.scheme(), Some("ftp"));

let uri = uri!("?foo#bar");
assert_eq!(uri.scheme(), None);

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

Returns the authority part.

Example

let uri = uri!("http://rocket.rs:4444?foo#bar");
let auth = uri!("rocket.rs:4444");
assert_eq!(uri.authority().unwrap(), &auth);

let uri = uri!("?foo#bar");
assert_eq!(uri.authority(), None);

pub fn path(&self) -> Path<'_>

Returns the path part. May be empty.

Example

let uri = uri!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.path(), "/guide");

pub fn query(&self) -> Option<Query<'_>>

Returns the query part. May be empty.

Example

let uri = uri!("http://rocket.rs/guide");
assert!(uri.query().is_none());

let uri = uri!("http://rocket.rs/guide?");
assert_eq!(uri.query().unwrap(), "");

let uri = uri!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.query().unwrap(), "foo");

let uri = uri!("http://rocket.rs/guide?q=bar");
assert_eq!(uri.query().unwrap(), "q=bar");

pub fn fragment(&self) -> Option<&RawStr>

Returns the fragment part, if any.

Example

let uri = uri!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.fragment().unwrap(), "bar");

// Fragment parts aren't normalized away, unlike query parts.
let uri = uri!("http://rocket.rs/guide?foo#");
assert_eq!(uri.fragment().unwrap(), "");

pub fn is_normalized(&self) -> bool

Returns true if self is normalized. Otherwise, returns false.

Normalization for a URI reference is equivalent to normalization for an absolute URI. See Absolute for more information on what it means for an absolute URI to be normalized.

Example

use rocket::http::uri::Reference;

assert!(Reference::parse("foo/bar").unwrap().is_normalized());
assert!(Reference::parse("foo/bar#").unwrap().is_normalized());
assert!(Reference::parse("http://").unwrap().is_normalized());
assert!(Reference::parse("http://foo.rs/foo/bar").unwrap().is_normalized());
assert!(Reference::parse("foo:bar#baz").unwrap().is_normalized());
assert!(Reference::parse("http://rocket.rs#foo").unwrap().is_normalized());
assert!(Reference::parse("http://?").unwrap().is_normalized());
assert!(Reference::parse("git://rocket.rs/").unwrap().is_normalized());
assert!(Reference::parse("http://rocket.rs?#foo").unwrap().is_normalized());
assert!(Reference::parse("http://rocket.rs#foo").unwrap().is_normalized());

assert!(!Reference::parse("http:/foo//bar").unwrap().is_normalized());
assert!(!Reference::parse("foo:bar?baz&&bop#c").unwrap().is_normalized());

// Recall that `uri!()` normalizes static input.
assert!(uri!("http:/foo//bar").is_normalized());
assert!(uri!("foo:bar?baz&&bop#c").is_normalized());
assert!(uri!("http://rocket.rs///foo////bar#cat").is_normalized());

pub fn normalize(&mut self)

Normalizes self in-place. Does nothing if self is already normalized.

Example

use rocket::http::uri::Reference;

let mut uri = Reference::parse("git://rocket.rs/").unwrap();
assert!(uri.is_normalized());

let mut uri = Reference::parse("http:/foo//bar?baz&&#cat").unwrap();
assert!(!uri.is_normalized());
uri.normalize();
assert!(uri.is_normalized());

let mut uri = Reference::parse("foo:bar?baz&&bop").unwrap();
assert!(!uri.is_normalized());
uri.normalize();
assert!(uri.is_normalized());

pub fn into_normalized(self) -> Reference<'a>

Normalizes self. This is a no-op if self is already normalized.

Example

use rocket::http::uri::Reference;

let mut uri = Reference::parse("git://rocket.rs/").unwrap();
assert!(uri.is_normalized());
assert!(uri.into_normalized().is_normalized());

let mut uri = Reference::parse("http:/foo//bar?baz&&#cat").unwrap();
assert!(!uri.is_normalized());
assert!(uri.into_normalized().is_normalized());

let mut uri = Reference::parse("foo:bar?baz&&bop").unwrap();
assert!(!uri.is_normalized());
assert!(uri.into_normalized().is_normalized());

Trait Implementations

impl<'a> Clone for Reference<'a>

fn clone(&self) -> Reference<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Reference<'a>

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

Formats the value using the given formatter.

impl<'a, 'de> Deserialize<'de> for Reference<'a>

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Reference<'_>

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

Formats the value using the given formatter.

impl<'a> From<Absolute<'a>> for Reference<'a>

fn from(absolute: Absolute<'a>) -> Reference<'a>

Converts to this type from the input type.

impl From<Asterisk> for Reference<'_>

fn from(_: Asterisk) -> Reference<'_>

Converts to this type from the input type.

impl<'a> From<Authority<'a>> for Reference<'a>

fn from(authority: Authority<'a>) -> Reference<'a>

Converts to this type from the input type.

impl<'a> From<Origin<'a>> for Reference<'a>

fn from(origin: Origin<'a>) -> Reference<'a>

Converts to this type from the input type.

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

fn from(other: Reference<'a>) -> Uri<'a>

Converts to this type from the input type.

impl Hash for Reference<'_>

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 IntoOwned for Reference<'_>

type Owned = Reference<'static>

The owned version of the type.

fn into_owned(self) -> Reference<'static>

Converts self into an owned version of itself.

impl<'b, 'a> PartialEq<&Reference<'a>> for Uri<'b>

fn eq(&self, other: &&Reference<'a>) -> 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 PartialEq<&str> for Reference<'_>

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 PartialEq<Reference<'_>> for str

fn eq(&self, other: &Reference<'_>) -> 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<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>

fn eq(&self, other: &Reference<'a>) -> 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<'a, 'b> PartialEq<Reference<'b>> for Reference<'a>

fn eq(&self, other: &Reference<'b>) -> 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<'b, 'a> PartialEq<Uri<'b>> for &Reference<'a>

fn eq(&self, other: &Uri<'b>) -> 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<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>

fn eq(&self, other: &Uri<'b>) -> 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 PartialEq<str> for Reference<'_>

fn eq(&self, string: &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<'a> Serialize for Reference<'a>

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 String> for Reference<'a>

type Error = Error<'a>

The type returned in the event of a conversion error.

fn try_from( value: &'a String, ) -> Result<Reference<'a>, <Reference<'a> as TryFrom<&'a String>>::Error>

Performs the conversion.

impl<'a> TryFrom<&'a str> for Reference<'a>

type Error = Error<'a>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<String> for Reference<'static>

type Error = Error<'static>

The type returned in the event of a conversion error.

fn try_from( value: String, ) -> Result<Reference<'static>, <Reference<'static> as TryFrom<String>>::Error>

Performs the conversion.

impl<'a> TryFrom<Uri<'a>> for Reference<'a>

type Error = TryFromUriError

The type returned in the event of a conversion error.

fn try_from( uri: Uri<'a>, ) -> Result<Reference<'a>, <Reference<'a> as TryFrom<Uri<'a>>>::Error>

Performs the conversion.

impl Eq for Reference<'_>