Struct `HeaderValue`

struct HeaderValue { ... }

Represents an HTTP header field value.

In practice, HTTP header field values are usually valid ASCII. However, the HTTP spec allows for a header value to contain opaque bytes as well. In this case, the header field value is not able to be represented as a string.

To handle this, the HeaderValue is useable as a type and can be compared with strings and implements Debug. A to_str fn is provided that returns an Err if the header value contains non visible ascii characters.

Implementations

`impl HeaderValue`

const fn from_static(src: &'static str) -> HeaderValue

Convert a static string to a HeaderValue.

This function will not perform any copying, however the string is checked to ensure that no invalid characters are present. Only visible ASCII characters (32-127) are permitted.

Panics

This function panics if the argument contains invalid header value characters.

Until Allow panicking in constants makes its way into stable, the panic message at compile-time is going to look cryptic, but should at least point at your header value:

error: any use of this value will cause an error
  --> http/src/header/value.rs:67:17
   |
67 |                 ([] as [u8; 0])[0]; // Invalid header value
   |                 ^^^^^^^^^^^^^^^^^^
   |                 |
   |                 index out of bounds: the length is 0 but the index is 0
   |                 inside `HeaderValue::from_static` at http/src/header/value.rs:67:17
   |                 inside `INVALID_HEADER` at src/main.rs:73:33
   |
  ::: src/main.rs:73:1
   |
73 | const INVALID_HEADER: HeaderValue = HeaderValue::from_static("жsome value");
   | ----------------------------------------------------------------------------

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_static("hello");
assert_eq!(val, "hello");

fn from_str(src: &str) -> Result<HeaderValue, InvalidHeaderValue>

Attempt to convert a string to a HeaderValue.

If the argument contains invalid header value characters, an error is returned. Only visible ASCII characters (32-127) are permitted. Use from_bytes to create a HeaderValue that includes opaque octets (128-255).

This function is intended to be replaced in the future by a TryFrom implementation once the trait is stabilized in std.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_str("hello").unwrap();
assert_eq!(val, "hello");

An invalid value

# use http::header::HeaderValue;
let val = HeaderValue::from_str("\n");
assert!(val.is_err());

fn from_name(name: HeaderName) -> HeaderValue

Converts a HeaderName into a HeaderValue

Since every valid HeaderName is a valid HeaderValue this is done infallibly.

Examples

# use http::header::{HeaderValue, HeaderName};
# use http::header::ACCEPT;
let val = HeaderValue::from_name(ACCEPT);
assert_eq!(val, HeaderValue::from_bytes(b"accept").unwrap());

fn from_bytes(src: &[u8]) -> Result<HeaderValue, InvalidHeaderValue>

Attempt to convert a byte slice to a HeaderValue.

If the argument contains invalid header value bytes, an error is returned. Only byte values between 32 and 255 (inclusive) are permitted, excluding byte 127 (DEL).

This function is intended to be replaced in the future by a TryFrom implementation once the trait is stabilized in std.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_bytes(b"hello\xfa").unwrap();
assert_eq!(val, &b"hello\xfa"[..]);

An invalid value

# use http::header::HeaderValue;
let val = HeaderValue::from_bytes(b"\n");
assert!(val.is_err());

fn from_maybe_shared<T>(src: T) -> Result<HeaderValue, InvalidHeaderValue> where T: AsRef<[u8]> + 'static

Attempt to convert a Bytes buffer to a HeaderValue.

This will try to prevent a copy if the type passed is the type used internally, and will copy the data if it is not.

unsafe fn from_maybe_shared_unchecked<T>(src: T) -> HeaderValue where T: AsRef<[u8]> + 'static

Convert a Bytes directly into a HeaderValue without validating.

This function does NOT validate that illegal bytes are not contained within the buffer.

Panics

In a debug build this will panic if src is not valid UTF-8.

Safety

src must contain valid UTF-8. In a release build it is undefined behaviour to call this with src that is not valid UTF-8.

fn to_str(self: &Self) -> Result<&str, ToStrError>

Yields a &str slice if the HeaderValue only contains visible ASCII chars.

This function will perform a scan of the header value, checking all the characters.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_static("hello");
assert_eq!(val.to_str().unwrap(), "hello");

fn len(self: &Self) -> usize

Returns the length of self.

This length is in bytes.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_static("hello");
assert_eq!(val.len(), 5);

fn is_empty(self: &Self) -> bool

Returns true if the HeaderValue has a length of zero bytes.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_static("");
assert!(val.is_empty());

let val = HeaderValue::from_static("hello");
assert!(!val.is_empty());

fn as_bytes(self: &Self) -> &[u8]

Converts a HeaderValue to a byte slice.

Examples

# use http::header::HeaderValue;
let val = HeaderValue::from_static("hello");
assert_eq!(val.as_bytes(), b"hello");

fn set_sensitive(self: &mut Self, val: bool)

Mark that the header value represents sensitive information.

Examples

# use http::header::HeaderValue;
let mut val = HeaderValue::from_static("my secret");

val.set_sensitive(true);
assert!(val.is_sensitive());

val.set_sensitive(false);
assert!(!val.is_sensitive());

fn is_sensitive(self: &Self) -> bool

Returns true if the value represents sensitive data.

Sensitive data could represent passwords or other data that should not be stored on disk or in memory. By marking header values as sensitive, components using this crate can be instructed to treat them with special care for security reasons. For example, caches can avoid storing sensitive values, and HPACK encoders used by HTTP/2.0 implementations can choose not to compress them.

Additionally, sensitive values will be masked by the Debug implementation of HeaderValue.

Note that sensitivity is not factored into equality or ordering.

Examples

# use http::header::HeaderValue;
let mut val = HeaderValue::from_static("my secret");

val.set_sensitive(true);
assert!(val.is_sensitive());

val.set_sensitive(false);
assert!(!val.is_sensitive());

`impl AsRef for HeaderValue`

fn as_ref(self: &Self) -> &[u8]

`impl Clone for HeaderValue`

fn clone(self: &Self) -> HeaderValue

`impl Debug for HeaderValue`

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

`impl Eq for HeaderValue`

`impl Freeze for HeaderValue`

`impl From for HeaderValue`

fn from(num: u16) -> HeaderValue

`impl From for HeaderValue`

fn from(num: i64) -> HeaderValue

`impl From for HeaderValue`

fn from(num: i32) -> HeaderValue

`impl From for HeaderValue`

fn from(num: i16) -> HeaderValue

`impl From for HeaderValue`

fn from(h: HeaderName) -> HeaderValue

`impl From for HeaderValue`

fn from(num: usize) -> HeaderValue

`impl From for HeaderValue`

fn from(num: u64) -> HeaderValue

`impl From for HeaderValue`

fn from(num: u32) -> HeaderValue

`impl From for HeaderValue`

fn from(num: isize) -> HeaderValue

`impl FromStr for HeaderValue`

fn from_str(s: &str) -> Result<HeaderValue, <Self as >::Err>

`impl Hash for HeaderValue`

fn hash<H: Hasher>(self: &Self, state: &mut H)

`impl Ord for HeaderValue`

fn cmp(self: &Self, other: &Self) -> cmp::Ordering

`impl PartialEq for HeaderValue`

fn eq(self: &Self, other: &str) -> bool

`impl PartialEq for HeaderValue`

fn eq(self: &Self, other: &String) -> bool

`impl PartialEq for HeaderValue`

fn eq(self: &Self, other: &[u8]) -> bool

`impl PartialEq for HeaderValue`

fn eq(self: &Self, other: &HeaderValue) -> bool

`impl PartialOrd for HeaderValue`

fn partial_cmp(self: &Self, other: &[u8]) -> Option<cmp::Ordering>

`impl PartialOrd for HeaderValue`

fn partial_cmp(self: &Self, other: &HeaderValue) -> Option<cmp::Ordering>

`impl PartialOrd for HeaderValue`

fn partial_cmp(self: &Self, other: &String) -> Option<cmp::Ordering>

`impl PartialOrd for HeaderValue`

fn partial_cmp(self: &Self, other: &str) -> Option<cmp::Ordering>

`impl RefUnwindSafe for HeaderValue`

`impl Send for HeaderValue`

`impl Sync for HeaderValue`

`impl TryFrom for HeaderValue`

fn try_from(vec: Vec<u8>) -> Result<Self, <Self as >::Error>

`impl TryFrom for HeaderValue`

fn try_from(t: String) -> Result<Self, <Self as >::Error>

`impl Unpin for HeaderValue`

`impl UnwindSafe for HeaderValue`

`impl<'a> From for HeaderValue`

fn from(t: &'a HeaderValue) -> Self

`impl<'a> TryFrom for HeaderValue`

fn try_from(s: &'a String) -> Result<Self, <Self as >::Error>

`impl<'a> TryFrom for HeaderValue`

fn try_from(t: &'a str) -> Result<Self, <Self as >::Error>

`impl<'a> TryFrom for HeaderValue`

fn try_from(t: &'a [u8]) -> Result<Self, <Self as >::Error>

`impl<'a, T: ?Sized> PartialEq for HeaderValue`

fn eq(self: &Self, other: &&'a T) -> bool

`impl<'a, T: ?Sized> PartialOrd for HeaderValue`

fn partial_cmp(self: &Self, other: &&'a T) -> Option<cmp::Ordering>

`impl<T> Any for HeaderValue`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for HeaderValue`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for HeaderValue`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for HeaderValue`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for HeaderValue`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for HeaderValue`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for HeaderValue`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for HeaderValue`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for HeaderValue`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>