Struct Peek 

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

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 with respect to '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: Facet<'facet> + ?Sized>(t: &'mem T) -> Self

Returns a read-only view over a T value.

pub unsafe fn unchecked_new(data: PtrConst, shape: &'static Shape) -> Self

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 with respect to 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 and bivariant types: if data is valid for 'static, it’s also valid for any shorter lifetime 'shorter.

From the Rust Reference:

• Covariant types can shrink lifetimes ('static → 'a)
• Bivariant types can go either direction (no lifetime constraints)

Panics

Panics if the type cannot shrink lifetimes (i.e., if it’s contravariant or invariant).

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 can shrink lifetimes (covariant or bivariant), or None if the type is invariant or contravariant.

See Variance::can_shrink for details.

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

where 'longer: 'facet,

Grows the 'facet lifetime parameter.

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

From the Rust Reference:

• Contravariant types can grow lifetimes ('a → 'static)
• Bivariant types can go either direction (no lifetime constraints)

Panics

Panics if the type cannot grow lifetimes (i.e., if it’s covariant or invariant).

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 can grow lifetimes (contravariant or bivariant), or None if the type is invariant or covariant.

See Variance::can_grow for details.

pub const 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: Hasher>(&self, hasher: &mut H)

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

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: Facet<'facet> + ?Sized>(&self) -> Result<&'mem T, ReflectError>

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 const fn into_struct(self) -> Result<PeekStruct<'mem, 'facet>, ReflectError>

Tries to identify this value as a struct

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

Tries to identify this value as an enum

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

Tries to identify this value as a map

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

Tries to identify this value as a set

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

Tries to identify this value as a list

pub const 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 const fn into_pointer( self, ) -> Result<PeekPointer<'mem, 'facet>, ReflectError>

Tries to identify this value as a pointer

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

Tries to identify this value as an option

pub const 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 const 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) -> Self

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>

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_with_proxy( &self, proxy_def: &'static ProxyDef, ) -> Result<OwnedPeek<'mem>, ReflectError>

Performs custom serialization using a specific proxy definition.

This is a lower-level method that takes a ProxyDef directly, useful when the caller has already resolved which proxy to use (e.g., via effective_proxy()).

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

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.

pub fn custom_serialization_from_shape_with_format( &self, format_namespace: Option<&str>, ) -> Result<Option<OwnedPeek<'mem>>, ReflectError>

Returns an OwnedPeek using the shape’s container-level proxy for serialization, with support for format-specific proxies.

If format_namespace is provided (e.g., Some("xml")), looks for a format-specific proxy first, falling back to the format-agnostic proxy.

Returns None if no applicable proxy is found.

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

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

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

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: &Self) -> 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: &Self) -> 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>