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", "/some%20thing"
By contrast, the following are valid but abnormal URIs:
"//", // one empty segment "/a/b/", // trailing empty segment "/a/ab//c//d" // two empty segments
The Origin::to_normalized()
method can be
used to normalize any Origin
:
// abnormal versions "//", "/a/b/", "/a/ab//c//d" // normalized versions "/", "/a/b", "/a/ab/c/d"
Implementations
impl<'a> Origin<'a>
[src]
impl<'a> Origin<'a>
[src]pub fn parse(string: &'a str) -> Result<Origin<'a>, Error<'a>>
[src]
pub fn parse(string: &'a str) -> Result<Origin<'a>, Error<'a>>
[src]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(), Some("query")); // Invalid URIs fail to parse. Origin::parse("foo bar").expect_err("invalid URI");
pub fn parse_owned(string: String) -> Result<Origin<'static>, Error<'static>>
[src]
pub fn parse_owned(string: String) -> Result<Origin<'static>, Error<'static>>
[src]Parses the string string
into an Origin
. Parsing will never allocate
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_eq!(uri.query(), None);
pub fn is_normalized(&self) -> bool
[src]
pub fn is_normalized(&self) -> bool
[src]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.
Example
use rocket::http::uri::Origin; let normal = Origin::parse("/").unwrap(); assert!(normal.is_normalized()); let normal = Origin::parse("/a/b/c").unwrap(); assert!(normal.is_normalized()); let abnormal = Origin::parse("/a/b/c//d").unwrap(); assert!(!abnormal.is_normalized());
pub fn to_normalized(&self) -> Origin<'_>
[src]
pub fn to_normalized(&self) -> Origin<'_>
[src]Normalizes self
.
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()); let normalized = abnormal.to_normalized(); assert!(normalized.is_normalized()); assert_eq!(normalized, Origin::parse("/a/b/c/d").unwrap());
pub fn path(&self) -> &str
[src]
pub fn path(&self) -> &str
[src]Returns the path part of this URI.
Examples
A URI with only a path:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c").unwrap(); assert_eq!(uri.path(), "/a/b/c");
A URI with a query:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c?name=bob").unwrap(); assert_eq!(uri.path(), "/a/b/c");
pub fn map_path<F: FnOnce(&str) -> String>(&self, f: F) -> Option<Self>
[src]
pub fn map_path<F: FnOnce(&str) -> String>(&self, f: F) -> Option<Self>
[src]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.
use rocket::http::uri::Origin; let old_uri = Origin::parse("/a/b/c").unwrap(); let expected_uri = Origin::parse("/a/b/c/").unwrap(); assert_eq!(old_uri.map_path(|p| p.to_owned() + "/"), Some(expected_uri)); let old_uri = Origin::parse("/a/b/c/").unwrap(); let expected_uri = Origin::parse("/a/b/c//").unwrap(); assert_eq!(old_uri.map_path(|p| p.to_owned() + "/"), Some(expected_uri));
pub fn query(&self) -> Option<&str>
[src]
pub fn query(&self) -> Option<&str>
[src]Returns the query part of this URI without the question mark, if there is any.
Examples
A URI with a query part:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c?alphabet=true").unwrap(); assert_eq!(uri.query(), Some("alphabet=true"));
A URI without the query part:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c").unwrap(); assert_eq!(uri.query(), None);
pub fn clear_query(&mut self)
[src]
pub fn clear_query(&mut self)
[src]Removes the query part of this URI, if there is any.
Example
use rocket::http::uri::Origin; let mut uri = Origin::parse("/a/b/c?query=some").unwrap(); assert_eq!(uri.query(), Some("query=some")); uri.clear_query(); assert_eq!(uri.query(), None);
pub fn segments(&self) -> Segments<'_>ⓘ
[src]
pub fn segments(&self) -> Segments<'_>ⓘ
[src]Returns an iterator over the segments of the path in this URI. Skips empty segments.
Examples
A valid URI with only non-empty segments:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c?a=true").unwrap(); for (i, segment) in uri.segments().enumerate() { match i { 0 => assert_eq!(segment, "a"), 1 => assert_eq!(segment, "b"), 2 => assert_eq!(segment, "c"), _ => unreachable!("only three segments") } }
A URI with empty segments:
use rocket::http::uri::Origin; let uri = Origin::parse("///a//b///c////d?query¶m").unwrap(); for (i, segment) in uri.segments().enumerate() { match i { 0 => assert_eq!(segment, "a"), 1 => assert_eq!(segment, "b"), 2 => assert_eq!(segment, "c"), 3 => assert_eq!(segment, "d"), _ => unreachable!("only four segments") } }
pub fn segment_count(&self) -> usize
[src]
pub fn segment_count(&self) -> usize
[src]Returns the number of segments in the URI. Empty segments, which are invalid according to RFC#3986, are not counted.
The segment count is cached after the first invocation. As a result, this function is O(1) after the first invocation, and O(n) before.
Examples
A valid URI with only non-empty segments:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b/c").unwrap(); assert_eq!(uri.segment_count(), 3);
A URI with empty segments:
use rocket::http::uri::Origin; let uri = Origin::parse("/a/b//c/d///e").unwrap(); assert_eq!(uri.segment_count(), 5);
Trait Implementations
Auto Trait Implementations
impl<'a> !RefUnwindSafe for Origin<'a>
impl<'a> Send for Origin<'a>
impl<'a> Sync for Origin<'a>
impl<'a> Unpin for Origin<'a>
impl<'a> UnwindSafe for Origin<'a>
Blanket Implementations
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]pub fn borrow_mut(&mut self) -> &mut T
[src]
pub fn borrow_mut(&mut self) -> &mut T
[src]Mutably borrows from an owned value. Read more
impl<T> IntoCollection<T> for T
[src]
impl<T> IntoCollection<T> for T
[src]impl<T> ToOwned for T where
T: Clone,
[src]
impl<T> ToOwned for T where
T: Clone,
[src]type Owned = T
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
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]
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