Struct Headers 

pub struct Headers { /* private fields */ }

An immutable view of headers

Header values are stored exactly as received and are not required to be valid UTF-8: an HTTP header value may contain any octet in 0x80..=0xFF (obs-text, RFC 7230), and an arbitrary sequence of those is not necessarily valid UTF-8. The string-typed accessors (get, get_all, iter, remove) therefore yield only values that are valid UTF-8, and skip those that are not. Use the corresponding byte accessors (get_bytes, get_all_bytes, iter_bytes) to observe every value.

Consequently len and contains_key count and report values the string accessors skip.

Implementations

impl Headers

pub fn new() -> Self

Create an empty header map

pub fn get(&self, key: impl AsRef<str>) -> Option<&str>

Returns the value for a given key

Returns None if the header is absent, or if its value is not valid UTF-8; use get_bytes to read a value of any encoding.

If multiple values are associated, the first value is returned See HeaderMap::get

pub fn try_get(&self, key: impl AsRef<str>) -> Option<Result<&str, &[u8]>>

Returns the value for a given key, distinguishing an unreadable value from an absent header

Some(Ok(_)) is a value that is valid UTF-8, Some(Err(_)) is the raw octets of one that is not, and None means the header is absent. get collapses the first two into None, so use this where the difference matters.

If multiple values are associated, the first value is returned.

pub fn get_all(&self, key: impl AsRef<str>) -> impl Iterator<Item = &str>

Returns all values for a given key

Values that are not valid UTF-8 are skipped; use get_all_bytes to read values of any encoding.

pub fn get_bytes(&self, key: impl AsRef<str>) -> Option<&[u8]>

Returns the value for a given key as raw bytes

Unlike get, the returned bytes are not required to be valid UTF-8.

If multiple values are associated, the first value is returned.

pub fn get_all_bytes(&self, key: impl AsRef<str>) -> impl Iterator<Item = &[u8]>

Returns all values for a given key as raw bytes

Unlike get_all, the returned bytes are not required to be valid UTF-8.

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

Returns an iterator over the headers

pub fn iter_bytes(&self) -> impl Iterator<Item = (&str, &[u8])>

Returns an iterator over the headers, pairing each name with its raw value bytes

Unlike iter, the returned bytes are not required to be valid UTF-8.

pub fn len(&self) -> usize

Returns the total number of values stored in the map

pub fn is_empty(&self) -> bool

Returns true if there are no headers

pub fn contains_key(&self, key: impl AsRef<str>) -> bool

Returns true if this header is present

pub fn insert( &mut self, key: impl AsHeaderComponent, value: impl AsHeaderComponent, ) -> Option<String>

Insert a value into the headers structure.

This will replace any existing value for this key. Returns the previous associated value if any.

Panics

If the key is not valid ASCII, or if the value is not valid UTF-8, this function will panic.

pub fn try_insert( &mut self, key: impl AsHeaderComponent, value: impl AsHeaderComponent, ) -> Result<Option<String>, HttpError>

Insert a value into the headers structure.

This will replace any existing value for this key. Returns the previous associated value if any.

If the key is not valid ASCII, or if the value is not valid UTF-8, this function will return an error.

pub fn append( &mut self, key: impl AsHeaderComponent, value: impl AsHeaderComponent, ) -> bool

Appends a value to a given key

Panics

If the key is not valid ASCII, or if the value is not valid UTF-8, this function will panic.

pub fn try_append( &mut self, key: impl AsHeaderComponent, value: impl AsHeaderComponent, ) -> Result<bool, HttpError>

Appends a value to a given key

If the key is not valid ASCII, or if the value is not valid UTF-8, this function will return an error.

pub fn remove(&mut self, key: impl AsRef<str>) -> Option<String>

Removes all headers with a given key

If there are multiple entries for this key, the first entry is returned. Returns None if the first value is not valid UTF-8; the headers are removed either way.

Trait Implementations

impl Clone for Headers

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Headers

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

Formats the value using the given formatter.

impl Default for Headers

fn default() -> Self

Returns the “default value” for a type.

impl<'a> IntoIterator for &'a Headers

type Item = (&'a str, &'a str)

The type of the elements being iterated over.

type IntoIter = HeadersIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl TryFrom<HeaderMap> for Headers

Available on crate feature http-02x only.

type Error = HttpError

The type returned in the event of a conversion error.

fn try_from(value: HeaderMap) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<HeaderMap> for Headers

Available on crate feature http-1x only.

type Error = HttpError

The type returned in the event of a conversion error.

fn try_from(value: HeaderMap) -> Result<Self, Self::Error>

Performs the conversion.