Struct HeaderMap

pub struct HeaderMap { /* private fields */ }

A multi-map of HTTP headers.

HeaderMap is a “multi-map” of HeaderName to one or more HeaderValues.

Examples

let mut map = HeaderMap::new();

map.insert(header::CONTENT_TYPE, HeaderValue::from_static("text/plain"));
map.insert(header::ORIGIN, HeaderValue::from_static("example.com"));

assert!(map.contains_key(header::CONTENT_TYPE));
assert!(map.contains_key(header::ORIGIN));

let mut removed = map.remove(header::ORIGIN);
assert_eq!(removed.next().unwrap(), "example.com");

assert!(!map.contains_key(header::ORIGIN));

Construct a header map using the FromIterator implementation. Note that it uses the append strategy, so duplicate header names are preserved.

use actix_http::header::{self, HeaderMap, HeaderValue};

let headers = HeaderMap::from_iter([
    (header::CONTENT_TYPE, HeaderValue::from_static("text/plain")),
    (header::COOKIE, HeaderValue::from_static("foo=1")),
    (header::COOKIE, HeaderValue::from_static("bar=1")),
]);

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

Implementations

impl HeaderMap

pub fn new() -> HeaderMap

Create an empty HeaderMap.

The map will be created without any capacity; this function will not allocate.

Examples

let map = HeaderMap::new();

assert!(map.is_empty());
assert_eq!(0, map.capacity());

pub fn with_capacity(capacity: usize) -> HeaderMap

Create an empty HeaderMap with the specified capacity.

The map will be able to hold at least capacity elements without needing to reallocate. If capacity is 0, the map will be created without allocating.

Examples

let map = HeaderMap::with_capacity(16);

assert!(map.is_empty());
assert!(map.capacity() >= 16);

pub fn len(&self) -> usize

Returns the number of values stored in the map.

See also: len_keys.

Examples

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

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));
assert_eq!(map.len(), 2);

map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));
assert_eq!(map.len(), 3);

pub fn len_keys(&self) -> usize

Returns the number of keys stored in the map.

The number of values stored will be at least this number. See also: Self::len.

Examples

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

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));
assert_eq!(map.len_keys(), 2);

map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));
assert_eq!(map.len_keys(), 2);

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Examples

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

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
assert!(!map.is_empty());

pub fn clear(&mut self)

Clears the map, removing all name-value pairs.

Keeps the allocated memory for reuse.

Examples

let mut map = HeaderMap::new();

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));
assert_eq!(map.len(), 2);

map.clear();
assert!(map.is_empty());

pub fn get(&self, key: impl AsHeaderName) -> Option<&HeaderValue>

Returns a reference to the first value associated with a header name.

Returns None if there is no value associated with the key.

Even when multiple values are associated with the key, the “first” one is returned but is not guaranteed to be chosen with any particular order; though, the returned item will be consistent for each call to get if the map has not changed.

See also: get_all.

Examples

let mut map = HeaderMap::new();

map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));

let cookie = map.get(header::SET_COOKIE).unwrap();
assert_eq!(cookie, "one=1");

map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));
assert_eq!(map.get(header::SET_COOKIE).unwrap(), "one=1");

assert_eq!(map.get(header::SET_COOKIE), map.get("set-cookie"));
assert_eq!(map.get(header::SET_COOKIE), map.get("Set-Cookie"));

assert!(map.get(header::HOST).is_none());
assert!(map.get("INVALID HEADER NAME").is_none());

pub fn get_mut(&mut self, key: impl AsHeaderName) -> Option<&mut HeaderValue>

Returns a mutable reference to the first value associated a header name.

Returns None if there is no value associated with the key.

Even when multiple values are associated with the key, the “first” one is returned but is not guaranteed to be chosen with any particular order; though, the returned item will be consistent for each call to get_mut if the map has not changed.

See also: get_all.

Examples

let mut map = HeaderMap::new();

map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));

let mut cookie = map.get_mut(header::SET_COOKIE).unwrap();
assert_eq!(cookie, "one=1");

*cookie = HeaderValue::from_static("three=3");
assert_eq!(map.get(header::SET_COOKIE).unwrap(), "three=3");

assert!(map.get(header::HOST).is_none());
assert!(map.get("INVALID HEADER NAME").is_none());

