Struct rocket::http::uri::URI

pub struct URI<'a> { /* fields omitted */ }

Borrowed string type for absolute URIs.

Methods

impl<'a> URI<'a>

pub fn new<T: Into<Cow<'a, str>>>(uri: T) -> URI<'a>

Constructs a new URI from a given string. The URI is assumed to be an absolute, well formed URI.

pub fn segment_count(&self) -> usize

Returns the number of segments in the URI. Empty segments, which are invalid according to RFC#3986, are not counted.

The segment count is cached after the first invocation. As a result, this function is O(1) after the first invocation, and O(n) before.

Examples

A valid URI with only non-empty segments:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c");
assert_eq!(uri.segment_count(), 3);

A URI with empty segments:

use rocket::http::uri::URI;

let uri = URI::new("/a/b//c/d///e");
assert_eq!(uri.segment_count(), 5);

Important traits for Segments<'a>

impl<'a> Iterator for Segments<'a> type Item = &'a str;

pub fn segments(&self) -> Segments

Returns an iterator over the segments of the path in this URI. Skips empty segments.

Examples

A valid URI with only non-empty segments:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c?a=true#done");
for (i, segment) in uri.segments().enumerate() {
    match i {
        0 => assert_eq!(segment, "a"),
        1 => assert_eq!(segment, "b"),
        2 => assert_eq!(segment, "c"),
        _ => panic!("only three segments")
    }
}

A URI with empty segments:

use rocket::http::uri::URI;

let uri = URI::new("///a//b///c////d?#");
for (i, segment) in uri.segments().enumerate() {
    match i {
        0 => assert_eq!(segment, "a"),
        1 => assert_eq!(segment, "b"),
        2 => assert_eq!(segment, "c"),
        3 => assert_eq!(segment, "d"),
        _ => panic!("only four segments")
    }
}

pub fn path(&self) -> &str

Returns the path part of this URI.

Examples

A URI with only a path:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c");
assert_eq!(uri.path(), "/a/b/c");

A URI with other components:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c?name=bob#done");
assert_eq!(uri.path(), "/a/b/c");

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

Returns the query part of this URI without the question mark, if there is any.

Examples

A URI with a query part:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c?alphabet=true");
assert_eq!(uri.query(), Some("alphabet=true"));

A URI without the query part:

use rocket::http::uri::URI;

let uri = URI::new("/a/b/c");
assert_eq!(uri.query(), None);

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

Returns the fargment part of this URI without the hash mark, if there is any.

Examples

A URI with a fragment part:

use rocket::http::uri::URI;

let uri = URI::new("/a?alphabet=true#end");
assert_eq!(uri.fragment(), Some("end"));

A URI without the fragment part:

use rocket::http::uri::URI;

let uri = URI::new("/a?query=true");
assert_eq!(uri.fragment(), None);

pub fn percent_decode(string: &[u8]) -> Result<Cow<str>, Utf8Error>

Returns a URL-decoded version of the string. If the percent encoded values are not valid UTF-8, an Err is returned.

Examples

use rocket::http::uri::URI;

let uri = URI::new("/Hello%2C%20world%21");
let decoded_path = URI::percent_decode(uri.path().as_bytes()).expect("decoded");
assert_eq!(decoded_path, "/Hello, world!");

pub fn percent_decode_lossy(string: &[u8]) -> Cow<str>

Returns a URL-decoded version of the path. Any invalid UTF-8 percent-encoded byte sequences will be replaced � U+FFFD, the replacement character.

Examples

use rocket::http::uri::URI;

let uri = URI::new("/Hello%2C%20world%21");
let decoded_path = URI::percent_decode_lossy(uri.path().as_bytes());
assert_eq!(decoded_path, "/Hello, world!");

pub fn percent_encode(string: &str) -> Cow<str>

Returns a URL-encoded version of the string. Any characters outside of visible ASCII-range are encoded as well as ' ', '"', '#', '<', '>', '`', '?', '{', '}', '%', and '/'.

Examples

use rocket::http::uri::URI;

let encoded = URI::percent_encode("hello?a=<b>hi</b>");
assert_eq!(encoded, "hello%3Fa=%3Cb%3Ehi%3C%2Fb%3E");

pub fn as_str(&self) -> &str

Returns the inner string of this URI.

The returned string is in raw form. It contains empty segments. If you'd like a string without empty segments, use to_string instead.

Example

use rocket::http::uri::URI;

let uri = URI::new("/a/b///c/d/e//f?name=Mike#end");
assert_eq!(uri.as_str(), "/a/b///c/d/e//f?name=Mike#end");

Trait Implementations

impl<'a, 'r> FromRequest<'a, 'r> for &'a URI<'a>

type Error = ()

The associated error to be returned if derivation fails.

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

Derives an instance of Self from the incoming request metadata.

impl<'a> From<&'a str> for URI<'a>

fn from(uri: &'a str) -> URI<'a>

Performs the conversion.

impl From<String> for URI<'static>

fn from(uri: String) -> URI<'static>

Performs the conversion.

impl<'a> Clone for URI<'a>

fn clone(&self) -> URI<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Eq for URI<'a>

impl<'a, 'b> PartialEq<URI<'b>> for URI<'a>

fn eq(&self, other: &URI<'b>) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> Display for URI<'a>

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

Formats the value using the given formatter.

impl<'a> Debug for URI<'a>

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

Formats the value using the given formatter.