Struct `Uri`

struct Uri { ... }

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_str(), Some("https"));
assert_eq!(uri.host(), Some("www.rust-lang.org"));
assert_eq!(uri.path(), "/install.html");

Implementations

`impl Uri`

fn builder() -> Builder

Creates a new builder-style object to manufacture a Uri.

This method returns an instance of Builder which can be usd to create a Uri.

Examples

use http::Uri;

let uri = Uri::builder()
    .scheme("https")
    .authority("hyper.rs")
    .path_and_query("/")
    .build()
    .unwrap();

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

Attempt to convert a Parts into a Uri.

Examples

Relative URI

# use http::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().is_none());
assert!(uri.authority().is_none());

Absolute URI

# use http::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().unwrap().as_str(), "http");
assert_eq!(uri.authority().unwrap(), "foo.com");
assert_eq!(uri.path(), "/foo");

fn from_maybe_shared<T>(src: T) -> Result<Self, InvalidUri> where T: AsRef<[u8]> + 'static

Attempt to convert a Bytes buffer to a Uri.

This will try to prevent a copy if the type passed is the type used internally, and will copy the data if it is not.

fn from_static(src: &'static str) -> Self

Convert a Uri from a static string.

This function will not perform any copying, however the string is checked to ensure that it is valid.

Panics

This function panics if the argument is an invalid URI.

Examples

# use http::uri::Uri;
let uri = Uri::from_static("http://example.com/foo");

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

fn into_parts(self: 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

# use http::uri::*;
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());

fn path_and_query(self: &Self) -> Option<&PathAndQuery>

Returns the path & query components of the Uri

fn path(self: &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

# use http::Uri;

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

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

An absolute URI

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

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

fn scheme(self: &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

use http::uri::{Scheme, Uri};

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

assert_eq!(uri.scheme(), Some(&Scheme::HTTP));

Relative URI

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

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

fn scheme_str(self: &Self) -> Option<&str>

Get the scheme of this Uri as a &str.

Example

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

assert_eq!(uri.scheme_str(), Some("http"));

fn authority(self: &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

Examples

Absolute URI

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

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

Relative URI

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

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

fn host(self: &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

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

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

Relative URI

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

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

fn port(self: &Self) -> Option<Port<&str>>

Get the port part of this Uri.

The port subcomponent of authority is designated by an optional port number following the host and delimited from it by a single colon (":") character. It can be turned into a decimal port number with the as_u16 method or as a str with the as_str method.

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

Examples

Absolute URI with port

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

let port = uri.port().unwrap();
assert_eq!(port.as_u16(), 80);

Absolute URI without port

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

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

Relative URI

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

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

fn port_u16(self: &Self) -> Option<u16>

Get the port of this Uri as a u16.

Example

# use http::{Uri, uri::Port};
let uri: Uri = "http://example.org:80/hello/world".parse().unwrap();

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

fn query(self: &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

# use http::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

# use http::Uri;
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

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

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

`impl Clone for Uri`

fn clone(self: &Self) -> Uri

`impl Debug for Uri`

fn fmt(self: &Self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Default for Uri`

fn default() -> Uri

`impl Display for Uri`

fn fmt(self: &Self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Eq for Uri`

`impl Freeze for Uri`

`impl From for Uri`

fn from(path_and_query: PathAndQuery) -> Self

`impl From for Uri`

fn from(authority: Authority) -> Self

`impl FromStr for Uri`

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

`impl Hash for Uri`

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

`impl PartialEq for Uri`

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

`impl PartialEq for Uri`

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

`impl RefUnwindSafe for Uri`

`impl Send for Uri`

`impl Sync for Uri`

`impl TryFrom for Uri`

fn try_from(vec: Vec<u8>) -> Result<Self, <Self as >::Error>

`impl TryFrom for Uri`

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

`impl TryFrom for Uri`

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

`impl Unpin for Uri`

`impl UnwindSafe for Uri`

`impl<'a> PartialEq for Uri`

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

`impl<'a> TryFrom for Uri`

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

`impl<'a> TryFrom for Uri`

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

`impl<'a> TryFrom for Uri`

fn try_from(t: &'a [u8]) -> Result<Self, <Self as >::Error>

`impl<'a> TryFrom for Uri`

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

`impl<T> Any for Uri`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Uri`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Uri`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Uri`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Uri`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Uri`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T> ToString for Uri`

fn to_string(self: &Self) -> String

`impl<T, U> Into for Uri`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Uri`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Uri`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>