Struct http::uri::Uri

pub struct Uri { /* fields omitted */ }

The URI component of a request.

For HTTP 1, this is included as part of the request line. From Section 5.3, Request Target:

Once an inbound connection is obtained, the client sends an HTTP request message (Section 3) with a request-target derived from the target URI. There are four distinct formats for the request-target, depending on both the method being requested and whether the request is to a proxy.

request-target = origin-form
               / absolute-form
               / authority-form
               / asterisk-form

The URI is structured as follows:

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
|-|   |-------------------------------||--------| |-------------------| |-----|
 |                  |                       |               |              |
scheme          authority                 path            query         fragment

For HTTP 2.0, the URI is encoded using pseudoheaders.

Examples

use http::Uri;

let uri = "/foo/bar?baz".parse::<Uri>().unwrap();
assert_eq!(uri.path(), "/foo/bar");
assert_eq!(uri.query(), Some("baz"));
assert_eq!(uri.host(), None);

let uri = "https://www.rust-lang.org/install.html".parse::<Uri>().unwrap();
assert_eq!(uri.scheme_part().map(|s| s.as_str()), Some("https"));
assert_eq!(uri.host(), Some("www.rust-lang.org"));
assert_eq!(uri.path(), "/install.html");

Methods

impl Uri

pub fn from_parts(src: Parts) -> Result<Uri, InvalidUriParts>

Attempt to convert a Uri from Parts

pub fn from_shared(s: Bytes) -> Result<Uri, InvalidUriBytes>

Attempt to convert a Uri from Bytes

This function will be replaced by a TryFrom implementation once the trait lands in stable.

Examples

extern crate bytes;

use bytes::Bytes;

let bytes = Bytes::from("http://example.com/foo");
let uri = Uri::from_shared(bytes).unwrap();

assert_eq!(uri.host().unwrap(), "example.com");
assert_eq!(uri.path(), "/foo");

pub fn into_parts(self) -> Parts

Convert a Uri into Parts.

Note

This is just an inherent method providing the same functionality as let parts: Parts = uri.into()

Examples

let uri: Uri = "/foo".parse().unwrap();

let parts = uri.into_parts();

assert_eq!(parts.path_and_query.unwrap(), "/foo");

assert!(parts.scheme.is_none());
assert!(parts.authority.is_none());

pub fn path_and_query(&self) -> Option<&PathAndQuery>

Returns the path & query components of the Uri

pub fn path(&self) -> &str

Get the path of this Uri.

Both relative and absolute URIs contain a path component, though it might be the empty string. The path component is case sensitive.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
                                       |--------|
                                            |
                                          path

If the URI is * then the path component is equal to *.

Examples

A relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert_eq!(uri.path(), "/hello/world");

An absolute URI

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.path(), "/hello/world");

pub fn scheme_part(&self) -> Option<&Scheme>

Get the scheme of this Uri.

The URI scheme refers to a specification for assigning identifiers within that scheme. Only absolute URIs contain a scheme component, but not all absolute URIs will contain a scheme component. Although scheme names are case-insensitive, the canonical form is lowercase.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
|-|
 |
scheme

Examples

Absolute URI

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.scheme_part().map(|s| s.as_str()), Some("http"));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.scheme_part().is_none());

pub fn authority_part(&self) -> Option<&Authority>

Get the authority of this Uri.

The authority is a hierarchical element for naming authority such that the remainder of the URI is delegated to that authority. For HTTP, the authority consists of the host and port. The host portion of the authority is case-insensitive.

The authority also includes a username:password component, however the use of this is deprecated and should be avoided.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
      |-------------------------------|
                    |
                authority

This function will be renamed to authority in the next semver release.

Examples

Absolute URI

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.authority_part().map(|a| a.as_str()), Some("example.org:80"));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.authority_part().is_none());

pub fn host(&self) -> Option<&str>

Get the host of this Uri.

The host subcomponent of authority is identified by an IP literal encapsulated within square brackets, an IPv4 address in dotted- decimal form, or a registered name. The host subcomponent is case-insensitive.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
                        |---------|
                             |
                            host

Examples

Absolute URI

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.host(), Some("example.org"));

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.host().is_none());

pub fn port(&self) -> Option<u16>

