Struct tonic::metadata::MetadataValue

source ·

pub struct MetadataValue<VE: ValueEncoding> { /* private fields */ }

Expand description

Represents a custom metadata field value.

MetadataValue is used as the MetadataMap value.

Implementations§

source §

impl<VE: ValueEncoding> MetadataValue<VE>

source

pub fn from_static(src: &'static str) -> Self

Convert a static string to a MetadataValue.

This function will not perform any copying, however the string is checked to ensure that no invalid characters are present.

For Ascii values, only visible ASCII characters (32-127) are permitted. For Binary values, the string must be valid base64.

§Panics

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

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val, "hello");

let val = BinaryMetadataValue::from_static("SGVsbG8hIQ==");
assert_eq!(val, "Hello!!");

source

pub unsafe fn from_shared_unchecked(src: Bytes) -> Self

Convert a Bytes directly into a MetadataValue without validating. For MetadataValue<Binary> the provided parameter must be base64 encoded without padding bytes at the end.

§Safety

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

source

pub fn is_empty(&self) -> bool

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

§Examples

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

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

source

pub fn to_bytes(&self) -> Result<Bytes, InvalidMetadataValueBytes>

Converts a MetadataValue to a Bytes buffer. This method cannot fail for Ascii values. For Ascii values, as_bytes is more convenient to use.

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val.to_bytes().unwrap().as_ref(), b"hello");

let val = BinaryMetadataValue::from_bytes(b"hello");
assert_eq!(val.to_bytes().unwrap().as_ref(), b"hello");

source

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

Mark that the metadata value represents sensitive information.

§Examples

let mut val = AsciiMetadataValue::from_static("my secret");

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

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

source

pub fn is_sensitive(&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. This setting can be used by components like caches to avoid storing the value. HPACK encoders must set the metadata field to never index when is_sensitive returns true.

Note that sensitivity is not factored into equality or ordering.

§Examples

let mut val = AsciiMetadataValue::from_static("my secret");

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

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

source

pub fn as_encoded_bytes(&self) -> &[u8] ⓘ

Converts a MetadataValue to a byte slice. For Binary values, the return value is base64 encoded.

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val.as_encoded_bytes(), b"hello");

let val = BinaryMetadataValue::from_bytes(b"Hello!");
assert_eq!(val.as_encoded_bytes(), b"SGVsbG8h");

source §

impl MetadataValue<Ascii>

source

pub fn from_key<KeyVE: ValueEncoding>(key: MetadataKey<KeyVE>) -> Self

Converts a MetadataKey into a MetadataValue<Ascii>.

Since every valid MetadataKey is a valid MetadataValue this is done infallibly.

§Examples

let val = AsciiMetadataValue::from_key::<Ascii>("accept".parse().unwrap());
assert_eq!(val, AsciiMetadataValue::try_from(b"accept").unwrap());

source

pub fn len(&self) -> usize

Returns the length of self, in bytes.

This method is not available for MetadataValue<Binary> because that cannot be implemented in constant time, which most people would probably expect. To get the length of MetadataValue<Binary>, convert it to a Bytes value and measure its length.

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val.len(), 5);

source

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

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

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

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val.to_str().unwrap(), "hello");

source

pub fn as_bytes(&self) -> &[u8] ⓘ

Converts a MetadataValue to a byte slice. For Binary values, use to_bytes.

§Examples

let val = AsciiMetadataValue::from_static("hello");
assert_eq!(val.as_bytes(), b"hello");

source §

impl MetadataValue<Binary>

source

pub fn from_bytes(src: &[u8]) -> Self

Convert a byte slice to a MetadataValue<Binary>.

§Examples

let val = BinaryMetadataValue::from_bytes(b"hello\xfa");
assert_eq!(val, &b"hello\xfa"[..]);

Trait Implementations§

source §

impl<VE: ValueEncoding> AsRef<[u8]> for MetadataValue<VE>

source §

fn as_ref(&self) -> &[u8] ⓘ

Converts this type into a shared reference of the (usually inferred) input type.

source §

impl<VE: Clone + ValueEncoding> Clone for MetadataValue<VE>

source §

fn clone(&self) -> MetadataValue<VE>

Returns a copy of the value. Read more

1.0.0 · source§

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

Performs copy-assignment from source. Read more

source §

impl<VE: ValueEncoding> Debug for MetadataValue<VE>

source §

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

Formats the value using the given formatter. Read more

source §