Struct CovariantPeek 

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

Available on crate feature reflect only.

A covariant wrapper around Peek for types that are covariant over their lifetime parameter.

Unlike Peek, which is invariant over 'facet for soundness reasons, CovariantPeek is covariant over 'facet. This means a CovariantPeek<'mem, 'static> can be used where a CovariantPeek<'mem, 'a> is expected.

When to Use

Use CovariantPeek when you need to:

• Store multiple Peek values with different lifetimes in a single collection
• Pass Peek values to functions expecting shorter lifetimes
• Build data structures that wrap Peek without forcing invariance on the wrapper

Safety

CovariantPeek can only be constructed from types that are actually covariant. The constructor verifies this at runtime by checking Shape::computed_variance. This ensures that lifetime shrinking is always safe.

Example

use facet::Facet;
use facet_reflect::{Peek, CovariantPeek};

#[derive(Facet)]
struct Data<'a> {
    value: &'a str,
}

// Data<'a> is covariant in 'a because &'a str is covariant
let data = Data { value: "hello" };
let peek: Peek<'_, 'static> = Peek::new(&data);

// Convert to CovariantPeek - this verifies covariance
let covariant = CovariantPeek::new(peek).expect("Data is covariant");

// Now we can use it where shorter lifetimes are expected
fn use_shorter<'a>(p: CovariantPeek<'_, 'a>) {
    let _ = p;
}
use_shorter(covariant);

Implementations

impl<'mem, 'facet> CovariantPeek<'mem, 'facet>

pub fn new(peek: Peek<'mem, 'facet>) -> Option<CovariantPeek<'mem, 'facet>>

Creates a new CovariantPeek from a Peek, verifying that the underlying type is covariant.

Returns None if the type is not covariant (i.e., it’s contravariant or invariant).

Example

use facet::Facet;
use facet_reflect::{Peek, CovariantPeek};

// i32 has no lifetime parameters, so it's covariant
let value = 42i32;
let peek = Peek::new(&value);
let covariant = CovariantPeek::new(peek);
assert!(covariant.is_some());

pub fn new_unchecked(peek: Peek<'mem, 'facet>) -> CovariantPeek<'mem, 'facet>

Creates a new CovariantPeek from a Peek, panicking if the type is not covariant.

Panics

Panics if the underlying type is not covariant.

Example

use facet::Facet;
use facet_reflect::{Peek, CovariantPeek};

let value = "hello";
let peek = Peek::new(&value);
let covariant = CovariantPeek::new_unchecked(peek); // Will succeed

pub fn from_ref<T>(t: &'mem T) -> Option<CovariantPeek<'mem, 'facet>>

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

Creates a CovariantPeek directly from a covariant Facet type.

Returns None if the type is not covariant.

Example

use facet::Facet;
use facet_reflect::CovariantPeek;

let value = 42i32;
let covariant = CovariantPeek::from_ref(&value);
assert!(covariant.is_some());

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

Returns the underlying Peek.

Note that the returned Peek is invariant, so you cannot use it to shrink lifetimes directly. Use CovariantPeek for lifetime flexibility.

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

Returns the shape of the underlying value.

pub const fn data(&self) -> PtrConst

Returns the data pointer.

Methods from Deref<Target = Peek<'mem, 'facet>>

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 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 fn shape(&self) -> &'static Shape

Returns the shape

pub 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 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 CovariantPeek<'mem, 'facet>

fn clone(&self) -> CovariantPeek<'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 CovariantPeek<'mem, 'facet>

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

Formats the value using the given formatter.

impl<'mem, 'facet> Deref for CovariantPeek<'mem, 'facet>

type Target = Peek<'mem, 'facet>

The resulting type after dereferencing.

fn deref(&self) -> &<CovariantPeek<'mem, 'facet> as Deref>::Target

Dereferences the value.

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

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

Formats the value using the given formatter.

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