pub struct HeaderMap<'h> { /* private fields */ }
Expand description
A collection of headers, mapping a header name to its many ordered values.
Case-Insensitivity
All header names, including those passed in to HeaderMap
methods and those
stored in an existing HeaderMap
, are treated case-insensitively. This
means that, for instance, a look for a header by the name of “aBC” will
returns values for headers of names “AbC”, “ABC”, “abc”, and so on.
Implementations§
source§impl<'h> HeaderMap<'h>
impl<'h> HeaderMap<'h>
sourcepub fn new() -> HeaderMap<'h>
pub fn new() -> HeaderMap<'h>
Returns an empty header collection.
Example
use rocket::http::HeaderMap;
let map = HeaderMap::new();
sourcepub fn contains<N>(&self, name: N) -> boolwhere
N: AsRef<str>,
pub fn contains<N>(&self, name: N) -> boolwhere N: AsRef<str>,
Returns true if self
contains a header with the name name
.
Example
use rocket::http::{HeaderMap, ContentType};
let mut map = HeaderMap::new();
map.add(ContentType::HTML);
assert!(map.contains("Content-Type"));
assert!(!map.contains("Accepts"));
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of values stored in the map.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
assert_eq!(map.len(), 0);
map.add_raw("X-Custom", "value_1");
assert_eq!(map.len(), 1);
map.replace_raw("X-Custom", "value_2");
assert_eq!(map.len(), 1);
map.add_raw("X-Custom", "value_1");
assert_eq!(map.len(), 2);
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if there are no headers stored in the map. Otherwise
returns false
.
Example
use rocket::http::HeaderMap;
let map = HeaderMap::new();
assert!(map.is_empty());
sourcepub fn get(&self, name: &str) -> impl Iterator<Item = &str>
pub fn get(&self, name: &str) -> impl Iterator<Item = &str>
Returns an iterator over all of the values stored in self
for the
header with name name
. The headers are returned in FIFO order.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");
assert_eq!(map.len(), 2);
let mut values = map.get("X-Custom");
assert_eq!(values.next(), Some("value_1"));
assert_eq!(values.next(), Some("value_2"));
assert_eq!(values.next(), None);
sourcepub fn get_one<'a>(&'a self, name: &str) -> Option<&'a str>
pub fn get_one<'a>(&'a self, name: &str) -> Option<&'a str>
Returns the first value stored for the header with name name
if
there is one.
Examples
Retrieve the first value when one exists:
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");
assert_eq!(map.len(), 2);
let first_value = map.get_one("X-Custom");
assert_eq!(first_value, Some("value_1"));
Attempt to retrieve a value that doesn’t exist:
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
let first_value = map.get_one("X-Other");
assert_eq!(first_value, None);
sourcepub fn replace<'p, H>(&mut self, header: H) -> boolwhere
'p: 'h,
H: Into<Header<'p>>,
pub fn replace<'p, H>(&mut self, header: H) -> boolwhere 'p: 'h, H: Into<Header<'p>>,
Replace any header that matches the name of header.name
with header
.
If there is no such header in self
, add header
. If the matching
header had multiple values, all of the values are removed, and only the
value in header
will remain.
Example
Replace a header that doesn’t yet exist:
use rocket::http::{HeaderMap, ContentType};
let mut map = HeaderMap::new();
map.replace(ContentType::JSON);
assert!(map.get_one("Content-Type").is_some());
Replace a header that already exists:
use rocket::http::{HeaderMap, ContentType};
let mut map = HeaderMap::new();
map.replace(ContentType::JSON);
assert_eq!(map.get_one("Content-Type"), Some("application/json"));
map.replace(ContentType::GIF);
assert_eq!(map.get_one("Content-Type"), Some("image/gif"));
assert_eq!(map.len(), 1);
An example of case-insensitivity.
use rocket::http::{HeaderMap, Header, ContentType};
let mut map = HeaderMap::new();
map.replace(ContentType::JSON);
assert_eq!(map.get_one("Content-Type"), Some("application/json"));
map.replace(Header::new("CONTENT-type", "image/gif"));
assert_eq!(map.get_one("Content-Type"), Some("image/gif"));
assert_eq!(map.len(), 1);
sourcepub fn replace_raw<'a, 'b, N, V>(&mut self, name: N, value: V) -> boolwhere
'a: 'h,
'b: 'h,
N: Into<Cow<'a, str>>,
V: Into<Cow<'b, str>>,
pub fn replace_raw<'a, 'b, N, V>(&mut self, name: N, value: V) -> boolwhere 'a: 'h, 'b: 'h, N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>,
A convenience method to replace a header using a raw name and value.
Aliases replace(Header::new(name, value))
. Should be used rarely.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.replace_raw("X-Custom", "value_1");
assert_eq!(map.get_one("X-Custom"), Some("value_1"));
map.replace_raw("X-Custom", "value_2");
assert_eq!(map.get_one("X-Custom"), Some("value_2"));
assert_eq!(map.len(), 1);
sourcepub fn replace_all<'n, 'v, H>(
&mut self,
name: H,
values: Vec<Cow<'v, str>, Global>
)where
'v: 'h,
'n: 'h,
H: Into<Cow<'n, str>>,
pub fn replace_all<'n, 'v, H>( &mut self, name: H, values: Vec<Cow<'v, str>, Global> )where 'v: 'h, 'n: 'h, H: Into<Cow<'n, str>>,
Replaces all of the values for a header with name name
with values
.
This a low-level method and should rarely be used.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");
let vals: Vec<_> = map.get("X-Custom").map(|s| s.to_string()).collect();
assert_eq!(vals, vec!["value_1", "value_2"]);
map.replace_all("X-Custom", vec!["value_3".into(), "value_4".into()]);
let vals: Vec<_> = map.get("X-Custom").collect();
assert_eq!(vals, vec!["value_3", "value_4"]);
sourcepub fn add<'p, H>(&mut self, header: H)where
'p: 'h,
H: Into<Header<'p>>,
pub fn add<'p, H>(&mut self, header: H)where 'p: 'h, H: Into<Header<'p>>,
Adds header
into the map. If a header with header.name
was
previously added, that header will have one more value.
use rocket::http::{Cookie, HeaderMap};
let mut map = HeaderMap::new();
map.add(&Cookie::new("a", "b"));
assert_eq!(map.get("Set-Cookie").count(), 1);
map.add(&Cookie::new("c", "d"));
assert_eq!(map.get("Set-Cookie").count(), 2);
sourcepub fn add_raw<'a, 'b, N, V>(&mut self, name: N, value: V)where
'a: 'h,
'b: 'h,
N: Into<Cow<'a, str>>,
V: Into<Cow<'b, str>>,
pub fn add_raw<'a, 'b, N, V>(&mut self, name: N, value: V)where 'a: 'h, 'b: 'h, N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>,
A convenience method to add a header using a raw name and value.
Aliases add(Header::new(name, value))
. Should be used rarely.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
assert_eq!(map.get("X-Custom").count(), 1);
map.add_raw("X-Custom", "value_2");
let values: Vec<_> = map.get("X-Custom").collect();
assert_eq!(values, vec!["value_1", "value_2"]);
sourcepub fn add_all<'n, H>(
&mut self,
name: H,
values: &mut Vec<Cow<'h, str>, Global>
)where
'n: 'h,
H: Into<Cow<'n, str>>,
pub fn add_all<'n, H>( &mut self, name: H, values: &mut Vec<Cow<'h, str>, Global> )where 'n: 'h, H: Into<Cow<'n, str>>,
Adds all of the values to a header with name name
. This a low-level
method and should rarely be used. values
will be empty when this
method returns.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
let mut values = vec!["value_1".into(), "value_2".into()];
map.add_all("X-Custom", &mut values);
assert_eq!(map.get("X-Custom").count(), 2);
assert_eq!(values.len(), 0);
let mut values = vec!["value_3".into(), "value_4".into()];
map.add_all("X-Custom", &mut values);
assert_eq!(map.get("X-Custom").count(), 4);
assert_eq!(values.len(), 0);
let values: Vec<_> = map.get("X-Custom").collect();
assert_eq!(values, vec!["value_1", "value_2", "value_3", "value_4"]);
sourcepub fn remove(&mut self, name: &str)
pub fn remove(&mut self, name: &str)
Remove all of the values for header with name name
.
Example
use rocket::http::HeaderMap;
let mut map = HeaderMap::new();
map.add_raw("X-Custom", "value_1");
map.add_raw("X-Custom", "value_2");
map.add_raw("X-Other", "other");
assert_eq!(map.len(), 3);
map.remove("X-Custom");
assert_eq!(map.len(), 1);
sourcepub fn remove_all(&mut self) -> Vec<Header<'h>, Global>
pub fn remove_all(&mut self) -> Vec<Header<'h>, Global>
Removes all of the headers stored in this map and returns a vector containing them. Header names are returned in no specific order, but all values for a given header name are grouped together, and values are in FIFO order.
Example
use rocket::http::{HeaderMap, Header};
use std::collections::HashSet;
// The headers we'll be storing.
let all_headers = vec![
Header::new("X-Custom", "value_1"),
Header::new("X-Custom", "value_2"),
Header::new("X-Other", "other")
];
// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers.clone() {
map.add(header)
}
assert_eq!(map.len(), 3);
// Now remove them all, ensure the map is empty.
let removed_headers = map.remove_all();
assert!(map.is_empty());
// Create two sets: what we expect and got. Ensure they're equal.
let expected_set: HashSet<_> = all_headers.into_iter().collect();
let actual_set: HashSet<_> = removed_headers.into_iter().collect();
assert_eq!(expected_set, actual_set);
sourcepub fn iter(&self) -> impl Iterator<Item = Header<'_>>
pub fn iter(&self) -> impl Iterator<Item = Header<'_>>
Returns an iterator over all of the Header
s stored in the map. Header
names are returned in no specific order, but all values for a given
header name are grouped together, and values are in FIFO order.
Example
use rocket::http::{HeaderMap, Header};
// The headers we'll be storing.
let all_headers = vec![
Header::new("X-Custom", "value_1"),
Header::new("X-Other", "other"),
Header::new("X-Third", "third"),
];
// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers {
map.add(header)
}
// Ensure there are three headers via the iterator.
assert_eq!(map.iter().count(), 3);
// Actually iterate through them.
for header in map.iter() {
match header.name().as_str() {
"X-Custom" => assert_eq!(header.value(), "value_1"),
"X-Other" => assert_eq!(header.value(), "other"),
"X-Third" => assert_eq!(header.value(), "third"),
_ => unreachable!("there are only three headers")
}
}
sourcepub fn into_iter(self) -> impl Iterator<Item = Header<'h>>
pub fn into_iter(self) -> impl Iterator<Item = Header<'h>>
Consumes self
and returns an iterator over all of the Header
s stored
in the map. Header names are returned in no specific order, but all
values for a given header name are grouped together, and values are in
FIFO order.
Example
use rocket::http::{HeaderMap, Header};
// The headers we'll be storing.
let all_headers = vec![
Header::new("X-Custom", "value_1"),
Header::new("X-Other", "other"),
Header::new("X-Third", "third"),
];
// Create a map, store all of the headers.
let mut map = HeaderMap::new();
for header in all_headers {
map.add(header)
}
// Ensure there are three headers via the iterator.
assert_eq!(map.iter().count(), 3);
// Actually iterate through them.
for header in map.into_iter() {
match header.name().as_str() {
"X-Custom" => assert_eq!(header.value(), "value_1"),
"X-Other" => assert_eq!(header.value(), "other"),
"X-Third" => assert_eq!(header.value(), "third"),
_ => unreachable!("there are only three headers")
}
}
Trait Implementations§
source§impl<'h> PartialEq<HeaderMap<'h>> for HeaderMap<'h>
impl<'h> PartialEq<HeaderMap<'h>> for HeaderMap<'h>
impl<'h> StructuralPartialEq for HeaderMap<'h>
Auto Trait Implementations§
impl<'h> RefUnwindSafe for HeaderMap<'h>
impl<'h> Send for HeaderMap<'h>
impl<'h> Sync for HeaderMap<'h>
impl<'h> Unpin for HeaderMap<'h>
impl<'h> UnwindSafe for HeaderMap<'h>
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> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightYellow
.
Example
println!("{}", value.bright_yellow());
source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.bright_magenta());
source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlack
.
Example
println!("{}", value.on_bright_black());
source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightGreen
.
Example
println!("{}", value.on_bright_green());
source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightYellow
.
Example
println!("{}", value.on_bright_yellow());
source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlue
.
Example
println!("{}", value.on_bright_blue());
source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.on_bright_magenta());
source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightCyan
.
Example
println!("{}", value.on_bright_cyan());
source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightWhite
.
Example
println!("{}", value.on_bright_white());
source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute
value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
source§fn underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
Quirk
value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition
value
applies. Replaces any previous condition.
See the crate level docs for more details.
Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);