Struct RouteUri

pub struct RouteUri<'a> {
    pub base: Origin<'a>,
    pub unmounted_origin: Origin<'a>,
    pub origin: Origin<'a>,
    /* private fields */
}

A route URI which is matched against requests.

A route URI is composed of two components:

• base

  Otherwise known as the route’s “mount point”, the base is a static Origin that prefixes the route URI. All route URIs have a base. When routes are created manually with Route::new(), the base defaults to /. When mounted via Rocket::mount(), the base is explicitly specified as the first argument.

  use rocket::Route;
  use rocket::http::Method;
  
  let route = Route::new(Method::Get, "/foo/<bar>", handler);
  assert_eq!(route.uri.base(), "/");
  
  let rocket = rocket::build().mount("/base", vec![route]);
  let routes: Vec<_> = rocket.routes().collect();
  assert_eq!(routes[0].uri.base(), "/base");

• origin

  Otherwise known as the “route URI”, the origin is an Origin with potentially dynamic (<dyn> or <dyn..>) segments. It is prefixed with the base. This is the URI which is matched against incoming requests for routing.

  use rocket::Route;
  use rocket::http::Method;
  
  let route = Route::new(Method::Get, "/foo/<bar>", handler);
  assert_eq!(route.uri, "/foo/<bar>");
  
  let rocket = rocket::build().mount("/base", vec![route]);
  let routes: Vec<_> = rocket.routes().collect();
  assert_eq!(routes[0].uri, "/base/foo/<bar>");

Fields

base: Origin<'a>

The mount point.

unmounted_origin: Origin<'a>

The URI without the base mount point.

origin: Origin<'a>

The URI with the base mount point. This is the canonical route URI.

Implementations

impl<'a> RouteUri<'a>

pub fn base(&self) -> &str

The path of the base mount point of this route URI as an &str.

Example

use rocket::Route;
use rocket::http::Method;

let index = Route::new(Method::Get, "/foo/bar?a=1", handler);
assert_eq!(index.uri.base(), "/");
let index = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
assert_eq!(index.uri.base(), "/boo");

pub fn path(&self) -> &str

The path part of this route URI as an &str.

Example

use rocket::Route;
use rocket::http::Method;

let index = Route::new(Method::Get, "/foo/bar?a=1", handler);
assert_eq!(index.uri.path(), "/foo/bar");
let index = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
assert_eq!(index.uri.path(), "/boo/foo/bar");

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

The query part of this route URI, if there is one.

Example

use rocket::Route;
use rocket::http::Method;

let index = Route::new(Method::Get, "/foo/bar", handler);
assert!(index.uri.query().is_none());

// Normalization clears the empty '?'.
let index = Route::new(Method::Get, "/foo/bar?", handler);
assert!(index.uri.query().is_none());

let index = Route::new(Method::Get, "/foo/bar?a=1", handler);
assert_eq!(index.uri.query().unwrap(), "a=1");

let index = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
assert_eq!(index.uri.query().unwrap(), "a=1");

pub fn as_str(&self) -> &str

The full URI as an &str.

Example

use rocket::Route;
use rocket::http::Method;

let index = Route::new(Method::Get, "/foo/bar?a=1", handler);
assert_eq!(index.uri.as_str(), "/foo/bar?a=1");
let index = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
assert_eq!(index.uri.as_str(), "/boo/foo/bar?a=1");

Methods from Deref<Target = Origin<'a>>

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

Returns the path part of this URI.

Example

let uri = uri!("/a/b/c");
assert_eq!(uri.path(), "/a/b/c");

let uri = uri!("/a/b/c?name=bob");
assert_eq!(uri.path(), "/a/b/c");

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

Returns the query part of this URI without the question mark, if there is any.

Example

let uri = uri!("/a/b/c?alphabet=true");
assert_eq!(uri.query().unwrap(), "alphabet=true");

let uri = uri!("/a/b/c");
assert!(uri.query().is_none());

pub fn map_path<'s, F, P>(&'s self, f: F) -> Option<Origin<'a>>

where F: FnOnce(&'s RawStr) -> P, P: Into<RawStrBuf> + 's,

Applies the function f to the internal path and returns a new Origin with the new path. If the path returned from f is invalid, returns None. Otherwise, returns Some, even if the new path is abnormal.

Examples

Affix a trailing slash if one isn’t present.

let uri = uri!("/a/b/c");
let expected_uri = uri!("/a/b/c/d");
assert_eq!(uri.map_path(|p| format!("{}/d", p)), Some(expected_uri));

let uri = uri!("/a/b/c");
let abnormal_map = uri.map_path(|p| format!("{}///d", p));
assert_eq!(abnormal_map.unwrap(), "/a/b/c///d");

let uri = uri!("/a/b/c");
let expected = uri!("/b/c");
let mapped = uri.map_path(|p| p.strip_prefix("/a").unwrap_or(p));
assert_eq!(mapped, Some(expected));

let uri = uri!("/a");
assert_eq!(uri.map_path(|p| p.strip_prefix("/a").unwrap_or(p)), None);

let uri = uri!("/a/b/c");
assert_eq!(uri.map_path(|p| format!("hi/{}", p)), None);

pub fn is_normalized(&self) -> bool

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

See Normalization for more information on what it means for an origin URI to be normalized. Note that uri!() always normalizes static input.

Example

use rocket::http::uri::Origin;

assert!(Origin::parse("/").unwrap().is_normalized());
assert!(Origin::parse("/a/b/c").unwrap().is_normalized());
assert!(Origin::parse("/a/b/c?a=b&c").unwrap().is_normalized());

assert!(!Origin::parse("/a/b/c//d").unwrap().is_normalized());
assert!(!Origin::parse("/a?q&&b").unwrap().is_normalized());

assert!(uri!("/a/b/c//d").is_normalized());
assert!(uri!("/a?q&&b").is_normalized());

Trait Implementations

impl<'a> Clone for RouteUri<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RouteUri<'_>

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

Formats the value using the given formatter.

impl<'a> Deref for RouteUri<'a>

type Target = Origin<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for RouteUri<'_>

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

Formats the value using the given formatter.

impl PartialEq<&str> for RouteUri<'_>

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<'a, 'b> PartialEq<Origin<'b>> for RouteUri<'a>

fn eq(&self, other: &Origin<'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 RouteUri<'_>

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.