Struct rocket::http::uri::Origin [−][src]
pub struct Origin<'a> { /* fields omitted */ }
Expand description
A URI with an absolute path and optional query: /path?query
.
Origin URIs are the primary type of URI encountered in Rocket applications. They are also the simplest type of URIs, made up of only a path and an optional query.
Structure
The following diagram illustrates the syntactic structure of an origin URI:
/first_segment/second_segment/third?optional=query
|---------------------------------| |------------|
path query
The URI must begin with a /
, can be followed by any number of segments,
and an optional ?
query separator and query string.
Normalization
Rocket prefers, and will sometimes require, origin URIs to be normalized. A normalized origin URI is a valid origin URI that contains zero empty segments except when there are no segments.
As an example, the following URIs are all valid, normalized URIs:
"/", "/a/b/c", "/a/b/c?q", "/hello?lang=en", "/some%20thing?q=foo&lang=fr",
By contrast, the following are valid but non-normal URIs:
"//", // one empty segment "/a/b/", // trailing empty segment "/a/ab//c//d", // two empty segments "/?a&&b", // empty query segment "/?foo&", // trailing empty query segment
The Origin::into_normalized()
method can be used to normalize any Origin
:
// non-normal versions "//", "/a/b/", "/a/ab//c//d", "/a?a&&b&", // normalized versions "/", "/a/b", "/a/ab/c/d", "/a?a&b",
(De)serialization
Origin
is both Serialize
and Deserialize
:
use serde::{Serialize, Deserialize}; use rocket::http::uri::Origin; #[derive(Deserialize, Serialize)] struct UriOwned { uri: Origin<'static>, } #[derive(Deserialize, Serialize)] struct UriBorrowed<'a> { uri: Origin<'a>, }
Implementations
Parses the string string
into an Origin
. Parsing will never
allocate. Returns an Error
if string
is not a valid origin URI.
Example
use rocket::http::uri::Origin; // Parse a valid origin URI. let uri = Origin::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. Origin::parse("foo bar").expect_err("invalid URI"); // Prefer to use `uri!()` when the input is statically known: let uri = uri!("/a/b/c?query"); assert_eq!(uri.path(), "/a/b/c"); assert_eq!(uri.query().unwrap(), "query");
Parses the string string
into an Origin
. Never allocates on success.
May allocate on error.
This method should be used instead of Origin::parse()
when
the source URI is already a String
. Returns an Error
if string
is
not a valid origin URI.
Example
use rocket::http::uri::Origin; let source = format!("/foo/{}/three", 2); let uri = Origin::parse_owned(source).expect("valid URI"); assert_eq!(uri.path(), "/foo/2/three"); assert!(uri.query().is_none());
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");
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());
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);
Removes the query part of this URI, if there is any.
Example
let mut uri = uri!("/a/b/c?query=some"); assert_eq!(uri.query().unwrap(), "query=some"); uri.clear_query(); assert!(uri.query().is_none());
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());
Normalizes self
. This is a no-op if self
is already normalized.
See Normalization for more information on what it means for an origin URI to be normalized.
Example
use rocket::http::uri::Origin; let mut abnormal = Origin::parse("/a/b/c//d").unwrap(); assert!(!abnormal.is_normalized()); abnormal.normalize(); assert!(abnormal.is_normalized());
Consumes self
and returns a normalized version.
This is a no-op if self
is already normalized. See
Normalization for more information on what it means
for an origin URI to be normalized.
Example
use rocket::http::uri::Origin; let abnormal = Origin::parse("/a/b/c//d").unwrap(); assert!(!abnormal.is_normalized()); assert!(abnormal.into_normalized().is_normalized());
Trait Implementations
pub fn deserialize<D>(
deserializer: D
) -> Result<Origin<'a>, <D as Deserializer<'de>>::Error> where
D: Deserializer<'de>,
[src]
pub fn deserialize<D>(
deserializer: D
) -> Result<Origin<'a>, <D as Deserializer<'de>>::Error> where
D: Deserializer<'de>,
[src]Deserialize this value from the given Serde deserializer. Read more
type Error = Infallible
type Error = Infallible
The associated error to be returned if derivation fails.
Converts self
into an owned version of itself.
pub fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
S: Serializer,
[src]
pub fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
S: Serializer,
[src]Serialize this value into the given Serde serializer. Read more
Auto Trait Implementations
impl<'a> !RefUnwindSafe for Origin<'a>
impl<'a> UnwindSafe for Origin<'a>
Blanket Implementations
Mutably borrows from an owned value. Read more
Compare self to key
and return true
if they are equal.
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
Converts self
into a collection.
type Output = T
type Output = T
Should always be Self
pub fn vzip(self) -> V