pub fn get_all(&self, key: impl AsHeaderName) -> Iter<'_, HeaderValue>

Returns an iterator over all values associated with a header name.

The returned iterator does not incur any allocations and will yield no items if there are no values associated with the key. Iteration order is guaranteed to be the same as insertion order.

Examples

let mut map = HeaderMap::new();

let mut none_iter = map.get_all(header::ORIGIN);
assert!(none_iter.next().is_none());

map.insert(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));

let mut set_cookies_iter = map.get_all(header::SET_COOKIE);
assert_eq!(set_cookies_iter.next().unwrap(), "one=1");
assert_eq!(set_cookies_iter.next().unwrap(), "two=2");
assert!(set_cookies_iter.next().is_none());

pub fn contains_key(&self, key: impl AsHeaderName) -> bool

Returns true if the map contains a value for the specified key.

Invalid header names will simply return false.

Examples

let mut map = HeaderMap::new();
assert!(!map.contains_key(header::ACCEPT));

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
assert!(map.contains_key(header::ACCEPT));

pub fn insert(&mut self, name: HeaderName, val: HeaderValue) -> Removed

Inserts (overrides) a name-value pair in the map.

If the map already contained this key, the new value is associated with the key and all previous values are removed and returned as a Removed iterator. The key is not updated; this matters for types that can be == without being identical.

Examples

let mut map = HeaderMap::new();

map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
assert!(map.contains_key(header::ACCEPT));
assert_eq!(map.len(), 1);

let mut removed = map.insert(header::ACCEPT, HeaderValue::from_static("text/csv"));
assert_eq!(removed.next().unwrap(), "text/plain");
assert!(removed.next().is_none());

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

A convenience method is provided on the returned iterator to check if the insertion replaced any values.

let mut map = HeaderMap::new();

let removed = map.insert(header::ACCEPT, HeaderValue::from_static("text/plain"));
assert!(removed.is_empty());

let removed = map.insert(header::ACCEPT, HeaderValue::from_static("text/html"));
assert!(!removed.is_empty());

pub fn append(&mut self, key: HeaderName, value: HeaderValue)

Appends a name-value pair to the map.

If the map already contained this key, the new value is added to the list of values currently associated with the key. The key is not updated; this matters for types that can be == without being identical.

Examples

let mut map = HeaderMap::new();

map.append(header::HOST, HeaderValue::from_static("example.com"));
assert_eq!(map.len(), 1);

map.append(header::ACCEPT, HeaderValue::from_static("text/csv"));
assert_eq!(map.len(), 2);

map.append(header::ACCEPT, HeaderValue::from_static("text/html"));
assert_eq!(map.len(), 3);

pub fn remove(&mut self, key: impl AsHeaderName) -> Removed

Removes all headers for a particular header name from the map.

Providing an invalid header names (as a string argument) will have no effect and return without error.

Examples

let mut map = HeaderMap::new();

map.append(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("one=2"));

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

let mut removed = map.remove(header::SET_COOKIE);
assert_eq!(removed.next().unwrap(), "one=1");
assert_eq!(removed.next().unwrap(), "one=2");
assert!(removed.next().is_none());

assert!(map.is_empty());

A convenience method is provided on the returned iterator to check if the remove call actually removed any values.

let mut map = HeaderMap::new();

let removed = map.remove("accept");
assert!(removed.is_empty());

map.insert(header::ACCEPT, HeaderValue::from_static("text/html"));
let removed = map.remove("accept");
assert!(!removed.is_empty());

pub fn capacity(&self) -> usize

Returns the number of single-value headers the map can hold without needing to reallocate.

Since this is a multi-value map, the actual capacity is much larger when considering each header name can be associated with an arbitrary number of values. The effect is that the size of len may be greater than capacity since it counts all the values. Conversely, len_keys will never be larger than capacity.

Examples

let map = HeaderMap::with_capacity(16);

assert!(map.is_empty());
assert!(map.capacity() >= 16);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more headers to be inserted in the map.

The header map may reserve more space to avoid frequent reallocations. Additional capacity only considers single-value headers.

Panics

Panics if the new allocation size overflows usize.

Examples

let mut map = HeaderMap::with_capacity(2);
assert!(map.capacity() >= 2);

map.reserve(100);
assert!(map.capacity() >= 102);

