Struct actix_web::http::header::map::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.

§Examples
let map = HeaderMap::new();

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

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

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

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

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

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

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

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

Trait Implementations§

source§

impl Clone for HeaderMap

source§

fn clone(&self) -> HeaderMap

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
source§

impl Debug for HeaderMap

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for HeaderMap

source§

fn default() -> HeaderMap

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

impl From<HeaderMap> for HeaderMap

Convert a http::HeaderMap to our HeaderMap.

source§

fn from(map: HeaderMap) -> HeaderMap

Converts to this type from the input type.
source§

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?
source§

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

Creates an iterator from a value. Read more
source§

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?
source§

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

Creates an iterator from a value. Read more

Auto Trait Implementations§

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

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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.

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.
§

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

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more