logo
pub struct Query<'a> { /* private fields */ }
Expand description

A URI query: ?foo&bar.

Implementations

Returns the raw, undecoded query value.

Example
let uri = uri!("/foo?baz+bar");
assert_eq!(uri.query().unwrap(), "baz+bar");
assert_eq!(uri.query().unwrap().raw(), "baz+bar");

Returns the raw, undecoded query value as an &str.

Example
let uri = uri!("/foo/bar?baz+bar");
assert_eq!(uri.query().unwrap(), "baz+bar");
assert_eq!(uri.query().unwrap().as_str(), "baz+bar");

Returns an iterator over the non-empty, undecoded (name, value) pairs of this query. If there is no query, the iterator is empty. Segments may be empty.

Example
use rocket::http::uri::Origin;

let uri = Origin::parse("/").unwrap();
assert!(uri.query().is_none());

let uri = Origin::parse("/?a=b&dog").unwrap();
let query_segs: Vec<_> = uri.query().unwrap().raw_segments().collect();
assert_eq!(query_segs, &["a=b", "dog"]);

// This is not normalized, so the query is `""`, the empty string.
let uri = Origin::parse("/?&").unwrap();
let query_segs: Vec<_> = uri.query().unwrap().raw_segments().collect();
assert_eq!(query_segs, &["", ""]);

// Recall that `uri!()` normalizes.
let uri = uri!("/?&");
assert!(uri.query().is_none());

// These are raw and undecoded. Use `segments()` for decoded variant.
let uri = Origin::parse("/foo/bar?a+b%2F=some+one%40gmail.com&&%26%3D2").unwrap();
let query_segs: Vec<_> = uri.query().unwrap().raw_segments().collect();
assert_eq!(query_segs, &["a+b%2F=some+one%40gmail.com", "", "%26%3D2"]);

Returns a (smart) iterator over the non-empty, url-decoded (name, value) pairs of this query. If there is no query, the iterator is empty.

Example
use rocket::http::uri::Origin;

let uri = Origin::parse("/").unwrap();
assert!(uri.query().is_none());

let uri = Origin::parse("/foo/bar?a+b%2F=some+one%40gmail.com&&%26%3D2").unwrap();
let query_segs: Vec<_> = uri.query().unwrap().segments().collect();
assert_eq!(query_segs, &[("a b/", "some one@gmail.com"), ("&=2", "")]);

Methods from Deref<Target = RawStr>

Returns a percent-decoded version of the string.

Errors

Returns an Err if the percent encoded values are not valid UTF-8.

Example

With a valid string:

use rocket::http::RawStr;

let raw_str = RawStr::new("Hello%21");
let decoded = raw_str.percent_decode();
assert_eq!(decoded, Ok("Hello!".into()));

With an invalid string:

use rocket::http::RawStr;

// Note: Rocket should never hand you a bad `&RawStr`.
let bad_str = unsafe { std::str::from_utf8_unchecked(b"a=\xff") };
let bad_raw_str = RawStr::new(bad_str);
assert!(bad_raw_str.percent_decode().is_err());

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

Example

With a valid string:

use rocket::http::RawStr;

let raw_str = RawStr::new("Hello%21");
let decoded = raw_str.percent_decode_lossy();
assert_eq!(decoded, "Hello!");

With an invalid string:

use rocket::http::RawStr;

// Note: Rocket should never hand you a bad `&RawStr`.
let bad_str = unsafe { std::str::from_utf8_unchecked(b"a=\xff") };
let bad_raw_str = RawStr::new(bad_str);
assert_eq!(bad_raw_str.percent_decode_lossy(), "a=�");

Returns a percent-encoded version of the string.

Example

With a valid string:

use rocket::http::RawStr;

let raw_str = RawStr::new("Hello%21");
let decoded = raw_str.percent_decode();
assert_eq!(decoded, Ok("Hello!".into()));

With an invalid string:

use rocket::http::RawStr;

// NOTE: Rocket will never hand you a bad `&RawStr`.
let bad_str = unsafe { std::str::from_utf8_unchecked(b"a=\xff") };
let bad_raw_str = RawStr::new(bad_str);
assert!(bad_raw_str.percent_decode().is_err());

