rocket::http::uri

Struct Reference

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

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>

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

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

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