[−][src]Struct rhymuri::Uri
This type is used to parse and generate URI strings to and from their various components. Components are percent-encoded as necessary during generation, and percent encodings are decoded during parsing.
Since most URI components, once decoded, may include non-UTF8 byte
sequences (which are always percent-encoded), getter methods such as
path
and query
return byte array slice references (&[u8]
)
rather than string or string slice references. Fallible convenience
methods ending in _to_string
, such as path_to_string
and
query_to_string
, are provided to convert these to strings.
The "Authority" part of the Uri is represented by the Authority
type.
Although the Uri
type provides userinfo
, host
, and port
methods for convenience, Uri
holds these components through the
Authority
type, which can be accessed via authority
and
set_authority
. To set or change the userinfo, host, or port of a
Uri
, construct a new Authority
value and set it in the Uri
with
set_authority
.
Examples
Parsing a URI into its components
use rhymuri::Uri; let uri = Uri::parse("http://www.example.com/foo?bar#baz")?; let authority = uri.authority().unwrap(); assert_eq!("www.example.com".as_bytes(), authority.host()); assert_eq!(Some("www.example.com"), uri.host_to_string()?.as_deref()); assert_eq!("/foo", uri.path_to_string()?); assert_eq!(Some("bar"), uri.query_to_string()?.as_deref()); assert_eq!(Some("baz"), uri.fragment_to_string()?.as_deref());
Implementations are provided for the TryFrom
trait, so that
TryFrom::try_from
or TryInto::try_into
may be used as alternatives
to parse
.
Generating a URI from its components
use rhymuri::{ Authority, Uri, }; let mut uri = Uri::default(); assert!(uri.set_scheme(String::from("http")).is_ok()); let mut authority = Authority::default(); authority.set_host("www.example.com"); uri.set_authority(Some(authority)); uri.set_path_from_str("/foo"); uri.set_query(Some("bar".into())); uri.set_fragment(Some("baz".into())); assert_eq!("http://www.example.com/foo?bar#baz", uri.to_string());
Implementations
impl Uri
[src]
#[must_use = "respect mah authoritah"]pub fn authority(&self) -> Option<&Authority>
[src]
Borrow the authority (if any) of the URI.
#[must_use = "please use the return value kthxbye"]pub fn contains_relative_path(&self) -> bool
[src]
Determines if the URI contains a relative path rather than an absolute path.
#[must_use =
"A query and a fragment walked into a bar. Too bad you're ignoring the fragment because it's actually a funny joke."]pub fn fragment(&self) -> Option<&[u8]>
[src]
Borrow the fragment (if any) of the URI.
#[must_use = "use the fragment return value silly programmer"]pub fn fragment_to_string(&self) -> Result<Option<String>, Error>
[src]
Convert the fragment (if any) into a string.
Errors
Since fragments may contain non-UTF8 byte sequences, this function may
return Error::CannotExpressAsUtf8
.
#[must_use = "why u no use host return value?"]pub fn host(&self) -> Option<&[u8]>
[src]
Borrow the host portion of the Authority (if any) of the URI.
#[must_use =
"I made that host field into a string for you; don't you want it?"]pub fn host_to_string(&self) -> Result<Option<String>, Error>
[src]
Convert the host portion of the Authority (if any) into a string.
Errors
Since host names may contain non-UTF8 byte sequences, this function may
return Error::CannotExpressAsUtf8
.
#[must_use =
"why would you call an accessor method and not use the return value, silly human"]pub fn is_relative_reference(&self) -> bool
[src]
Determines if the URI is a relative-ref
(relative reference), as
defined in RFC 3986 section
4.2. A relative
reference has no scheme, but may still have an authority.
pub fn normalize(&mut self)
[src]
Apply the remove_dot_segments
routine talked about
in RFC 3986 section
5.2 to the path
segments of the URI, in order to normalize the path (apply and remove
"." and ".." segments).
Examples
use rhymuri::Uri; let mut uri = Uri::parse("/a/b/c/./../../g")?; uri.normalize(); assert_eq!("/a/g", uri.path_to_string()?);
pub fn parse<T>(uri_string: T) -> Result<Self, Error> where
T: AsRef<str>,
[src]
T: AsRef<str>,
Interpret the given string as a URI, separating its various components,
returning a Uri
value containing them.
Errors
There are many ways to screw up a URI string, and this function will
let you know what's up by returning a variant of the
Error
type.
#[must_use = "you called path() to get the path, so why you no use?"]pub fn path(&self) -> &Vec<Vec<u8>>
[src]
Borrow the path component of the URI.
The path is represented as a two-dimensional vector:
- the "segments" or pieces of the path between the slashes
- the bytes that make up each segment
Byte vectors are used instead of strings because segments may contain non-UTF8 sequences.
Leading and trailing slashes in the path are special cases represented by extra empty segments at the beginning and/or end of the path.
Examples
(Note: the examples below show strings, not byte vectors, simply to be more readable.)
"foo/bar" -> ["foo", "bar"]
"/foo/bar" -> ["", "foo", "bar"]
"foo/bar/" -> ["foo", "bar", ""]
"/foo/bar/" -> ["", "foo", "bar", ""]
"/" -> [""]
"" -> []
#[must_use =
"we went through all that trouble to put the path into a string, and you don't want it?"]pub fn path_to_string(&self) -> Result<String, Error>
[src]
Convert the path portion of the URI into a string.
Errors
Since path segments may contain non-UTF8 byte sequences, this function
may return
Error::CannotExpressAsUtf8
.
#[must_use = "why did you get the port number and then throw it away?"]pub fn port(&self) -> Option<u16>
[src]
Return a copy of the port (if any) contained in the URI.
#[must_use = "don't you want to know what that query was?"]pub fn query(&self) -> Option<&[u8]>
[src]
Borrow the query (if any) of the URI.
#[must_use = "use the query return value silly programmer"]pub fn query_to_string(&self) -> Result<Option<String>, Error>
[src]
Convert the query (if any) into a string.
Errors
Since queries may contain non-UTF8 byte sequences, this function may
return Error::CannotExpressAsUtf8
.
#[must_use =
"why go through all that effort to resolve the URI, when you're not going to use it?!"]pub fn resolve(&self, relative_reference: &Self) -> Self
[src]
Return a new URI which is the result of applying the given relative reference to the URI, following the algorithm from RFC 3986 section 5.2.2.
Examples
use rhymuri::Uri; let base = Uri::parse("http://a/b/c/d;p?q")?; let relative_reference = Uri::parse("g;x?y#s")?; let resolved = base.resolve(&relative_reference); assert_eq!("http://a/b/c/g;x?y#s", resolved.to_string());
#[must_use = "you wanted to use that scheme, right?"]pub fn scheme(&self) -> Option<&str>
[src]
Borrow the scheme (if any) component of the URI.
pub fn set_authority<T>(&mut self, authority: T) where
T: Into<Option<Authority>>,
[src]
T: Into<Option<Authority>>,
Change the authority of the URI.
pub fn set_fragment<T>(&mut self, fragment: T) where
T: Into<Option<Vec<u8>>>,
[src]
T: Into<Option<Vec<u8>>>,
Change the fragment of the URI.
pub fn set_path<T>(&mut self, path: T) where
T: Into<Vec<Vec<u8>>>,
[src]
T: Into<Vec<Vec<u8>>>,
Change the path of the URI.
Note: See path
for special notes about what the
segments of the path mean.
pub fn set_path_from_str<T>(&mut self, path: T) where
T: AsRef<str>,
[src]
T: AsRef<str>,
Change the path of the URI using a string which is split by its slash
(/
) characters to determine the path segments.
Note: See path
for special notes about what the
segments of the path mean.
pub fn set_query<T>(&mut self, query: T) where
T: Into<Option<Vec<u8>>>,
[src]
T: Into<Option<Vec<u8>>>,
Change the query of the URI.
pub fn set_scheme<T>(&mut self, scheme: T) -> Result<(), Error> where
T: Into<Option<String>>,
[src]
T: Into<Option<String>>,
Change the scheme of the URI.
Errors
The set of characters allowed in the scheme of a URI is limited.
Error::IllegalCharacter
is returned if you try to use a character that isn't allowed.
#[must_use]pub fn take_authority(&mut self) -> Option<Authority>
[src]
Remove and return the authority portion (if any) of the URI.
#[must_use]pub fn take_fragment(&mut self) -> Option<Vec<u8>>
[src]
Remove and return the fragment portion (if any) of the URI.
#[must_use]pub fn take_query(&mut self) -> Option<Vec<u8>>
[src]
Remove and return the query portion (if any) of the URI.
#[must_use]pub fn take_scheme(&mut self) -> Option<String>
[src]
Remove and return the scheme portion (if any) of the URI.
#[must_use = "security breach... security breach... userinfo not used"]pub fn userinfo(&self) -> Option<&[u8]>
[src]
Borrow the userinfo portion (if any) of the Authority (if any) of the URI.
Note that you can get None
if there is either no Authority in the URI
or there is an Authority in the URI but it has no userinfo in it.
#[must_use =
"come on, you intended to use that userinfo return value, didn't you?"]pub fn userinfo_to_string(&self) -> Result<Option<String>, Error>
[src]
Convert the fragment (if any) into a string.
Errors
Since fragments may contain non-UTF8 byte sequences, this function may
return Error::CannotExpressAsUtf8
.
Trait Implementations
impl Clone for Uri
[src]
impl Debug for Uri
[src]
impl Default for Uri
[src]
impl Display for Uri
[src]
impl PartialEq<Uri> for Uri
[src]
impl StructuralPartialEq for Uri
[src]
impl TryFrom<&'_ str> for Uri
[src]
type Error = Error
The type returned in the event of a conversion error.
pub fn try_from(uri_string: &str) -> Result<Self, Self::Error>
[src]
impl TryFrom<String> for Uri
[src]
Auto Trait Implementations
impl RefUnwindSafe for Uri
[src]
impl Send for Uri
[src]
impl Sync for Uri
[src]
impl Unpin for Uri
[src]
impl UnwindSafe for Uri
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,