Struct rocket::http::RawStr[]

#[repr(transparent)]
pub struct RawStr(_);
Expand description

A reference to a string inside of a raw HTTP message.

A RawStr is an unsanitzed, unvalidated, and undecoded raw string from an HTTP message. It exists to separate validated string inputs, represented by the String, &str, and Cow<str> types, from unvalidated inputs, represented by &RawStr.

Validation

An &RawStr should be converted into one of the validated string input types through methods on RawStr. These methods are summarized below:

  • url_decode() - used to decode a raw string in a form value context
  • percent_decode(), percent_decode_lossy() - used to percent-decode a raw string, typically in a URL context
  • html_escape() - used to decode a string for use in HTML templates
  • as_str() - used when the RawStr is known to be safe in the context of its intended use. Use sparingly and with care!
  • as_uncased_str() - used when the RawStr is known to be safe in the context of its intended, uncased use

Note: Template engines like Tera and Handlebars all functions like html_escape() on all rendered template outputs by default.

Usage

A RawStr is a dynamically sized type (just like str). It is always used through a reference an as &RawStr (just like &str).

Implementations

Constructs an &RawStr from a string-like type at no cost.

Example

use rocket::http::RawStr;

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

// `into` can also be used; note that the type must be specified
let raw_str: &RawStr = "Hello, world!".into();

Construct a Cow<RawStr> from a Cow<Str>. Does not allocate.

See RawStr::into_cow_str() for the inverse operation.

Example

use std::borrow::Cow;
use rocket::http::RawStr;

let cow_str = Cow::from("hello!");
let cow_raw = RawStr::from_cow_str(cow_str);
assert_eq!(cow_raw.as_str(), "hello!");

Construct a Cow<str> from a Cow<RawStr>. Does not allocate.

See RawStr::from_cow_str() for the inverse operation.

Example

use std::borrow::Cow;
use rocket::http::RawStr;

let cow_raw = Cow::from(RawStr::new("hello!"));
let cow_str = RawStr::into_cow_str(cow_raw);
assert_eq!(&*cow_str, "hello!");

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 percent-encoded version of bytes.

Example

use rocket::http::RawStr;

// Note: Rocket should never hand you a bad `&RawStr`.
let bytes = &[93, 12, 0, 13, 1];
let encoded = RawStr::percent_encode_bytes(&bytes[..]);

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

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Immutably borrows from an owned value. Read more

Immutably borrows from an owned value. Read more

Formats the value using the given formatter. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Performs the conversion.

Performs the conversion.

The associated error to be returned when the guard fails.

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data. Read more

Feeds this value into the given Hasher. Read more

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

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. 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 !=.

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 !=.

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 returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Serialize this value into the given Serde serializer. Read more

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)

recently added

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

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Convert self to an UncasedStr.

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.

Pipes by value. This is generally the method you want to use. Read more

Borrows self and passes that borrow into the pipe function. Read more

Mutably borrows self and passes that borrow into the pipe function. Read more

Borrows self, then passes self.borrow() into the pipe function. Read more

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more

Borrows self, then passes self.as_ref() into the pipe function.

Mutably borrows self, then passes self.as_mut() into the pipe function. Read more

Borrows self, then passes self.deref() into the pipe function.

Mutably borrows self, then passes self.deref_mut() into the pipe function. Read more

Converts the given value to a String. Read more