Struct Partial 

pub struct Partial<'facet, const BORROW: bool = true> { /* private fields */ }

A type-erased, heap-allocated, partially-initialized value.

Partial keeps track of the state of initialiation of the underlying value: if we’re building struct S { a: u32, b: String }, we may have initialized a, or b, or both, or neither.

Partial allows navigating down nested structs and initializing them progressively: Partial::begin_field pushes a frame onto the stack, which then has to be initialized, and popped off with Partial::end.

If Partial::end is called but the current frame isn’t fully initialized, an error is returned: in other words, if you navigate down to a field, you have to fully initialize it one go. You can’t go back up and back down to it again.

Implementations

impl<'facet> Partial<'facet, true>

Allocate a Partial that can borrow from input with lifetime ’facet. This is the default mode - use this when deserializing from a buffer that outlives the result.

pub fn alloc<T>() -> Result<Self, ReflectError>

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

Allocates a new Partial instance on the heap, with the given shape and type.

This creates a borrowing Partial that can hold references with lifetime ’facet.

pub fn alloc_shape(shape: &'static Shape) -> Result<Self, ReflectError>

Allocates a new Partial instance on the heap, with the given shape.

This creates a borrowing Partial that can hold references with lifetime ’facet.

impl Partial<'static, false>

Allocate a Partial that cannot borrow - all data must be owned. Use this when deserializing from a temporary buffer (e.g., HTTP request body).

pub fn alloc_owned<T>() -> Result<Self, ReflectError>

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

Allocates a new Partial instance on the heap, with the given shape and type.

This creates an owned Partial that cannot hold borrowed references. Use this when the input buffer is temporary and won’t outlive the result.

pub fn alloc_shape_owned(shape: &'static Shape) -> Result<Self, ReflectError>

Allocates a new Partial instance on the heap, with the given shape.

This creates an owned Partial that cannot hold borrowed references.

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn build(self) -> Result<HeapValue<'facet, BORROW>, ReflectError>

Builds the value, consuming the Partial.

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn selected_variant(&self) -> Option<Variant>

Get the currently selected variant for an enum

pub fn find_variant( &self, variant_name: &str, ) -> Option<(usize, &'static Variant)>

Find a variant by name in the current enum

pub fn select_nth_variant(self, index: usize) -> Result<Self, ReflectError>

Assuming the current frame is an enum, this selects a variant by index (0-based, in declaration order).

For example:

enum E { A, B, C }

Calling select_nth_variant(2) would select variant C.

This will return an error if the current frame is anything other than fully-uninitialized. In other words, it’s not possible to “switch to a different variant” once you’ve selected one.

This does not push a frame on the stack.

pub fn select_variant_named( self, variant_name: &str, ) -> Result<Self, ReflectError>

Pushes a variant for enum initialization by name

See Self::select_nth_variant for more notes.

pub fn select_variant(self, discriminant: i64) -> Result<Self, ReflectError>

Selects a given enum variant by discriminant. If none of the variants of the frame’s enum have that discriminant, this returns an error.

See Self::select_nth_variant for more notes.

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn field_index(&self, field_name: &str) -> Option<usize>

Find the index of a field by name in the current struct

If the current frame isn’t a struct or an enum (with a selected variant) then this returns None for sure.

pub fn is_field_set(&self, index: usize) -> Result<bool, ReflectError>

Check if a struct field at the given index has been set

pub fn begin_field(self, field_name: &str) -> Result<Self, ReflectError>

Selects a field (by name) of a struct or enum data.

For enums, the variant needs to be selected first, see Self::select_nth_variant and friends.

pub fn begin_nth_field(self, idx: usize) -> Result<Self, ReflectError>

Begins the nth field of a struct, enum variant, or array, by index.

On success, this pushes a new frame which must be ended with a call to Partial::end

pub fn set_nth_field_to_default(self, idx: usize) -> Result<Self, ReflectError>

Sets the given field to its default value, preferring:

• A default = some_fn() function
• The field’s Default implementation if any

But without going all the way up to the parent struct’s Default impl.

Errors out if idx is out of bound, if the field has no default method or Default impl.

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_list(self) -> Result<Self, ReflectError>

Initializes a list (Vec, etc.) if it hasn’t been initialized before. This is a prerequisite to begin_push_item/set/end or the shorthand push.

begin_list does not clear the list if it was previously initialized. begin_list does not push a new frame to the stack, and thus does not require end to be called afterwards.

pub fn begin_array(self) -> Result<Self, ReflectError>

Transitions the frame to Array tracker state.

This is used to prepare a fixed-size array for element initialization. Unlike begin_list, this does not initialize any runtime data - arrays are stored inline and don’t need a vtable call.

This method is particularly important for zero-length arrays like [u8; 0], which have no elements to initialize but still need their tracker state to be set correctly for require_full_initialization to pass.

begin_array does not push a new frame to the stack.

pub fn begin_list_item(self) -> Result<Self, ReflectError>

Pushes an element to the list The element should be set using set() or similar methods, then pop() to complete

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_map(self) -> Result<Self, ReflectError>

Begins a map initialization operation

This initializes the map with default capacity and allows inserting key-value pairs It does not push a new frame onto the stack.

For Def::DynamicValue types, this initializes as an object instead of a map.

pub fn begin_key(self) -> Result<Self, ReflectError>

Pushes a frame for the map key. After that, set() should be called (or the key should be initialized somehow) and end() should be called to pop the frame.

pub fn begin_value(self) -> Result<Self, ReflectError>

Pushes a frame for the map value Must be called after the key has been set and popped

pub fn begin_object_entry(self, key: &str) -> Result<Self, ReflectError>

Begins an object entry for a DynamicValue object.

This is a simpler API than begin_key/begin_value for DynamicValue objects, where keys are always strings. The key is stored and a frame is pushed for the value. After setting the value and calling end(), the key-value pair will be inserted into the object.

For Def::Map types, use begin_key() / begin_value() instead.

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn is_active(&self) -> bool

Returns true if the Partial is in an active state (not built or poisoned).

After build() succeeds or after an error causes poisoning, the Partial becomes inactive and most operations will fail.

pub fn frame_count(&self) -> usize

Returns the current frame count (depth of nesting)

The initial frame count is 1 — begin_field would push a new frame, bringing it to 2, then end would bring it back to 1.

This is an implementation detail of Partial, kinda, but deserializers might use this for debug assertions, to make sure the state is what they think it is.

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

Returns the shape of the current frame.

Panics

Panics if the Partial has been poisoned or built, or if there are no frames (which indicates a bug in the Partial implementation).

pub fn try_shape(&self) -> Option<&'static Shape>

Returns the shape of the current frame, or None if the Partial is inactive (poisoned or built) or has no frames.

This is useful for debugging/logging where you want to inspect the state without risking a panic.

pub fn is_building_smart_ptr_slice(&self) -> bool

Returns true if the current frame is building a smart pointer slice (Arc<[T]>, Rc<[T]>, Box<[T]>).

This is used by deserializers to determine if they should deserialize as a list rather than recursing into the smart pointer type.

pub fn deferred_resolution(&self) -> Option<&Resolution>

Returns the current deferred resolution, if in deferred mode.

pub fn current_path_slice(&self) -> Option<&[&'static str]>

Returns the current path in deferred mode as a slice (for debugging/tracing).

pub fn begin_deferred( self, resolution: Resolution, ) -> Result<Self, ReflectError>

Enables deferred materialization mode with the given Resolution.

When deferred mode is enabled:

• end() stores frames instead of validating them
• Re-entering a path restores the stored frame with its state intact
• finish_deferred() performs final validation and materialization

This allows deserializers to handle interleaved fields (e.g., TOML dotted keys, flattened structs) where nested fields aren’t contiguous in the input.

Use Cases

• TOML dotted keys: inner.x = 1 followed by count = 2 then inner.y = 3
• Flattened structs where nested fields appear at the parent level
• Any format where field order doesn’t match struct nesting

Errors

Returns an error if already in deferred mode.

pub fn finish_deferred(self) -> Result<Self, ReflectError>

Finishes deferred mode: validates all stored frames and finalizes.

This method:

1. Validates that all stored frames are fully initialized
2. Processes frames from deepest to shallowest, updating parent ISets
3. Validates the root frame

Errors

Returns an error if any required fields are missing or if the partial is not in deferred mode.

pub fn end(self) -> Result<Self, ReflectError>

Pops the current frame off the stack, indicating we’re done initializing the current field

pub fn path(&self) -> String

Returns a human-readable path representing the current traversal in the builder, e.g., RootStruct.fieldName[index].subfield.

pub fn parent_field(&self) -> Option<&Field>

Get the field for the parent frame

pub fn current_field(&self) -> Option<&Field>

Gets the field for the current frame

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_some(self) -> Result<Self, ReflectError>

Begin building the Some variant of an Option

pub fn begin_inner(self) -> Result<Self, ReflectError>

Begin building the inner value of a wrapper type

pub fn begin_custom_deserialization(self) -> Result<Self, ReflectError>

Begin bulding the source shape for custom deserialization, calling end() for this frame will call the deserialize_with function provided by the field and set the field using the result.

pub fn begin_custom_deserialization_from_shape( self, ) -> Result<(Self, bool), ReflectError>

Begin building the source shape for custom deserialization using container-level proxy.

Unlike begin_custom_deserialization which uses field-level proxy info, this method uses the shape’s own proxy definition (from #[facet(proxy = ...)] at container level).

Returns Ok((self, true)) if the shape has a container-level proxy and we’ve begun custom deserialization, Ok((self, false)) if not (self is returned unchanged).

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_smart_ptr(self) -> Result<Self, ReflectError>

Pushes a frame to initialize the inner value of a smart pointer (Box<T>, Arc<T>, etc.)

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_ok(self) -> Result<Self, ReflectError>

Begin building the Ok variant of a Result

pub fn begin_err(self) -> Result<Self, ReflectError>

Begin building the Err variant of a Result

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn set<U>(self, value: U) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Sets a value wholesale into the current frame.

If the current frame was already initialized, the previous value is dropped. If it was partially initialized, the fields that were initialized are dropped, etc.

pub unsafe fn set_shape( self, src_value: PtrConst, src_shape: &'static Shape, ) -> Result<Self, ReflectError>

Sets a value into the current frame by PtrConst / Shape.

Safety

The caller must ensure that src_value points to a valid instance of a value whose memory layout and type matches src_shape, and that this value can be safely copied (bitwise) into the destination specified by the Partial’s current frame.

After a successful call, the ownership of the value at src_value is effectively moved into the Partial (i.e., the destination), and the original value should not be used or dropped by the caller; you should use core::mem::forget on the passed value.

If an error is returned, the destination remains unmodified and safe for future operations.

pub fn set_datetime( self, year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, nanos: u32, kind: DynDateTimeKind, ) -> Result<Self, ReflectError>

Sets a datetime value into a DynamicValue target.

This is used for format-specific datetime types (like TOML datetime). Returns an error if the target doesn’t support datetime values.

pub unsafe fn set_from_function<F>(self, f: F) -> Result<Self, ReflectError>

where F: FnOnce(PtrUninit) -> Result<(), ReflectError>,

Sets the current frame using a function that initializes the value

Safety

If f returns Ok(), it is assumed that it initialized the passed pointer fully and with a value of the right type.

If f returns Err(), it is assumed that it did NOT initialize the passed pointer and that there is no need to drop it in place.

pub fn set_default(self) -> Result<Self, ReflectError>

Sets the current frame to its default value using default_in_place from the vtable.

Note: if you have struct S { field: F }, and F does not implement Default but S does, this doesn’t magically uses S’s Default implementation to get a value for field.

If the current frame’s shape does not implement Default, then this returns an error.

pub unsafe fn set_from_peek( self, peek: &Peek<'_, '_>, ) -> Result<Self, ReflectError>

Copy a value from a Peek into the current frame.

Invariants

peek must be a thin pointer, otherwise this panics.

Safety

If this succeeds, the value Peek points to has been moved out of, and as such, should not be dropped (but should be deallocated).

pub fn parse_from_str(self, s: &str) -> Result<Self, ReflectError>

Parses a string value into the current frame using the type’s ParseFn from the vtable.

If the current frame was previously initialized, its contents are dropped in place.

pub fn parse_from_bytes(self, bytes: &[u8]) -> Result<Self, ReflectError>

Parses a byte slice into the current frame using the type’s ParseBytesFn from the vtable.

This is used for binary formats where types have efficient binary representations (e.g., UUID as 16 raw bytes instead of a string).

If the current frame was previously initialized, its contents are dropped in place.

impl<const BORROW: bool> Partial<'_, BORROW>

pub fn begin_set(self) -> Result<Self, ReflectError>

Initializes a set (HashSet, BTreeSet, etc.) if it hasn’t been initialized before. This is a prerequisite to begin_set_item/set/end or the shorthand insert.

begin_set does not clear the set if it was previously initialized. begin_set does not push a new frame to the stack, and thus does not require end to be called afterwards.

pub fn begin_set_item(self) -> Result<Self, ReflectError>

Begins pushing an element to the set. The element should be set using set() or similar methods, then end() to complete.

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn set_nth_field<U>( self, idx: usize, value: U, ) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Convenience shortcut: sets the field at index idx directly to value, popping after.

Works on structs, enums (after selecting a variant) and arrays.

pub fn set_field<U>( self, field_name: &str, value: U, ) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Convenience shortcut: sets the named field to value, popping after.

pub fn set_key<U>(self, value: U) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Convenience shortcut: sets the key for a map key-value insertion, then pops after.

pub fn set_value<U>(self, value: U) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Convenience shortcut: sets the value for a map key-value insertion, then pops after.

pub fn push<U>(self, value: U) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Shorthand for: begin_list_item(), set(), end()

pub fn insert<U>(self, value: U) -> Result<Self, ReflectError>

where U: Facet<'facet>,

Shorthand for: begin_set_item(), set(), end()

impl<'facet, const BORROW: bool> Partial<'facet, BORROW>

pub fn is_deferred(&self) -> bool

Check if we’re in deferred mode.

Trait Implementations

impl<'facet, const BORROW: bool> Drop for Partial<'facet, BORROW>

fn drop(&mut self)

Executes the destructor for this type.