Struct Poke 

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

A mutable view into a value with runtime type information.

Poke provides reflection capabilities for mutating values at runtime. It is the mutable counterpart to Peek.

Wholesale Replacement vs Field Mutation

Poke can be created for any type. Replacing a value wholesale with Poke::set is always safe - it just drops the old value and writes the new one.

However, mutating individual struct fields via PokeStruct::set_field requires the struct to be marked as POD (#[facet(pod)]). This is because field mutation could violate struct-level invariants.

Lifetime Parameters

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

Example

// Wholesale replacement works on any type
let mut s = String::from("hello");
let mut poke = Poke::new(&mut s);
poke.set(String::from("world")).unwrap();

// Field mutation requires #[facet(pod)]
#[derive(Facet)]
#[facet(pod)]
struct Point { x: i32, y: i32 }

let mut point = Point { x: 1, y: 2 };
let mut poke = Poke::new(&mut point);
poke.into_struct().unwrap().set_field_by_name("x", 10i32).unwrap();
assert_eq!(point.x, 10);

Implementations

impl<'mem, 'facet> Poke<'mem, 'facet>

pub fn new<T: Facet<'facet>>(t: &'mem mut T) -> Self

Creates a mutable view over a T value.

This always succeeds - wholesale replacement via Poke::set is safe for any type. The POD check happens when you try to mutate individual struct fields.

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

Creates a mutable view from raw parts without any validation.

Safety

• data must point to a valid, initialized value of the type described by shape
• data must be valid for the lifetime 'mem

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

Returns the shape of the value.

pub const fn data(&self) -> PtrConst

Returns a const pointer to the underlying data.

pub const fn data_mut(&mut self) -> PtrMut

Returns a mutable pointer to the underlying data.

pub fn variance(&self) -> Variance

Returns the computed variance of the underlying type.

pub fn try_reborrow<'shorter>(&mut self) -> Option<Poke<'_, 'shorter>>

where 'facet: 'shorter,

Attempts to reborrow this mutable view as an owned Poke.

This is useful when only &mut Poke is available (e.g. through DerefMut) but an API requires ownership of Poke.

Returns Some if the underlying type can shrink the 'facet lifetime (covariant or bivariant), or None otherwise.

pub const fn is_struct(&self) -> bool

Returns true if this value is a struct.

pub const fn is_enum(&self) -> bool

Returns true if this value is an enum.

pub const fn is_scalar(&self) -> bool

Returns true if this value is a scalar (primitive type).

pub const fn is_tuple(&self) -> bool

Returns true if this value is a tuple (anonymous (A, B, ...)).

Note: tuple structs (named struct Foo(A, B);) report false here; they match is_struct.

pub const fn is_list(&self) -> bool

Returns true if this value is a list (variable-length, homogeneous, e.g. Vec<T>).

pub const fn is_array(&self) -> bool

Returns true if this value is a fixed-size array (e.g. [T; N]).

pub const fn is_slice(&self) -> bool

Returns true if this value is a slice (e.g. [T]).

pub const fn is_list_like(&self) -> bool

Returns true if this value is a list, array, or slice (the set accepted by into_list_like).

pub const fn is_map(&self) -> bool

Returns true if this value is a map.

pub const fn is_set(&self) -> bool

Returns true if this value is a set.

pub const fn is_option(&self) -> bool

Returns true if this value is an option.

pub const fn is_result(&self) -> bool

Returns true if this value is a result.

pub const fn is_pointer(&self) -> bool

Returns true if this value is a (smart) pointer.

pub const fn is_ndarray(&self) -> bool

Returns true if this value is an n-dimensional array.

pub const fn is_dynamic_value(&self) -> bool

Returns true if this value is a dynamic value (e.g. facet_value::Value — runtime-kind-dispatched).

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

Converts this into a PokeStruct if the value is a struct.

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

Converts this into a PokeEnum if the value is an enum.

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

Converts this into a PokeList if the value is a list.

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

Converts this into a PokeListLike if the value is a list, array, or slice.

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

Converts this into a PokeMap if the value is a map.

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

Converts this into a PokeSet if the value is a set.

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

Converts this into a PokeOption if the value is an option.

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

Converts this into a PokeResult if the value is a result.

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

Converts this into a PokeTuple if the value is a tuple (or tuple struct).

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

Converts this into a PokePointer if the value is a pointer.

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

Converts this into a PokeNdArray if the value is an n-dimensional array.

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

Converts this into a PokeDynamicValue if the value is a dynamic value.

pub fn get<T: Facet<'facet>>(&self) -> Result<&T, ReflectError>

Gets a reference to the underlying value.

Returns an error if the shape doesn’t match T.

pub fn get_mut<T: Facet<'facet>>(&mut self) -> Result<&mut T, ReflectError>

Gets a mutable reference to the underlying value.

Returns an error if the shape doesn’t match T.

pub fn set<T: Facet<'facet>>(&mut self, value: T) -> Result<(), ReflectError>

Sets the value to a new value.

This replaces the entire value. The new value must have the same shape.

pub fn as_peek(&self) -> Peek<'_, 'facet>

Borrows this Poke as a read-only Peek.

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

Consumes this Poke, returning a read-only Peek with the same 'mem lifetime.

pub fn at_path_mut( self, path: &Path, ) -> Result<Poke<'mem, 'facet>, PathAccessError>

Navigate to a nested value by following a Path, returning a mutable view.

Each PathStep in the path is applied in order, descending into structs, enums, and lists. If any step cannot be applied, a PathAccessError is returned with the step index and context.

Supported steps

• Field — struct fields and enum variant fields (after Variant)
• Variant — verify enum variant matches, then allow Field access
• Index — list/array element access
• OptionSome — navigate into Some(T) or return OptionIsNone

MapKey, MapValue, Deref, Inner, and Proxy are currently not supported for mutable access and return PathAccessError::MissingTarget.

Errors

Returns PathAccessError if:

• The path’s root shape doesn’t match this value’s shape
• A step kind doesn’t apply to the current shape
• A field/list index is out of bounds
• An enum variant doesn’t match the runtime variant

Trait Implementations

impl Debug for Poke<'_, '_>

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

Formats the value using the given formatter.