logo
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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

Convert http::HeaderMap to our HeaderMap.

Converts to this type from the input type.

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

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

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

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.

Should always be Self

The resulting type after obtaining ownership.

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

Uses borrowed data to replace owned data, usually by cloning. 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