assert!(map.is_empty());

pub fn iter(&self) -> Iter<'_>

An iterator over all name-value pairs.

Names will be yielded for each associated value. So, if a key has 3 associated values, it will be yielded 3 times. The iteration order should be considered arbitrary.

Examples

let mut map = HeaderMap::new();

let mut iter = map.iter();
assert!(iter.next().is_none());

map.append(header::HOST, HeaderValue::from_static("duck.com"));
map.append(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));

let mut iter = map.iter();
assert!(iter.next().is_some());
assert!(iter.next().is_some());
assert!(iter.next().is_some());
assert!(iter.next().is_none());

let pairs = map.iter().collect::<Vec<_>>();
assert!(pairs.contains(&(&header::HOST, &HeaderValue::from_static("duck.com"))));
assert!(pairs.contains(&(&header::SET_COOKIE, &HeaderValue::from_static("one=1"))));
assert!(pairs.contains(&(&header::SET_COOKIE, &HeaderValue::from_static("two=2"))));

pub fn keys(&self) -> Keys<'_>

An iterator over all contained header names.

Each name will only be yielded once even if it has multiple associated values. The iteration order should be considered arbitrary.

Examples

let mut map = HeaderMap::new();

let mut iter = map.keys();
assert!(iter.next().is_none());

map.append(header::HOST, HeaderValue::from_static("duck.com"));
map.append(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));

let keys = map.keys().cloned().collect::<Vec<_>>();
assert_eq!(keys.len(), 2);
assert!(keys.contains(&header::HOST));
assert!(keys.contains(&header::SET_COOKIE));

pub fn retain<F>(&mut self, retain_fn: F)

where F: FnMut(&HeaderName, &mut HeaderValue) -> bool,

Retains only the headers specified by the predicate.

In other words, removes all headers (name, val) for which retain_fn(&name, &mut val) returns false.

The order in which headers are visited should be considered arbitrary.

Examples

let mut map = HeaderMap::new();

map.append(header::HOST, HeaderValue::from_static("duck.com"));
map.append(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));

map.retain(|name, val| val.as_bytes().starts_with(b"one"));

assert_eq!(map.len(), 1);
assert!(map.contains_key(&header::SET_COOKIE));

pub fn drain(&mut self) -> Drain<'_>

Clears the map, returning all name-value sets as an iterator.

Header names will only be yielded for the first value in each set. All items that are yielded without a name and after an item with a name are associated with that same name. The first item will always contain a name.

Keeps the allocated memory for reuse.

Examples

let mut map = HeaderMap::new();

let mut iter = map.drain();
assert!(iter.next().is_none());
drop(iter);

map.append(header::SET_COOKIE, HeaderValue::from_static("one=1"));
map.append(header::SET_COOKIE, HeaderValue::from_static("two=2"));

let mut iter = map.drain();
assert_eq!(iter.next().unwrap(), (Some(header::SET_COOKIE), HeaderValue::from_static("one=1")));
assert_eq!(iter.next().unwrap(), (None, HeaderValue::from_static("two=2")));
drop(iter);

assert!(map.is_empty());

Trait Implementations

impl Clone for HeaderMap

fn clone(&self) -> HeaderMap

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for HeaderMap

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

Formats the value using the given formatter.

impl Default for HeaderMap

fn default() -> HeaderMap

Returns the “default value” for a type.

impl From<HeaderMap> for HeaderMap

Convert a http::HeaderMap to our HeaderMap.

fn from(map: HeaderMap) -> HeaderMap

Converts to this type from the input type.

impl FromIterator<(HeaderName, HeaderValue)> for HeaderMap

fn from_iter<T>(iter: T) -> HeaderMap

where T: IntoIterator<Item = (HeaderName, HeaderValue)>,

Creates a value from an iterator.

impl<'a> IntoIterator for &'a HeaderMap

type Item = (&'a HeaderName, &'a HeaderValue)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a HeaderMap as IntoIterator>::IntoIter

Creates an iterator from a value.

impl IntoIterator for HeaderMap

Note that this implementation will clone a HeaderName for each value. Consider using drain to control header name cloning.

type Item = (HeaderName, HeaderValue)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> <HeaderMap as IntoIterator>::IntoIter

Creates an iterator from a value.