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<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§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,
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§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,
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for T
§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling [Attribute
] value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
[Quirk
] value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the [Condition
] value
applies. Replaces any previous condition.
See the crate level docs for more details.
Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);