Struct Headers

source

pub struct Headers { /* private fields */ }

Expand description

A list of headers.

Implementations§

source §

impl Headers

source

pub fn new() -> Self

Initialize an empty list of headers.

source

pub fn with_capacity(c: usize) -> Self

Initialize an empty list of headers backed by a vector with the provided capacity.

source

pub fn into_vec(self) -> Vec<Header>

Convert this list of headers to a Vec

source

pub fn len(&self) -> usize

Returns the number of headers.

source

pub fn is_empty(&self) -> bool

Returns true if len() is zero.

source

pub fn clear(&mut self)

Clear this set of headers.

source

pub fn insert<N, V>(&mut self, name: N, value: V) -> Result<&mut Self, Error>
where N: Into<HeaderName> + PartialEq<HeaderName>, V: Into<String> + AsRef<str>,

Insert or update a new header.

This returns an error if you attempt to specify a header with an invalid value (values must be printable ASCII and may not contain \r or \n)

§Example

let mut h = Headers::new();
h.insert("My-Cool-Header", "example")?;
assert_eq!(h.get("My-Cool-Header"), Some("example"));

// Note: names are sensitive
assert_eq!(h.get("my-cool-header"), Some("example"));

// Also note, constants for headers are in `viaduct::header_names`, and
// you can chain the result of this function.
h.insert(viaduct::header_names::CONTENT_TYPE, "something...")?
 .insert("Something-Else", "etc")?;

source

pub fn insert_if_missing<N, V>( &mut self, name: N, value: V, ) -> Result<&mut Self, Error>
where N: Into<HeaderName> + PartialEq<HeaderName>, V: Into<String> + AsRef<str>,

Insert the provided header unless a header is already specified. Mostly used internally, e.g. to set “Content-Type: application/json” in Request::json() unless it has been set specifically.

source

pub fn insert_header(&mut self, new: Header) -> &mut Self

Insert or update a header directly. Typically you will want to use insert over this, as it performs less work if the header needs updating instead of insertion.

source

pub fn extend<I>(&mut self, iter: I) -> &mut Self
where I: IntoIterator<Item = Header>,

Add all the headers in the provided iterator to this list of headers.

source

pub fn try_extend<I, E>(&mut self, iter: I) -> Result<&mut Self, E>
where I: IntoIterator<Item = Result<Header, E>>,

Add all the headers in the provided iterator, unless any of them are Err.

source

pub fn get_header<S>(&self, name: S) -> Option<&Header>
where S: PartialEq<HeaderName>,

Get the header object with the requested name. Usually, you will want to use get() or get_as::<T>() instead.

source

pub fn get<S>(&self, name: S) -> Option<&str>
where S: PartialEq<HeaderName>,

Get the value of the header with the provided name.

§Example

let mut h = Headers::new();
h.insert(CONTENT_TYPE, "application/json")?;
assert_eq!(h.get(CONTENT_TYPE), Some("application/json"));
assert_eq!(h.get("Something-Else"), None);

source

pub fn get_as<T, S>(&self, name: S) -> Option<Result<T, <T as FromStr>::Err>>
where T: FromStr, S: PartialEq<HeaderName>,

Get the value of the header with the provided name, and attempt to parse it using std::str::FromStr.

If the header is missing, it returns None.
If the header is present but parsing failed, returns Some(Err(<error returned by parsing>)).
Otherwise, returns Some(Ok(result)).

Note that if Option<Result<T, E>> is inconvenient for you, and you wish this returned Result<Option<T>, E>, you may use the built-in transpose() method to convert between them.

let mut h = Headers::new();
h.insert("Example", "1234")?.insert("Illegal", "abcd")?;
let v: Option<Result<i64, _>> = h.get_as("Example");
assert_eq!(v, Some(Ok(1234)));
assert_eq!(h.get_as::<i64, _>("Example"), Some(Ok(1234)));
assert_eq!(h.get_as::<i64, _>("Illegal"), Some("abcd".parse::<i64>()));
assert_eq!(h.get_as::<i64, _>("Something-Else"), None);

source

pub fn try_get<T, S>(&self, name: S) -> Option<T>
where T: FromStr, S: PartialEq<HeaderName>,

Get the value of the header with the provided name, and attempt to parse it using std::str::FromStr.

This is a variant of get_as that returns None on error, intended to be used for cases where missing and invalid headers should be treated the same. (With get_as this requires h.get_as(...).and_then(|r| r.ok()), which is somewhat opaque.

source