Struct Peek 

pub struct Peek<'mem, 'facet> { /* private fields */ }

Available on crate feature reflect only.

A read-only view into a value with runtime type information.

Peek provides reflection capabilities for reading values at runtime. If the value is a struct, you can read its fields; if it’s an enum, you can determine which variant is selected; if it’s a scalar, you can extract a concrete value.

Lifetime Parameters

• 'mem: The memory lifetime - how long the underlying data is valid
• 'facet: The type’s lifetime parameter (for types like &'a str)

Variance and Soundness

Peek is invariant over 'facet. This is required for soundness: if Peek were covariant, it would be possible to launder lifetimes through reflection, leading to use-after-free bugs with types like fn(&'a str). See issue #1168.

The underlying type’s variance is tracked in Shape::variance, which can be used for future variance-aware APIs.

Implementations

impl<'mem, 'facet> Peek<'mem, 'facet>

pub fn new<T>(t: &'mem T) -> Peek<'mem, 'facet>

where T: Facet<'facet> + ?Sized,

Returns a read-only view over a T value.

pub unsafe fn unchecked_new( data: PtrConst, shape: &'static Shape, ) -> Peek<'mem, 'facet>

Returns a read-only view over a value (given its shape), trusting you that those two match.

Safety

This function is unsafe because it doesn’t check if the provided data and shape are compatible. The caller must ensure that the data is valid for the given shape.

pub fn variance(&self) -> Variance

Returns the computed variance of the underlying type.

This walks the type’s fields to determine if the type is covariant, contravariant, or invariant over its lifetime parameter.

pub fn shrink_lifetime<'shorter>(self) -> Peek<'mem, 'shorter>

where 'facet: 'shorter,

Shrinks the 'facet lifetime parameter.

This is safe for covariant types: if data is valid for 'static, it’s also valid for any shorter lifetime 'shorter.

Panics

Panics if the type is not covariant (i.e., if shrinking would be unsound).

pub fn try_shrink_lifetime<'shorter>(self) -> Option<Peek<'mem, 'shorter>>

where 'facet: 'shorter,

Tries to shrink the 'facet lifetime parameter.

Returns Some if the type is covariant (shrinking is safe), or None if the type is invariant or contravariant.

pub fn grow_lifetime<'longer>(self) -> Peek<'mem, 'longer>

where 'longer: 'facet,

Grows the 'facet lifetime parameter.

This is safe for contravariant types: if a function accepts 'short, it can also accept 'longer (a longer lifetime is more restrictive).

Panics

Panics if the type is not contravariant (i.e., if growing would be unsound).

pub fn try_grow_lifetime<'longer>(self) -> Option<Peek<'mem, 'longer>>

where 'longer: 'facet,

Tries to grow the 'facet lifetime parameter.

Returns Some if the type is contravariant (growing is safe), or None if the type is invariant or covariant.

pub fn vtable(&self) -> VTableErased

Returns the vtable

pub fn id(&self) -> ValueId

Returns a unique identifier for this value, usable for cycle detection

pub fn ptr_eq(&self, other: &Peek<'_, '_>) -> bool

Returns true if the two values are pointer-equal

pub fn partial_eq(&self, other: &Peek<'_, '_>) -> Result<bool, ReflectError>

Returns true if this scalar is equal to the other scalar

Returns

false if equality comparison is not supported for this scalar type

pub fn partial_cmp( &self, other: &Peek<'_, '_>, ) -> Result<Option<Ordering>, ReflectError>

Compares this scalar with another and returns their ordering

Returns

None if comparison is not supported for this scalar type

pub fn hash(&self, hasher: &mut dyn Hasher) -> Result<(), ReflectError>

Hashes this scalar using the vtable hash function.

Returns

Err if hashing is not supported for this scalar type, Ok otherwise

pub fn structural_hash<H>(&self, hasher: &mut H)

where H: Hasher,

Computes a structural hash of this value.

Unlike hash, this method recursively traverses the structure and hashes each component, making it work for types that don’t implement Hash.

For scalars with a vtable hash function, it uses that. For compound types (structs, enums, lists, etc.), it recursively hashes the structure.

This is useful for Merkle-tree style hashing where you want to compare subtrees for equality based on their structural content.

pub fn type_name( &self, f: &mut Formatter<'_>, opts: TypeNameOpts, ) -> Result<(), Error>

Returns the type name of this scalar

Arguments

• f - A mutable reference to a core::fmt::Formatter
• opts - The TypeNameOpts to use for formatting

Returns

The result of the type name formatting

pub const fn shape(&self) -> &'static Shape

Returns the shape

pub const fn data(&self) -> PtrConst

Returns the data

pub fn scalar_type(&self) -> Option<ScalarType>

Get the scalar type if set.

pub fn get<T>(&self) -> Result<&'mem T, ReflectError>

where T: Facet<'facet> + ?Sized,

Read the value from memory into a Rust value.

Panics

Panics if the shape doesn’t match the type T.

pub fn as_str(&self) -> Option<&'mem str>

Try to get the value as a string if it’s a string type Returns None if the value is not a string or couldn’t be extracted

pub fn as_bytes(&self) -> Option<&'mem [u8]>

Try to get the value as a byte slice if it’s a &u8 type Returns None if the value is not a byte slice or couldn’t be extracted

pub fn into_struct(self) -> Result<PeekStruct<'mem, 'facet>, ReflectError>

Tries to identify this value as a struct

pub fn into_enum(self) -> Result<PeekEnum<'mem, 'facet>, ReflectError>

Tries to identify this value as an enum

pub fn into_map(self) -> Result<PeekMap<'mem, 'facet>, ReflectError>

Tries to identify this value as a map

pub fn into_set(self) -> Result<PeekSet<'mem, 'facet>, ReflectError>

Tries to identify this value as a set

pub fn into_list(self) -> Result<PeekList<'mem, 'facet>, ReflectError>

Tries to identify this value as a list

pub fn into_ndarray(self) -> Result<PeekNdArray<'mem, 'facet>, ReflectError>

Tries to identify this value as a ndarray

pub fn into_list_like(self) -> Result<PeekListLike<'mem, 'facet>, ReflectError>

Tries to identify this value as a list, array or slice

pub fn into_pointer(self) -> Result<PeekPointer<'mem, 'facet>, ReflectError>

Tries to identify this value as a pointer

pub fn into_option(self) -> Result<PeekOption<'mem, 'facet>, ReflectError>

Tries to identify this value as an option

pub fn into_result(self) -> Result<PeekResult<'mem, 'facet>, ReflectError>

Tries to identify this value as a result

pub fn into_tuple(self) -> Result<PeekTuple<'mem, 'facet>, ReflectError>

Tries to identify this value as a tuple

pub fn into_dynamic_value( self, ) -> Result<PeekDynamicValue<'mem, 'facet>, ReflectError>

Tries to identify this value as a dynamic value (like facet_value::Value)

pub fn innermost_peek(self) -> Peek<'mem, 'facet>

Tries to return the innermost value — useful for serialization. For example, we serialize a NonZero<u8> the same as a u8. Similarly, we serialize a Utf8PathBuf the same as a `String.

Returns a Peek to the innermost value, unwrapping transparent wrappers recursively. For example, this will peel through newtype wrappers or smart pointers that have an inner.

pub fn custom_serialization( &self, field: Field, ) -> Result<OwnedPeek<'mem>, ReflectError>

Available on crate feature alloc only.

Performs custom serialization of the current peek using the provided field’s metadata.

Returns an OwnedPeek that points to the final type that should be serialized in place of the current peek.

pub fn custom_serialization_from_shape( &self, ) -> Result<Option<OwnedPeek<'mem>>, ReflectError>

Available on crate feature alloc only.

Returns an OwnedPeek using the shape’s container-level proxy for serialization.

This is used when a type has #[facet(proxy = ProxyType)] at the container level. Unlike field-level proxies which are checked via custom_serialization(field), this method checks the Shape itself for a proxy definition.

Returns None if the shape has no container-level proxy.

Trait Implementations

impl<'mem, 'facet> Clone for Peek<'mem, 'facet>

fn clone(&self) -> Peek<'mem, 'facet>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'mem, 'facet> Debug for Peek<'mem, 'facet>

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

Formats the value using the given formatter.

impl<'mem, 'facet> Display for Peek<'mem, 'facet>

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

Formats the value using the given formatter.

impl<'mem, 'facet> Hash for Peek<'mem, 'facet>

fn hash<H>(&self, hasher: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'mem, 'facet> PartialEq for Peek<'mem, 'facet>

fn eq(&self, other: &Peek<'mem, 'facet>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'mem, 'facet> PartialOrd for Peek<'mem, 'facet>

fn partial_cmp(&self, other: &Peek<'mem, 'facet>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'mem, 'facet> Copy for Peek<'mem, 'facet>