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:
- If there is an authority, the path is empty or absolute.
- The path and query, if any, are normalized with no empty segments except optionally for one trailing slash.
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",
"http://rocket.rs/",
"ftp:/a/b/",
"ftp:/a/b/?",
"scheme:/foo/bar",
"scheme:/foo/bar/",
"scheme:/foo/bar/?",
"scheme:/foo/bar/?abc",
By contrast, the following are valid but non-normal URIs:
"ftp:/a//c//d", // two empty segments
"ftp:/?foo&", // trailing empty query segment
"ftp:/?fooa&&b", // 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());
let mut uri = Absolute::parse("git://rocket.rs/").unwrap();
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) -> Absolute<'a>
pub fn into_normalized(self) -> Absolute<'a>
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());
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<'a, 'de> Deserialize<'de> for Absolute<'a>
impl<'a, 'de> Deserialize<'de> for Absolute<'a>
source§fn deserialize<D>(
deserializer: D
) -> Result<Absolute<'a>, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
fn deserialize<D>( deserializer: D ) -> Result<Absolute<'a>, <D as Deserializer<'de>>::Error>where D: Deserializer<'de>,
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<'_>
source§impl<'a> Serialize for Absolute<'a>
impl<'a> Serialize for Absolute<'a>
source§fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where S: Serializer,
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
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.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.source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§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
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§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();
source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightYellow
.
Example
println!("{}", value.bright_yellow());
source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.bright_magenta());
source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§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();
source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlack
.
Example
println!("{}", value.on_bright_black());
source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightGreen
.
Example
println!("{}", value.on_bright_green());
source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightYellow
.
Example
println!("{}", value.on_bright_yellow());
source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlue
.
Example
println!("{}", value.on_bright_blue());
source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.on_bright_magenta());
source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightCyan
.
Example
println!("{}", value.on_bright_cyan());
source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightWhite
.
Example
println!("{}", value.on_bright_white());
source§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();
source§fn underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§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();
source§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);