Struct rocket_http::uri::Absolute [−][src]
pub struct Absolute<'a> { /* fields omitted */ }
Expand description
A URI with a scheme, authority, path, and query.
Structure
The following diagram illustrates the syntactic structure of an absolute URI with all optional parts:
http://user:pass@domain.com:4444/foo/bar?some=query
|--| |------------------------||------| |--------|
scheme authority path query
Only the scheme part of the URI is required.
Normalization
Rocket prefers normalized absolute URIs, an absolute URI with the following properties:
- The path and query, if any, are normalized with no empty segments.
- If there is an authority, the path is empty or absolute with more than one character.
The Absolute::is_normalized()
method checks for normalization while
Absolute::into_normalized()
normalizes any absolute URI.
As an example, the following URIs are all valid, normalized URIs:
"http://rocket.rs", "scheme:/foo/bar", "scheme:/foo/bar?abc",
By contrast, the following are valid but non-normal URIs:
"http://rocket.rs/", // trailing '/' "ftp:/a/b/", // trailing empty segment "ftp:/a//c//d", // two empty segments "ftp:/a/b/?", // empty path segment "ftp:/?foo&", // trailing empty query segment
(De)serialization
Absolute
is both Serialize
and Deserialize
:
use serde::{Serialize, Deserialize}; use rocket::http::uri::Absolute; #[derive(Deserialize, Serialize)] struct UriOwned { uri: Absolute<'static>, } #[derive(Deserialize, Serialize)] struct UriBorrowed<'a> { uri: Absolute<'a>, }
Implementations
Parses the string string
into an Absolute
. Parsing will never
allocate. Returns an Error
if string
is not a valid absolute URI.
Example
use rocket::http::uri::Absolute; // Parse a valid authority URI. let uri = Absolute::parse("https://rocket.rs").expect("valid URI"); assert_eq!(uri.scheme(), "https"); assert_eq!(uri.authority().unwrap().host(), "rocket.rs"); assert_eq!(uri.path(), ""); assert!(uri.query().is_none()); // Prefer to use `uri!()` when the input is statically known: let uri = uri!("https://rocket.rs"); assert_eq!(uri.scheme(), "https"); assert_eq!(uri.authority().unwrap().host(), "rocket.rs"); assert_eq!(uri.path(), ""); assert!(uri.query().is_none());
Parses the string string
into an Absolute
. Allocates minimally on
success and error.
This method should be used instead of Absolute::parse()
when the
source URI is already a String
. Returns an Error
if string
is not
a valid absolute URI.
Example
use rocket::http::uri::Absolute; let source = format!("https://rocket.rs/foo/{}/three", 2); let uri = Absolute::parse_owned(source).expect("valid URI"); assert_eq!(uri.authority().unwrap().host(), "rocket.rs"); assert_eq!(uri.path(), "/foo/2/three"); assert!(uri.query().is_none());
Returns the scheme part of the absolute URI.
Example
let uri = uri!("ftp://127.0.0.1"); assert_eq!(uri.scheme(), "ftp");
Returns the authority part of the absolute URI, if there is one.
Example
let uri = uri!("https://rocket.rs:80"); assert_eq!(uri.scheme(), "https"); let authority = uri.authority().unwrap(); assert_eq!(authority.host(), "rocket.rs"); assert_eq!(authority.port(), Some(80)); let uri = uri!("file:/web/home"); assert_eq!(uri.authority(), None);
Returns the path part. May be empty.
Example
let uri = uri!("ftp://rocket.rs/foo/bar"); assert_eq!(uri.path(), "/foo/bar"); let uri = uri!("ftp://rocket.rs"); assert!(uri.path().is_empty());
Returns the query part with the leading ?
. May be empty.
Example
let uri = uri!("ftp://rocket.rs/foo?bar"); assert_eq!(uri.query().unwrap(), "bar"); let uri = uri!("ftp://rocket.rs"); assert!(uri.query().is_none());
Removes the query part of this URI, if there is any.
Example
let mut uri = uri!("ftp://rocket.rs/foo?bar"); assert_eq!(uri.query().unwrap(), "bar"); 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 absolute URI to be normalized. Note that uri!()
always
returns a normalized version of its static input.
Example
use rocket::http::uri::Absolute; assert!(uri!("http://rocket.rs").is_normalized()); assert!(uri!("http://rocket.rs///foo////bar").is_normalized()); assert!(Absolute::parse("http:/").unwrap().is_normalized()); assert!(Absolute::parse("http://").unwrap().is_normalized()); assert!(Absolute::parse("http://foo.rs/foo/bar").unwrap().is_normalized()); assert!(Absolute::parse("foo:bar").unwrap().is_normalized()); assert!(!Absolute::parse("git://rocket.rs/").unwrap().is_normalized()); assert!(!Absolute::parse("http:/foo//bar").unwrap().is_normalized()); assert!(!Absolute::parse("foo:bar?baz&&bop").unwrap().is_normalized());
Normalizes self
in-place. Does nothing if self
is already
normalized.
Example
use rocket::http::uri::Absolute; let mut uri = Absolute::parse("git://rocket.rs/").unwrap(); assert!(!uri.is_normalized()); uri.normalize(); assert!(uri.is_normalized()); let mut uri = Absolute::parse("http:/foo//bar").unwrap(); assert!(!uri.is_normalized()); uri.normalize(); assert!(uri.is_normalized()); let mut uri = Absolute::parse("foo:bar?baz&&bop").unwrap(); assert!(!uri.is_normalized()); uri.normalize(); assert!(uri.is_normalized());
Normalizes self
. This is a no-op if self
is already normalized.
Example
use rocket::http::uri::Absolute; let mut uri = Absolute::parse("git://rocket.rs/").unwrap(); assert!(!uri.is_normalized()); assert!(uri.into_normalized().is_normalized()); let mut uri = Absolute::parse("http:/foo//bar").unwrap(); assert!(!uri.is_normalized()); assert!(uri.into_normalized().is_normalized()); let mut uri = Absolute::parse("foo:bar?baz&&bop").unwrap(); assert!(!uri.is_normalized()); assert!(uri.into_normalized().is_normalized());
Sets the authority in self
to authority
.
Example
let mut uri = uri!("https://rocket.rs:80"); let authority = uri.authority().unwrap(); assert_eq!(authority.host(), "rocket.rs"); assert_eq!(authority.port(), Some(80)); let new_authority = uri!("rocket.rs:443"); uri.set_authority(new_authority); let authority = uri.authority().unwrap(); assert_eq!(authority.host(), "rocket.rs"); assert_eq!(authority.port(), Some(443));
Sets the authority in self
to authority
and returns self
.
Example
let uri = uri!("https://rocket.rs:80"); let authority = uri.authority().unwrap(); assert_eq!(authority.host(), "rocket.rs"); assert_eq!(authority.port(), Some(80)); let new_authority = uri!("rocket.rs"); let uri = uri.with_authority(new_authority); let authority = uri.authority().unwrap(); assert_eq!(authority.host(), "rocket.rs"); assert_eq!(authority.port(), None);
Trait Implementations
Converts self
into an owned version of itself.
Auto Trait Implementations
impl<'a> !RefUnwindSafe for Absolute<'a>
impl<'a> UnwindSafe for Absolute<'a>
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more