Struct rocket::http::HeaderMap

pub struct HeaderMap<'h> { /* private fields */ }
Expand description

A collection of headers, mapping a header name to its many ordered values.

§Case-Insensitivity

All header names, including those passed in to HeaderMap methods and those stored in an existing HeaderMap, are treated case-insensitively. This means that, for instance, a look for a header by the name of “aBC” will returns values for headers of names “AbC”, “ABC”, “abc”, and so on.

Implementations§

§

impl<'h> HeaderMap<'h>

pub fn new() -> HeaderMap<'h>

Returns an empty header collection.

§Example
use rocket::http::HeaderMap;

let map = HeaderMap::new();

pub fn contains(&self, name: &str) -> bool

Returns true if self contains a header with the name name.

§Example
use rocket::http::{HeaderMap, ContentType};

let mut map = HeaderMap::new();
map.add(ContentType::HTML);

assert!(map.contains("Content-Type"));
assert!(!map.contains("Accepts"));

pub fn len(&self) -> usize

Returns the number of values stored in the map.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
assert_eq!(map.len(), 0);

map.add_raw("X-Custom", "value_1");
assert_eq!(map.len(), 1);

map.replace_raw("X-Custom", "value_2");
assert_eq!(map.len(), 1);

map.add_raw("X-Custom", "value_1");
assert_eq!(map.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if there are no headers stored in the map. Otherwise returns false.

§Example
use rocket::http::HeaderMap;

let map = HeaderMap::new();
assert!(map.is_empty());

pub fn get<'a>(&'a self, name: &str) -> impl Iterator<Item = &'a str>

Returns an iterator over all of the values stored in self for the header with name name. The headers are returned in FIFO order.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");

assert_eq!(map.len(), 2);

let mut values = map.get("X-Custom");
assert_eq!(values.next(), Some("value_1"));
assert_eq!(values.next(), Some("value_2"));
assert_eq!(values.next(), None);

pub fn get_one<'a>(&'a self, name: &str) -> Option<&'a str>

Returns the first value stored for the header with name name if there is one.

§Examples

Retrieve the first value when one exists:

use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");

assert_eq!(map.len(), 2);

let first_value = map.get_one("X-Custom");
assert_eq!(first_value, Some("value_1"));

Attempt to retrieve a value that doesn’t exist:

use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");

let first_value = map.get_one("X-Other");
assert_eq!(first_value, None);

pub fn replace<'p, H>(&mut self, header: H) -> bool
where 'p: 'h, H: Into<Header<'p>>,

Replace any header that matches the name of header.name with header. If there is no such header in self, add header. If the matching header had multiple values, all of the values are removed, and only the value in header will remain.

§Example

Replace a header that doesn’t yet exist:

use rocket::http::{HeaderMap, ContentType};

let mut map = HeaderMap::new();
map.replace(ContentType::JSON);

assert!(map.get_one("Content-Type").is_some());

Replace a header that already exists:

use rocket::http::{HeaderMap, ContentType};

let mut map = HeaderMap::new();

map.replace(ContentType::JSON);
assert_eq!(map.get_one("Content-Type"), Some("application/json"));

map.replace(ContentType::GIF);
assert_eq!(map.get_one("Content-Type"), Some("image/gif"));
assert_eq!(map.len(), 1);

An example of case-insensitivity.

use rocket::http::{HeaderMap, Header, ContentType};

let mut map = HeaderMap::new();

map.replace(ContentType::JSON);
assert_eq!(map.get_one("Content-Type"), Some("application/json"));

map.replace(Header::new("CONTENT-type", "image/gif"));
assert_eq!(map.get_one("Content-Type"), Some("image/gif"));
assert_eq!(map.len(), 1);

pub fn replace_raw<'a, 'b, N, V>(&mut self, name: N, value: V) -> bool
where 'a: 'h, 'b: 'h, N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>,

A convenience method to replace a header using a raw name and value. Aliases replace(Header::new(name, value)). Should be used rarely.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();

map.replace_raw("X-Custom", "value_1");
assert_eq!(map.get_one("X-Custom"), Some("value_1"));

map.replace_raw("X-Custom", "value_2");
assert_eq!(map.get_one("X-Custom"), Some("value_2"));
assert_eq!(map.len(), 1);

pub fn replace_all<'n, 'v, H>(&mut self, name: H, values: Vec<Cow<'v, str>>)
where 'v: 'h, 'n: 'h, H: Into<Cow<'n, str>>,

Replaces all of the values for a header with name name with values. This a low-level method and should rarely be used.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");

let vals: Vec<_> = map.get("X-Custom").map(|s| s.to_string()).collect();
assert_eq!(vals, vec!["value_1", "value_2"]);

map.replace_all("X-Custom", vec!["value_3".into(), "value_4".into()]);
let vals: Vec<_> = map.get("X-Custom").collect();
assert_eq!(vals, vec!["value_3", "value_4"]);

pub fn add<'p, H>(&mut self, header: H)
where 'p: 'h, H: Into<Header<'p>>,

Adds header into the map. If a header with header.name was previously added, that header will have one more value.

use rocket::http::{Cookie, HeaderMap};

let mut map = HeaderMap::new();

map.add(&Cookie::new("a", "b"));
assert_eq!(map.get("Set-Cookie").count(), 1);

map.add(&Cookie::new("c", "d"));
assert_eq!(map.get("Set-Cookie").count(), 2);

pub fn add_raw<'a, 'b, N, V>(&mut self, name: N, value: V)
where 'a: 'h, 'b: 'h, N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>,

A convenience method to add a header using a raw name and value. Aliases add(Header::new(name, value)). Should be used rarely.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();

map.add_raw("X-Custom", "value_1");
assert_eq!(map.get("X-Custom").count(), 1);

map.add_raw("X-Custom", "value_2");
let values: Vec<_> = map.get("X-Custom").collect();
assert_eq!(values, vec!["value_1", "value_2"]);

pub fn add_all<'n, H>(&mut self, name: H, values: &mut Vec<Cow<'h, str>>)
where 'n: 'h, H: Into<Cow<'n, str>>,