Get the port of this Uri.

The port subcomponent of authority is designated by an optional port number in decimal following the host and delimited from it by a single colon (":") character. A value is only returned if one is specified in the URI string, i.e., default port values are not returned.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
                                    |-|
                                     |
                                    port

Examples

Absolute URI with port

let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

assert_eq!(uri.port(), Some(80));

Absolute URI without port

let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert!(uri.port().is_none());

Relative URI

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.port().is_none());

pub fn query(&self) -> Option<&str>

Get the query string of this Uri, starting after the ?.

The query component contains non-hierarchical data that, along with data in the path component, serves to identify a resource within the scope of the URI's scheme and naming authority (if any). The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI.

abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
                                                  |-------------------|
                                                            |
                                                          query

Examples

Absolute URI

let uri: Uri = "http://example.org/hello/world?key=value".parse().unwrap();

assert_eq!(uri.query(), Some("key=value"));

Relative URI with a query string component

let uri: Uri = "/hello/world?key=value&foo=bar".parse().unwrap();

assert_eq!(uri.query(), Some("key=value&foo=bar"));

Relative URI without a query string component

let uri: Uri = "/hello/world".parse().unwrap();

assert!(uri.query().is_none());

Trait Implementations

impl Clone for Uri

fn clone(&self) -> Uri

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> HttpTryFrom<&'a str> for Uri

type Error = InvalidUri

Associated error with the conversion this implementation represents.

fn try_from(t: &'a str) -> Result<Self, Self::Error>

impl<'a> HttpTryFrom<&'a String> for Uri

type Error = InvalidUri

Associated error with the conversion this implementation represents.

fn try_from(t: &'a String) -> Result<Self, Self::Error>

impl HttpTryFrom<String> for Uri

type Error = InvalidUriBytes

Associated error with the conversion this implementation represents.

fn try_from(t: String) -> Result<Self, Self::Error>

impl HttpTryFrom<Bytes> for Uri

type Error = InvalidUriBytes

Associated error with the conversion this implementation represents.

fn try_from(t: Bytes) -> Result<Self, Self::Error>

impl HttpTryFrom<Parts> for Uri

type Error = InvalidUriParts

Associated error with the conversion this implementation represents.

fn try_from(src: Parts) -> Result<Self, Self::Error>

impl<'a> HttpTryFrom<&'a Uri> for Uri

type Error = Error

Associated error with the conversion this implementation represents.

fn try_from(src: &'a Uri) -> Result<Self, Self::Error>

impl From<Uri> for Parts

Convert a Uri from parts

Examples

Relative URI

let mut parts = Parts::default();
parts.path_and_query = Some("/foo".parse().unwrap());

let uri = Uri::from_parts(parts).unwrap();

assert_eq!(uri.path(), "/foo");

assert!(uri.scheme_part().is_none());
assert!(uri.authority().is_none());

Absolute URI

let mut parts = Parts::default();
parts.scheme = Some("http".parse().unwrap());
parts.authority = Some("foo.com".parse().unwrap());
parts.path_and_query = Some("/foo".parse().unwrap());

let uri = Uri::from_parts(parts).unwrap();

assert_eq!(uri.scheme_part().unwrap().as_str(), "http");
assert_eq!(uri.authority().unwrap(), "foo.com");
assert_eq!(uri.path(), "/foo");

fn from(src: Uri) -> Self

Performs the conversion.

impl FromStr for Uri

type Err = InvalidUri

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Uri, InvalidUri>

Parses a string s to return a value of this type.

impl PartialEq for Uri

fn eq(&self, other: &Uri) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<str> for Uri

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Uri> for str

fn eq(&self, uri: &Uri) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<&'a str> for Uri

fn eq(&self, other: &&'a str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Uri> for &'a str

fn eq(&self, uri: &Uri) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for Uri

impl Default for Uri

Returns a Uri representing /

fn default() -> Uri

Returns the "default value" for a type.

impl Display for Uri

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Uri

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for Uri

fn hash<H>(&self, state: &mut H) where     H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl HttpTryFrom<Uri> for Uri

type Error = Error

Associated error with the conversion this implementation represents.

fn try_from(t: Self) -> Result<Self, Self::Error>