Struct actix_web::http::header::HeaderMap

source ·

pub struct HeaderMap { /* private fields */ }

Expand description

A multi-map of HTTP headers.

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

Examples

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

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));

Implementations§

source §

impl HeaderMap

source

pub fn new() -> HeaderMap

Create an empty HeaderMap.

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

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.

pub fn len(&self) -> usize

Returns the number of values stored in the map.

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.

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

pub fn clear(&mut self)

Clears the map, removing all name-value pairs.

Keeps the allocated memory for reuse.

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.

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());

source

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.

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());

source

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());

source

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));

source

pub fn insert(&mut self, key: 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());

source

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);

source

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());

source

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);

source

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());

source

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"))));

source

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));

source

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));

source

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());