Struct rocket_http::uri::Reference
source · pub struct Reference<'a> { /* private fields */ }
Expand description
A URI-reference with optional scheme, authority, relative path, query, and fragment parts.
Structure
The following diagram illustrates the syntactic structure of a URI reference with all optional parts:
http://user:pass@domain.com:4444/foo/bar?some=query#and-fragment
|--| |------------------------||------| |--------| |----------|
scheme authority path query fragment
All parts are optional. When a scheme and authority are not present, the
path may be relative: foo/bar?baz#cat
.
Conversion
All other URI types (Origin
, Absolute
, and so on) are valid URI
references. As such, conversion between the types is lossless:
use rocket::http::uri::Reference;
let absolute = uri!("http://rocket.rs");
let reference: Reference = absolute.into();
assert_eq!(reference.scheme(), Some("http"));
assert_eq!(reference.authority().unwrap().host(), "rocket.rs");
let origin = uri!("/foo/bar");
let reference: Reference = origin.into();
assert_eq!(reference.path(), "/foo/bar");
Note that uri!()
macro always prefers the more specific URI variant to
Reference
when possible, as is demonstrated above for absolute
and
origin
.
(De)serialization
Reference
is both Serialize
and Deserialize
:
use serde::{Serialize, Deserialize};
use rocket::http::uri::Reference;
#[derive(Deserialize, Serialize)]
struct UriOwned {
uri: Reference<'static>,
}
#[derive(Deserialize, Serialize)]
struct UriBorrowed<'a> {
uri: Reference<'a>,
}
Implementations§
source§impl<'a> Reference<'a>
impl<'a> Reference<'a>
sourcepub fn parse(string: &'a str) -> Result<Reference<'a>, Error<'a>>
pub fn parse(string: &'a str) -> Result<Reference<'a>, Error<'a>>
Parses the string string
into an Reference
. Parsing will never
allocate. Returns an Error
if string
is not a valid origin URI.
Example
use rocket::http::uri::Reference;
// Parse a valid URI reference.
let uri = Reference::parse("/a/b/c?query").expect("valid URI");
assert_eq!(uri.path(), "/a/b/c");
assert_eq!(uri.query().unwrap(), "query");
// Invalid URIs fail to parse.
Reference::parse("foo bar").expect_err("invalid URI");
// Prefer to use `uri!()` when the input is statically known:
let uri = uri!("/a/b/c?query#fragment");
assert_eq!(uri.path(), "/a/b/c");
assert_eq!(uri.query().unwrap(), "query");
assert_eq!(uri.fragment().unwrap(), "fragment");
sourcepub fn parse_owned(string: String) -> Result<Reference<'static>, Error<'static>>
pub fn parse_owned(string: String) -> Result<Reference<'static>, Error<'static>>
Parses the string string
into a Reference
. Allocates minimally on
success and error.
This method should be used instead of Reference::parse()
when the
source URI is already a String
. Returns an Error
if string
is not
a valid URI reference.
Example
use rocket::http::uri::Reference;
let source = format!("/foo?{}#3", 2);
let uri = Reference::parse_owned(source).unwrap();
assert_eq!(uri.path(), "/foo");
assert_eq!(uri.query().unwrap(), "2");
assert_eq!(uri.fragment().unwrap(), "3");
sourcepub fn scheme(&self) -> Option<&str>
pub fn scheme(&self) -> Option<&str>
Returns the scheme. If Some
, is non-empty.
Example
let uri = uri!("http://rocket.rs?foo#bar");
assert_eq!(uri.scheme(), Some("http"));
let uri = uri!("ftp:/?foo#bar");
assert_eq!(uri.scheme(), Some("ftp"));
let uri = uri!("?foo#bar");
assert_eq!(uri.scheme(), None);
Returns the authority part.
Example
let uri = uri!("http://rocket.rs:4444?foo#bar");
let auth = uri!("rocket.rs:4444");
assert_eq!(uri.authority().unwrap(), &auth);
let uri = uri!("?foo#bar");
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!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.path(), "/guide");
sourcepub fn query(&self) -> Option<Query<'_>>
pub fn query(&self) -> Option<Query<'_>>
Returns the query part. May be empty.
Example
let uri = uri!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.query().unwrap(), "foo");
let uri = uri!("http://rocket.rs/guide?q=bar");
assert_eq!(uri.query().unwrap(), "q=bar");
// Empty query parts are normalized away by `uri!()`.
let uri = uri!("http://rocket.rs/guide?#bar");
assert!(uri.query().is_none());
sourcepub fn fragment(&self) -> Option<&RawStr>
pub fn fragment(&self) -> Option<&RawStr>
Returns the fragment part, if any.
Example
let uri = uri!("http://rocket.rs/guide?foo#bar");
assert_eq!(uri.fragment().unwrap(), "bar");
// Fragment parts aren't normalized away, unlike query parts.
let uri = uri!("http://rocket.rs/guide?foo#");
assert_eq!(uri.fragment().unwrap(), "");
sourcepub fn is_normalized(&self) -> bool
pub fn is_normalized(&self) -> bool
Returns true
if self
is normalized. Otherwise, returns false
.
Normalization for a URI reference is equivalent to normalization for an
absolute URI. See Absolute
for more information on
what it means for an absolute URI to be normalized.
Example
use rocket::http::uri::Reference;
assert!(Reference::parse("foo/bar").unwrap().is_normalized());
assert!(Reference::parse("foo/bar#").unwrap().is_normalized());
assert!(Reference::parse("http://").unwrap().is_normalized());
assert!(Reference::parse("http://foo.rs/foo/bar").unwrap().is_normalized());
assert!(Reference::parse("foo:bar#baz").unwrap().is_normalized());
assert!(Reference::parse("http://rocket.rs#foo").unwrap().is_normalized());
assert!(!Reference::parse("http://?").unwrap().is_normalized());
assert!(!Reference::parse("git://rocket.rs/").unwrap().is_normalized());
assert!(!Reference::parse("http:/foo//bar").unwrap().is_normalized());
assert!(!Reference::parse("foo:bar?baz&&bop#c").unwrap().is_normalized());
assert!(!Reference::parse("http://rocket.rs?#foo").unwrap().is_normalized());
// Recall that `uri!()` normalizes static input.
assert!(uri!("http://rocket.rs#foo").is_normalized());
assert!(uri!("http://rocket.rs///foo////bar#cat").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::Reference;
let mut uri = Reference::parse("git://rocket.rs/").unwrap();
assert!(!uri.is_normalized());
uri.normalize();
assert!(uri.is_normalized());
let mut uri = Reference::parse("http:/foo//bar?baz&&#cat").unwrap();
assert!(!uri.is_normalized());
uri.normalize();
assert!(uri.is_normalized());
let mut uri = Reference::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::Reference;
let mut uri = Reference::parse("git://rocket.rs/").unwrap();
assert!(!uri.is_normalized());
assert!(uri.into_normalized().is_normalized());
let mut uri = Reference::parse("http:/foo//bar?baz&&#cat").unwrap();
assert!(!uri.is_normalized());
assert!(uri.into_normalized().is_normalized());
let mut uri = Reference::parse("foo:bar?baz&&bop").unwrap();
assert!(!uri.is_normalized());
assert!(uri.into_normalized().is_normalized());
Trait Implementations§
source§impl PartialEq<&str> for Reference<'_>
impl PartialEq<&str> for Reference<'_>
source§impl PartialEq<Reference<'_>> for str
impl PartialEq<Reference<'_>> for str
source§impl<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>
impl<'b, 'a> PartialEq<Reference<'a>> for Uri<'b>
source§impl<'a, 'b> PartialEq<Reference<'b>> for Reference<'a>
impl<'a, 'b> PartialEq<Reference<'b>> for Reference<'a>
source§impl<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>
impl<'b, 'a> PartialEq<Uri<'b>> for Reference<'a>
source§impl PartialEq<str> for Reference<'_>
impl PartialEq<str> for Reference<'_>
impl Eq for Reference<'_>
Auto Trait Implementations§
impl<'a> !RefUnwindSafe for Reference<'a>
impl<'a> Send for Reference<'a>
impl<'a> Sync for Reference<'a>
impl<'a> Unpin for Reference<'a>
impl<'a> UnwindSafe for Reference<'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);