Adds all of the values to a header with name name. This a low-level method and should rarely be used. values will be empty when this method returns.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();

let mut values = vec!["value_1".into(), "value_2".into()];
map.add_all("X-Custom", &mut values);
assert_eq!(map.get("X-Custom").count(), 2);
assert_eq!(values.len(), 0);

let mut values = vec!["value_3".into(), "value_4".into()];
map.add_all("X-Custom", &mut values);
assert_eq!(map.get("X-Custom").count(), 4);
assert_eq!(values.len(), 0);

let values: Vec<_> = map.get("X-Custom").collect();
assert_eq!(values, vec!["value_1", "value_2", "value_3", "value_4"]);

pub fn remove(&mut self, name: &str)

Remove all of the values for header with name name.

§Example
use rocket::http::HeaderMap;

let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");
map.add_raw("X-Other", "other");

assert_eq!(map.len(), 3);

map.remove("X-Custom");
assert_eq!(map.len(), 1);

pub fn remove_all(&mut self) -> Vec<Header<'h>>

Removes all of the headers stored in this map and returns a vector containing them. Header names are returned in no specific order, but all values for a given header name are grouped together, and values are in FIFO order.

§Example
use rocket::http::{HeaderMap, Header};
use std::collections::HashSet;

// The headers we'll be storing.
let all_headers = vec![
    Header::new("X-Custom", "value_1"),
    Header::new("X-Custom", "value_2"),
    Header::new("X-Other", "other")
];

// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers.clone() {
    map.add(header)
}

assert_eq!(map.len(), 3);

// Now remove them all, ensure the map is empty.
let removed_headers = map.remove_all();
assert!(map.is_empty());

// Create two sets: what we expect and got. Ensure they're equal.
let expected_set: HashSet<_> = all_headers.into_iter().collect();
let actual_set: HashSet<_> = removed_headers.into_iter().collect();
assert_eq!(expected_set, actual_set);

pub fn iter(&self) -> impl Iterator<Item = Header<'_>>

Returns an iterator over all of the Headers stored in the map. Header names are returned in no specific order, but all values for a given header name are grouped together, and values are in FIFO order.

§Example
use rocket::http::{HeaderMap, Header};

// The headers we'll be storing.
let all_headers = vec![
    Header::new("X-Custom", "value_1"),
    Header::new("X-Other", "other"),
    Header::new("X-Third", "third"),
];

// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers {
    map.add(header)
}

// Ensure there are three headers via the iterator.
assert_eq!(map.iter().count(), 3);

// Actually iterate through them.
for header in map.iter() {
    match header.name() {
        "X-Custom" => assert_eq!(header.value(), "value_1"),
        "X-Other" => assert_eq!(header.value(), "other"),
        "X-Third" => assert_eq!(header.value(), "third"),
        _ => unreachable!("there are only three headers")
    }
}

pub fn into_iter(self) -> impl Iterator<Item = Header<'h>>

Consumes self and returns an iterator over all of the Headers stored in the map. Header names are returned in no specific order, but all values for a given header name are grouped together, and values are in FIFO order.

§Example
use rocket::http::{HeaderMap, Header};

// The headers we'll be storing.
let all_headers = vec![
    Header::new("X-Custom", "value_1"),
    Header::new("X-Other", "other"),
    Header::new("X-Third", "third"),
];

// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers {
    map.add(header)
}

// Ensure there are three headers via the iterator.
assert_eq!(map.iter().count(), 3);

// Actually iterate through them.
for header in map.into_iter() {
    match header.name() {
        "X-Custom" => assert_eq!(header.value(), "value_1"),
        "X-Other" => assert_eq!(header.value(), "other"),
        "X-Third" => assert_eq!(header.value(), "third"),
        _ => unreachable!("there are only three headers")
    }
}

Trait Implementations§

§

impl<'h> Clone for HeaderMap<'h>

§

fn clone(&self) -> HeaderMap<'h>

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
§

impl<'h> Debug for HeaderMap<'h>

§

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

Formats the value using the given formatter. Read more
§

impl<'h> Default for HeaderMap<'h>

§

fn default() -> HeaderMap<'h>

Returns the “default value” for a type. Read more
§

impl<'h> PartialEq for HeaderMap<'h>

§

fn eq(&self, other: &HeaderMap<'h>) -> bool

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
§

impl<'h> StructuralPartialEq for HeaderMap<'h>

Auto Trait Implementations§

§

impl<'h> Freeze for HeaderMap<'h>

§

impl<'h> RefUnwindSafe for HeaderMap<'h>

§

impl<'h> Send for HeaderMap<'h>

§

impl<'h> Sync for HeaderMap<'h>

§

impl<'h> Unpin for HeaderMap<'h>

§

impl<'h> UnwindSafe for HeaderMap<'h>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T, I> AsResult<T, I> for T
where I: Input,

source§

fn as_result(self) -> Result<T, ParseErr<I>>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T> Typeable for T
where T: Any,

source§

fn get_type(&self) -> TypeId

Get the TypeId of this object.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V