pub struct HeaderMap { /* private fields */ }
Expand description
A multi-map of HTTP headers.
HeaderMap
is a “multi-map” of HeaderName
to one or more HeaderValue
s.
§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§
source§impl HeaderMap
impl HeaderMap
sourcepub fn new() -> 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());
sourcepub fn with_capacity(capacity: usize) -> HeaderMap
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);
sourcepub fn len(&self) -> usize
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);
sourcepub fn len_keys(&self) -> usize
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);
sourcepub fn is_empty(&self) -> bool
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());
sourcepub fn clear(&mut self)
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());
sourcepub fn get(&self, key: impl AsHeaderName) -> Option<&HeaderValue>
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());
sourcepub fn get_mut(&mut self, key: impl AsHeaderName) -> Option<&mut HeaderValue>
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());
sourcepub fn get_all(&self, key: impl AsHeaderName) -> Iter<'_, HeaderValue>
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());
sourcepub fn contains_key(&self, key: impl AsHeaderName) -> bool
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));
sourcepub fn insert(&mut self, name: HeaderName, val: HeaderValue) -> Removed ⓘ
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());
sourcepub fn append(&mut self, key: HeaderName, value: HeaderValue)
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);
sourcepub fn remove(&mut self, key: impl AsHeaderName) -> Removed ⓘ
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());
sourcepub fn capacity(&self) -> usize
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);
sourcepub fn reserve(&mut self, additional: usize)
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());
sourcepub fn iter(&self) -> Iter<'_> ⓘ
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"))));
sourcepub fn keys(&self) -> Keys<'_> ⓘ
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));
sourcepub fn retain<F>(&mut self, retain_fn: F)
pub fn retain<F>(&mut self, retain_fn: F)
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));
sourcepub fn drain(&mut self) -> Drain<'_> ⓘ
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 FromIterator<(HeaderName, HeaderValue)> for HeaderMap
impl FromIterator<(HeaderName, HeaderValue)> for HeaderMap
source§impl<'a> IntoIterator for &'a HeaderMap
impl<'a> IntoIterator for &'a HeaderMap
§type Item = (&'a HeaderName, &'a HeaderValue)
type Item = (&'a HeaderName, &'a HeaderValue)
source§impl IntoIterator for HeaderMap
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)
type Item = (HeaderName, HeaderValue)
Auto Trait Implementations§
impl Freeze for HeaderMap
impl RefUnwindSafe for HeaderMap
impl Send for HeaderMap
impl Sync for HeaderMap
impl Unpin for HeaderMap
impl UnwindSafe for HeaderMap
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)