Returns a URL-decoded version of the string. This is identical to percent decoding except that + characters are converted into spaces. This is the encoding used by form values.

Errors

Returns an Err if the percent encoded values are not valid UTF-8.

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("Hello%2C+world%21");
let decoded = raw_str.url_decode();
assert_eq!(decoded.unwrap(), "Hello, world!");

Returns a URL-decoded version of the string.

Any invalid UTF-8 percent-encoded byte sequences will be replaced � U+FFFD, the replacement character. This is identical to lossy percent decoding except that + characters are converted into spaces. This is the encoding used by form values.

Example

With a valid string:

use rocket::http::RawStr;

let raw_str: &RawStr = "Hello%2C+world%21".into();
let decoded = raw_str.url_decode_lossy();
assert_eq!(decoded, "Hello, world!");

With an invalid string:

use rocket::http::RawStr;

// Note: Rocket should never hand you a bad `&RawStr`.
let bad_str = unsafe { std::str::from_utf8_unchecked(b"a+b=\xff") };
let bad_raw_str = RawStr::new(bad_str);
assert_eq!(bad_raw_str.url_decode_lossy(), "a b=�");

Returns an HTML escaped version of self. Allocates only when characters need to be escaped.

The following characters are escaped: &, <, >, ", ', /, `. This suffices as long as the escaped string is not used in an execution context such as inside of <script> or <style> tags! See the OWASP XSS Prevention Rules for more information.

Example

Strings with HTML sequences are escaped:

use rocket::http::RawStr;

let raw_str: &RawStr = "<b>Hi!</b>".into();
let escaped = raw_str.html_escape();
assert_eq!(escaped, "&lt;b&gt;Hi!&lt;&#x2F;b&gt;");

let raw_str: &RawStr = "Hello, <i>world!</i>".into();
let escaped = raw_str.html_escape();
assert_eq!(escaped, "Hello, &lt;i&gt;world!&lt;&#x2F;i&gt;");

Strings without HTML sequences remain untouched:

use rocket::http::RawStr;

let raw_str: &RawStr = "Hello!".into();
let escaped = raw_str.html_escape();
assert_eq!(escaped, "Hello!");

let raw_str: &RawStr = "大阪".into();
let escaped = raw_str.html_escape();
assert_eq!(escaped, "大阪");

Returns the length of self.

This length is in bytes, not chars or graphemes. In other words, it may not be what a human considers the length of the string.

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("Hello, world!");
assert_eq!(raw_str.len(), 13);

Returns true if self has a length of zero bytes.

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("Hello, world!");
assert!(!raw_str.is_empty());

let raw_str = RawStr::new("");
assert!(raw_str.is_empty());

Converts self into an &str.

This method should be used sparingly. Only use this method when you are absolutely certain that doing so is safe.

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("Hello, world!");
assert_eq!(raw_str.as_str(), "Hello, world!");

Converts self into an &[u8].

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("hi");
assert_eq!(raw_str.as_bytes(), &[0x68, 0x69]);

Converts a string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a u8. This pointer will be pointing to the first byte of the string slice.

The caller must ensure that the returned pointer is never written to. If you need to mutate the contents of the string slice, use as_mut_ptr.

Examples

Basic usage:

use rocket::http::RawStr;

let raw_str = RawStr::new("hi");
let ptr = raw_str.as_ptr();

Converts self into an &UncasedStr.

This method should be used sparingly. Only use this method when you are absolutely certain that doing so is safe.

Example
use rocket::http::RawStr;

let raw_str = RawStr::new("Content-Type");
assert!(raw_str.as_uncased_str() == "content-TYPE");

Returns true if the given pattern matches a sub-slice of this string slice.

Returns false if it does not.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples

Basic usage:

use rocket::http::RawStr;

let bananas = RawStr::new("bananas");

assert!(bananas.contains("nana"));
assert!(!bananas.contains("apples"));

Returns true if the given pattern matches a prefix of this string slice.

