pub enum Uri<'a> {
Asterisk(Asterisk),
Origin(Origin<'a>),
Authority(Authority<'a>),
Absolute(Absolute<'a>),
Reference(Reference<'a>),
}
Expand description
An enum
encapsulating any of the possible URI variants.
Usage
In Rocket, this type will rarely be used directly. Instead, you will
typically encounter URIs via the Origin
type. This is because all
incoming requests accepted by Rocket contain URIs in origin-form.
Parsing
The Uri
type implements a full, zero-allocation, zero-copy RFC 7230
compliant “request target” parser with limited liberties for real-world
deviations. In particular, the parser deviates as follows:
-
It accepts
%
characters without two trailing hex-digits. -
It accepts the following additional unencoded characters in query parts, to match real-world browser behavior:
{
,}
,[
,]
,\
,^
,`
,|
To parse an &str
into a Uri
, use Uri::parse()
. Alternatively, you
may also use the TryFrom<&str>
and TryFrom<String>
trait implementation.
To inspect the parsed type, match on the resulting enum
and use the
methods of the internal structure.
Variants§
Asterisk(Asterisk)
An asterisk: exactly *
.
Origin(Origin<'a>)
An origin URI.
Authority(Authority<'a>)
An authority URI.
Absolute(Absolute<'a>)
An absolute URI.
Reference(Reference<'a>)
A URI reference.
Implementations§
source§impl<'a> Uri<'a>
impl<'a> Uri<'a>
sourcepub fn parse<T>(string: &'a str) -> Result<Uri<'a>, Error<'a>>where
T: Into<Uri<'a>> + TryFrom<&'a str, Error = Error<'a>>,
pub fn parse<T>(string: &'a str) -> Result<Uri<'a>, Error<'a>>where T: Into<Uri<'a>> + TryFrom<&'a str, Error = Error<'a>>,
Parses the string string
into a Uri
of kind T
.
This is identical to T::parse(string).map(Uri::from)
.
T
is typically one of Asterisk
, Origin
, Authority
,
Absolute
, or Reference
. Parsing never allocates. Returns an
Error
if string
is not a valid URI of kind T
.
To perform an ambiguous parse into any valid URI type, use
Uri::parse_any()
.
Example
use rocket::http::uri::{Uri, Origin};
// Parse a valid origin URI (note: in practice, use `Origin::parse()`).
let uri = Uri::parse::<Origin>("/a/b/c?query").expect("valid URI");
let origin = uri.origin().expect("origin URI");
assert_eq!(origin.path(), "/a/b/c");
assert_eq!(origin.query().unwrap(), "query");
// Prefer to use the `uri!()` macro for static inputs. The return value
// is of the specific type, not `Uri`.
let origin = uri!("/a/b/c?query");
assert_eq!(origin.path(), "/a/b/c");
assert_eq!(origin.query().unwrap(), "query");
// Invalid URIs fail to parse.
Uri::parse::<Origin>("foo bar").expect_err("invalid URI");
sourcepub fn parse_any(string: &'a str) -> Result<Uri<'a>, Error<'a>>
pub fn parse_any(string: &'a str) -> Result<Uri<'a>, Error<'a>>
Parse string
into a the “best fit” URI type.
Always prefer to use uri!()
for statically known inputs.
Because URI parsing is ambiguous (that is, there isn’t a one-to-one mapping between strings and a URI type), the internal type returned by this method may not be the desired type. This method chooses the “best fit” type for a given string by preferring to parse in the following order:
Asterisk
Origin
Authority
Absolute
Reference
Thus, even though *
is a valid Asterisk
and Reference
URI, it
will parse as an Asterisk
.
Example
use rocket::http::uri::{Uri, Origin, Reference};
// An absolute path is an origin _unless_ it contains a fragment.
let uri = Uri::parse_any("/a/b/c?query").expect("valid URI");
let origin = uri.origin().expect("origin URI");
assert_eq!(origin.path(), "/a/b/c");
assert_eq!(origin.query().unwrap(), "query");
let uri = Uri::parse_any("/a/b/c?query#fragment").expect("valid URI");
let reference = uri.reference().expect("reference URI");
assert_eq!(reference.path(), "/a/b/c");
assert_eq!(reference.query().unwrap(), "query");
assert_eq!(reference.fragment().unwrap(), "fragment");
// Prefer to use the `uri!()` macro for static inputs. The return type
// is the internal type, not `Uri`. The explicit type is not required.
let uri: Origin = uri!("/a/b/c?query");
let uri: Reference = uri!("/a/b/c?query#fragment");
sourcepub fn origin(&self) -> Option<&Origin<'a>>
pub fn origin(&self) -> Option<&Origin<'a>>
Returns the internal instance of Origin
if self
is a Uri::Origin
.
Otherwise, returns None
.
Example
use rocket::http::uri::{Uri, Absolute, Origin};
let uri = Uri::parse::<Origin>("/a/b/c?query").expect("valid URI");
assert!(uri.origin().is_some());
let uri = Uri::from(uri!("/a/b/c?query"));
assert!(uri.origin().is_some());
let uri = Uri::parse::<Absolute>("https://rocket.rs").expect("valid URI");
assert!(uri.origin().is_none());
let uri = Uri::from(uri!("https://rocket.rs"));
assert!(uri.origin().is_none());
Returns the internal instance of Authority
if self
is a
Uri::Authority
. Otherwise, returns None
.
Example
use rocket::http::uri::{Uri, Absolute, Authority};
let uri = Uri::parse::<Authority>("user:pass@domain.com").expect("valid URI");
assert!(uri.authority().is_some());
let uri = Uri::from(uri!("user:pass@domain.com"));
assert!(uri.authority().is_some());
let uri = Uri::parse::<Absolute>("https://rocket.rs").expect("valid URI");
assert!(uri.authority().is_none());
let uri = Uri::from(uri!("https://rocket.rs"));
assert!(uri.authority().is_none());
sourcepub fn absolute(&self) -> Option<&Absolute<'a>>
pub fn absolute(&self) -> Option<&Absolute<'a>>
Returns the internal instance of Absolute
if self
is a
Uri::Absolute
. Otherwise, returns None
.
Example
use rocket::http::uri::{Uri, Absolute, Origin};
let uri = Uri::parse::<Absolute>("http://rocket.rs").expect("valid URI");
assert!(uri.absolute().is_some());
let uri = Uri::from(uri!("http://rocket.rs"));
assert!(uri.absolute().is_some());
let uri = Uri::parse::<Origin>("/path").expect("valid URI");
assert!(uri.absolute().is_none());
let uri = Uri::from(uri!("/path"));
assert!(uri.absolute().is_none());
sourcepub fn reference(&self) -> Option<&Reference<'a>>
pub fn reference(&self) -> Option<&Reference<'a>>
Returns the internal instance of Reference
if self
is a
Uri::Reference
. Otherwise, returns None
.
Example
use rocket::http::uri::{Uri, Absolute, Reference};
let uri = Uri::parse::<Reference>("foo/bar").expect("valid URI");
assert!(uri.reference().is_some());
let uri = Uri::from(uri!("foo/bar"));
assert!(uri.reference().is_some());
let uri = Uri::parse::<Absolute>("https://rocket.rs").expect("valid URI");
assert!(uri.reference().is_none());
let uri = Uri::from(uri!("https://rocket.rs"));
assert!(uri.reference().is_none());
Trait Implementations§
source§impl<'b, 'a> PartialEq<Absolute<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Absolute<'a>> for Uri<'b>
source§impl<'b> PartialEq<Asterisk> for Uri<'b>
impl<'b> PartialEq<Asterisk> for Uri<'b>
source§impl<'b, 'a> PartialEq<Authority<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Authority<'a>> for Uri<'b>
source§impl<'b, 'a> PartialEq<Origin<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Origin<'a>> for Uri<'b>
source§impl<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>
source§impl<'a> PartialEq<Uri<'a>> for Uri<'a>
impl<'a> PartialEq<Uri<'a>> for Uri<'a>
source§impl<'b, 'a> PartialEq<Uri<'b>> for Absolute<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Absolute<'a>
source§impl<'b> PartialEq<Uri<'b>> for Asterisk
impl<'b> PartialEq<Uri<'b>> for Asterisk
source§impl<'b, 'a> PartialEq<Uri<'b>> for Authority<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Authority<'a>
source§impl<'b, 'a> PartialEq<Uri<'b>> for Origin<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Origin<'a>
source§impl<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>
impl<'a> StructuralPartialEq for Uri<'a>
Auto Trait Implementations§
impl<'a> !RefUnwindSafe for Uri<'a>
impl<'a> Send for Uri<'a>
impl<'a> Sync for Uri<'a>
impl<'a> Unpin for Uri<'a>
impl<'a> UnwindSafe for Uri<'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<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);