Struct rocket_http::uri::Reference[−][src]

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

Expand description

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>[src]

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

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>>[src]

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>[src]

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>>[src]

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<'_>[src]

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<'_>>[src]

Returns the query part. May be empty.

Example

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

// Empty query parts are normalized away by `uri!()`.
let uri = uri!("http://rocket.rs/guide?#bar");
assert!(uri.query().is_none());

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

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[src]

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:/foo//bar").unwrap().is_normalized());
assert!(!Reference::parse("foo:bar?baz&&bop#c").unwrap().is_normalized());
assert!(!Reference::parse("http://rocket.rs?#foo").unwrap().is_normalized());

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

pub fn normalize(&mut self)[src]

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());
uri.normalize();
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) -> Self[src]

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>[src]

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

Returns a copy of the value. Read more

fn clone_from(&mut self, source: &Self)1.0.0 [src]

Performs copy-assignment from source. Read more

impl<'a> Debug for Reference<'a>[src]

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

Formats the value using the given formatter. Read more

impl Display for Reference<'_>[src]

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

Formats the value using the given formatter. Read more

impl<'a> From<Absolute<'a>> for Reference<'a>[src]

fn from(absolute: Absolute<'a>) -> Self[src]

Performs the conversion.

impl From<Asterisk> for Reference<'_>[src]

fn from(_: Asterisk) -> Self[src]

Performs the conversion.

impl<'a> From<Authority<'a>> for Reference<'a>[src]

fn from(authority: Authority<'a>) -> Self[src]

Performs the conversion.

impl<'a> From<Origin<'a>> for Reference<'a>[src]

fn from(origin: Origin<'a>) -> Self[src]

Performs the conversion.

impl<'a> From<Reference<'a>> for Uri<'a>[src]

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

Performs the conversion.

impl IntoOwned for Reference<'_>[src]

type Owned = Reference<'static>

The owned version of the type.

fn into_owned(self) -> Self::Owned[src]

Converts self into an owned version of itself.

impl PartialEq<Reference<'_>> for Reference<'_>[src]

fn eq(&self, other: &Reference<'_>) -> bool[src]

This method tests for self and other values to be equal, and is used by ==. Read more

#[must_use]
fn ne(&self, other: &Rhs) -> bool

1.0.0 [src]

This method tests for !=.

impl<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>[src]

fn eq(&self, other: &Reference<'a>) -> bool[src]

This method tests for self and other values to be equal, and is used by ==. Read more

#[must_use]
fn ne(&self, other: &Rhs) -> bool

1.0.0 [src]

This method tests for !=.

impl<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>[src]

fn eq(&self, other: &Uri<'b>) -> bool[src]

This method tests for self and other values to be equal, and is used by ==. Read more

#[must_use]
fn ne(&self, other: &Rhs) -> bool

1.0.0 [src]

This method tests for !=.

impl<'a> TryFrom<&'a String> for Reference<'a>[src]

type Error = Error<'a>

The type returned in the event of a conversion error.

fn try_from(value: &'a String) -> Result<Self, Self::Error>[src]

Performs the conversion.

impl<'a> TryFrom<&'a str> for Reference<'a>[src]

type Error = Error<'a>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<String> for Reference<'static>[src]

type Error = Error<'static>

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>[src]

Performs the conversion.

impl<'a> TryFrom<Uri<'a>> for Reference<'a>[src]

type Error = TryFromUriError

The type returned in the event of a conversion error.

fn try_from(uri: Uri<'a>) -> Result<Self, Self::Error>[src]

Performs the conversion.

Auto Trait Implementations

impl<'a> !RefUnwindSafe for Reference<'a>

impl<'a> Send for Reference<'a>

impl<'a> Sync for Reference<'a>

impl<'a> Unpin for Reference<'a>

impl<'a> UnwindSafe for Reference<'a>

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized,

[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized,

[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized,

[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>,

[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T[src]

pub fn into_collection<A>(Self) -> SmallVec<A> where
    A: Array<Item = T>,

[src]

Converts self into a collection.

pub fn mapped<U, F, A>(Self, F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>,

[src]

impl<T> ToOwned for T where
    T: Clone,

[src]

type Owned = T

The resulting type after obtaining ownership.

pub fn to_owned(&self) -> T[src]

Creates owned data from borrowed data, usually by cloning. Read more

pub fn clone_into(&self, target: &mut T)[src]

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T> ToString for T where
    T: Display + ?Sized,

[src]

pub default fn to_string(&self) -> String[src]

Converts the given value to a String. Read more

impl<T, U> TryFrom<U> for T where
    U: Into<T>,

[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>,

[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.