Returns false if it does not.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples

Basic usage:

use rocket::http::RawStr;

let bananas = RawStr::new("bananas");

assert!(bananas.starts_with("bana"));
assert!(!bananas.starts_with("nana"));

Returns true if the given pattern matches a suffix of this string slice.

Returns false if it does not.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples

Basic usage:

use rocket::http::RawStr;

let bananas = RawStr::new("bananas");

assert!(bananas.ends_with("anas"));
assert!(!bananas.ends_with("nana"));

Returns the byte index of the first character of this string slice that matches the pattern.

Returns None if the pattern doesn’t match.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Example
use rocket::http::RawStr;

let s = RawStr::new("Löwe 老虎 Léopard Gepardi");

assert_eq!(s.find('L'), Some(0));
assert_eq!(s.find('é'), Some(14));
assert_eq!(s.find("pard"), Some(17));

An iterator over substrings of this string slice, separated by characters matched by a pattern.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples

Simple patterns:

use rocket::http::RawStr;

let v: Vec<_> = RawStr::new("Mary had a little lamb")
    .split(' ')
    .map(|r| r.as_str())
    .collect();

assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);

Splits self into two pieces: the piece before the first byte b and the piece after (not including b). Returns the tuple (before, after). If b is not in self, or b is not an ASCII characters, returns the entire string self as before and the empty string as after.

Example
use rocket::http::RawStr;

let haystack = RawStr::new("a good boy!");

let (before, after) = haystack.split_at_byte(b'a');
assert_eq!(before, "");
assert_eq!(after, " good boy!");

let (before, after) = haystack.split_at_byte(b' ');
assert_eq!(before, "a");
assert_eq!(after, "good boy!");

let (before, after) = haystack.split_at_byte(b'o');
assert_eq!(before, "a g");
assert_eq!(after, "od boy!");

let (before, after) = haystack.split_at_byte(b'!');
assert_eq!(before, "a good boy");
assert_eq!(after, "");

let (before, after) = haystack.split_at_byte(b'?');
assert_eq!(before, "a good boy!");
assert_eq!(after, "");

let haystack = RawStr::new("");
let (before, after) = haystack.split_at_byte(b' ');
assert_eq!(before, "");
assert_eq!(after, "");

Returns a string slice with the prefix removed.

If the string starts with the pattern prefix, returns substring after the prefix, wrapped in Some. This method removes the prefix exactly once.

If the string does not start with prefix, returns None.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples
use rocket::http::RawStr;

assert_eq!(RawStr::new("foo:bar").strip_prefix("foo:").unwrap(), "bar");
assert_eq!(RawStr::new("foofoo").strip_prefix("foo").unwrap(), "foo");
assert!(RawStr::new("foo:bar").strip_prefix("bar").is_none());

Returns a string slice with the suffix removed.

If the string ends with the pattern suffix, returns the substring before the suffix, wrapped in Some. Unlike trim_end_matches, this method removes the suffix exactly once.

If the string does not end with suffix, returns None.

The pattern can be a &str, char, a slice of chars, or a function or closure that determines if a character matches.

Examples
use rocket::http::RawStr;

assert_eq!(RawStr::new("bar:foo").strip_suffix(":foo").unwrap(), "bar");
assert_eq!(RawStr::new("foofoo").strip_suffix("foo").unwrap(), "foo");
assert!(RawStr::new("bar:foo").strip_suffix("bar").is_none());

Parses this string slice into another type.

Because parse is so general, it can cause problems with type inference. As such, parse is one of the few times you’ll see the syntax affectionately known as the ‘turbofish’: ::<>. This helps the inference algorithm understand specifically which type you’re trying to parse into.

Errors

Will return Err if it’s not possible to parse this string slice into the desired type.

Examples

Basic usage

use rocket::http::RawStr;

let four: u32 = RawStr::new("4").parse().unwrap();

assert_eq!(4, four);

Trait Implementations

Converts this type into a shared reference of the (usually inferred) input type.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Compare self to key and return true if they are equal.

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Converts self into a collection.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more