Struct RouteUri

pub struct RouteUri<'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>");

Implementations

impl<'a> RouteUri<'a>

pub fn inner(&self) -> &Origin<'a>

Returns the complete route URI.

Note: RouteURI derefs to the Origin returned by this method, so this method should rarely be called directly.

Example

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

let route = Route::new(Method::Get, "/foo/bar?a=1", handler);

// Use `inner()` directly:
assert_eq!(route.uri.inner().query().unwrap(), "a=1");

// Use the deref implementation. This is preferred:
assert_eq!(route.uri.query().unwrap(), "a=1");

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

The base mount point of this route URI.

Example

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

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

let route = route.rebase(uri!("/boo"));
assert_eq!(route.uri.base(), "/boo");

let route = route.rebase(uri!("/foo"));
assert_eq!(route.uri.base(), "/foo/boo");

pub fn unmounted(&self) -> &Origin<'a>

The route URI without the base mount point.

Example

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

let route = Route::new(Method::Get, "/foo/bar?a=1", handler);
let route = route.rebase(uri!("/boo"));

assert_eq!(route.uri, "/boo/foo/bar?a=1");
assert_eq!(route.uri.base(), "/boo");
assert_eq!(route.uri.unmounted(), "/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());

pub fn has_trailing_slash(&self) -> bool

Returns true if self has a trailing slash.

This is defined as path.len() > 1 && path.ends_with('/'). This implies that the URI / is not considered to have a trailing slash.

Example

assert!(!uri!("/").has_trailing_slash());
assert!(!uri!("/a").has_trailing_slash());
assert!(!uri!("/foo/bar/baz").has_trailing_slash());

assert!(uri!("/a/").has_trailing_slash());
assert!(uri!("/foo/").has_trailing_slash());
assert!(uri!("/foo/bar/baz/").has_trailing_slash());

pub fn is_normalized_nontrailing(&self) -> bool

Returns true if self is normalized (Origin::is_normalized()) and does not have a trailing slash (Origin::has_trailing_slash()). Otherwise returns false.

Example

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

let origin = Origin::parse("/").unwrap();
assert!(origin.is_normalized_nontrailing());

let origin = Origin::parse("/foo/bar").unwrap();
assert!(origin.is_normalized_nontrailing());

let origin = Origin::parse("//").unwrap();
assert!(!origin.is_normalized_nontrailing());

let origin = Origin::parse("/foo/bar//baz/").unwrap();
assert!(!origin.is_normalized_nontrailing());

let origin = Origin::parse("/foo/bar/").unwrap();
assert!(!origin.is_normalized_nontrailing());

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<'a> Debug for RouteUri<'a>

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.