Struct Headers 

pub struct Headers { /* private fields */ }

The ordered header collection.

Order is preserved absolutely, including the relative order of same-named headers. Via order determines where a response goes, so nothing here ever sorts or deduplicates.

Implementations

impl Headers

pub fn new() -> Self

An empty collection.

pub fn len(&self) -> usize

How many header fields are present.

pub fn is_empty(&self) -> bool

Whether there are no headers.

pub fn push(&mut self, header: Header)

Append a header, keeping any existing ones of the same name.

pub fn push_front(&mut self, header: Header)

Insert a header at the front — where a new Via goes.

pub fn iter(&self) -> impl Iterator<Item = &Header>

Every header, in wire order.

pub fn get(&self, name: &HeaderName) -> Option<&Header>

The first header with this name.

pub fn get_all<'a>( &'a self, name: &'a HeaderName, ) -> impl Iterator<Item = &'a Header>

Every header with this name, in wire order.

pub fn count(&self, name: &HeaderName) -> usize

How many headers carry this name.

pub fn remove_all(&mut self, name: &HeaderName) -> usize

Remove every header with this name, returning how many went.

pub fn remove_first(&mut self, name: &HeaderName) -> Option<Header>

Remove the topmost header with this name and return it.

The one a forwarding element needs constantly: RFC 3261 §16.7 step 2 has a proxy remove the topmost Via from a response before forwarding it, and §16.6 has it push its own onto a request. Order is semantic for Via, Route, Record-Route and Path — it is the routing — so this is an exact position rather than a set operation, and everything else keeps its place.

pub fn insert(&mut self, index: usize, header: Header)

Insert a header at an absolute position.

An index past the end appends rather than panicking. This crate parses hostile input and a caller’s index is often derived from it; a panic here would be a remote denial of service reachable through arithmetic, which is exactly the class of bug the builders exist to make unrepresentable.

pub fn retain(&mut self, f: impl FnMut(&Header) -> bool)

Keep the headers a predicate accepts, in place and in order.

The general case behind Headers::remove_all, for the filters a forwarding element writes that are not “by name” — stripping hop-by-hop headers, dropping a Route that names this proxy, removing everything a policy did not whitelist.

pub fn replace_address_uri( &mut self, name: &HeaderName, value_index: usize, uri: &Uri, ) -> Result<(), AddressEditError>

Replace one address URI by its flattened wire-order value index.

Repeated rows and comma-joined values share one zero-based index space. Every matching row is parsed before mutation, so a malformed later row cannot leave a partial edit behind.

pub fn replace_address_presentation( &mut self, name: &HeaderName, value_index: usize, display_name: Option<&str>, uri: &Uri, ) -> Result<(), AddressEditError>

Replace one address presentation by its flattened wire-order value index.

Repeated rows and comma-joined values share one zero-based index space. Every matching row is parsed before mutation, so a malformed later row cannot leave a partial edit behind.

pub fn replace_warning_agent_with_pseudonym( &mut self, value_index: usize, pseudonym: &[u8], ) -> Result<(), WarningEditError>

Replace one Warning agent by its flattened wire-order value index.

Repeated rows and comma-joined values share one zero-based index space. Every Warning row is parsed before mutation, so a malformed later row cannot leave a partial edit behind.

pub fn remove_address_value( &mut self, name: &HeaderName, value_index: usize, ) -> Result<(), AddressEditError>

Remove one address value by its flattened wire-order index.

If it was a row’s sole value, that exact field line is removed. Otherwise only the value and one adjacent list delimiter are removed; all surviving wire bytes retain their order.

pub fn value(&self, name: &HeaderName) -> Option<Cow<'_, [u8]>>

The first value with this name, unfolded.

pub fn write_to(&self, out: &mut Vec<u8>)

Write every header, each followed by CRLF.

impl Headers

pub fn typed<H: TypedHeader>(&self) -> Option<Result<H, HeaderError>>

Parse the first header of this type.

Returns None when the header is absent and Some(Err(..)) when it is present and malformed. Collapsing those two is how implementations end up treating a corrupt CSeq as a missing one.

pub fn typed_all<'a, H: TypedHeader + 'a>( &'a self, ) -> impl Iterator<Item = Result<H, HeaderError>> + 'a

Parse every header of this type, in wire order, yielding each element of a comma-separated row separately — one row of n values and n rows of one value are the same message (RFC 3261 §7.3).

Trait Implementations

impl Clone for Headers

fn clone(&self) -> Headers

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

Returns the “default value” for a type.