Struct rocket_http::uri::Absolute
source · pub struct Absolute<'a> { /* private fields */ }
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§
source§impl<'a> Absolute<'a>
impl<'a> Absolute<'a>
sourcepub fn parse(string: &'a str) -> Result<Absolute<'a>, Error<'a>>
pub fn parse(string: &'a str) -> Result<Absolute<'a>, Error<'a>>
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());
sourcepub fn parse_owned(string: String) -> Result<Absolute<'static>, Error<'static>>
pub fn parse_owned(string: String) -> Result<Absolute<'static>, Error<'static>>
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());
sourcepub fn scheme(&self) -> &str
pub fn scheme(&self) -> &str
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);
sourcepub fn path(&self) -> Path<'_>
pub fn path(&self) -> Path<'_>
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());
sourcepub fn query(&self) -> Option<Query<'_>>
pub fn query(&self) -> Option<Query<'_>>
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());
sourcepub fn clear_query(&mut self)
pub fn clear_query(&mut self)
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());
sourcepub fn is_normalized(&self) -> bool
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 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());
sourcepub fn normalize(&mut self)
pub fn normalize(&mut self)
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());
sourcepub fn into_normalized(self) -> Self
pub fn into_normalized(self) -> Self
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§
source§impl PartialEq<&str> for Absolute<'_>
impl PartialEq<&str> for Absolute<'_>
source§impl PartialEq<Absolute<'_>> for str
impl PartialEq<Absolute<'_>> for str
source§impl<'b, 'a> PartialEq<Absolute<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Absolute<'a>> for Uri<'b>
source§impl<'a, 'b> PartialEq<Absolute<'b>> for Absolute<'a>
impl<'a, 'b> PartialEq<Absolute<'b>> for Absolute<'a>
source§impl<'b, 'a> PartialEq<Uri<'b>> for Absolute<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Absolute<'a>
source§impl PartialEq<str> for Absolute<'_>
impl PartialEq<str> for Absolute<'_>
impl Eq for Absolute<'_>
Auto Trait Implementations§
impl<'a> !RefUnwindSafe for Absolute<'a>
impl<'a> Send for Absolute<'a>
impl<'a> Sync for Absolute<'a>
impl<'a> Unpin for Absolute<'a>
impl<'a> UnwindSafe for Absolute<'a>
Blanket Implementations§
source§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.