Struct Partial 

pub struct Partial<'facet> { /* 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.

You might be interested in TypedPartial as well, which carries a generic type parameter to make TypedPartial::build type-safe. However, when implementing deserializers for example, if you want to avoid monomorphization, you might want to work with Partial directly.

Implementations

impl<'facet> Partial<'facet>

pub fn alloc<T>() -> Result<TypedPartial<'facet, T>, ReflectError>

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

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

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

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

impl<'facet> Partial<'facet>

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.

pub fn end(&mut self) -> Result<&mut 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

impl<'facet> Partial<'facet>

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

Builds the value

impl<'facet> Partial<'facet>

pub fn set<U>(&mut self, value: U) -> Result<&mut 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( &mut self, src_value: PtrConst<'_>, src_shape: &'static Shape, ) -> Result<&mut 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 unsafe fn set_from_function<F>( &mut self, f: F, ) -> Result<&mut 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(&mut self) -> Result<&mut 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( &mut self, peek: &Peek<'_, '_>, ) -> Result<&mut 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(&mut self, s: &str) -> Result<&mut 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.

impl<'facet> Partial<'facet>

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( &mut self, index: usize, ) -> Result<&mut 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( &mut self, variant_name: &str, ) -> Result<&mut Self, ReflectError>

Pushes a variant for enum initialization by name

See Self::select_nth_variant for more notes.

pub fn select_variant( &mut self, discriminant: i64, ) -> Result<&mut 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 Partial<'_>

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( &mut self, field_name: &str, ) -> Result<&mut 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(&mut self, idx: usize) -> Result<&mut 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( &mut self, idx: usize, ) -> Result<&mut 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.

pub fn steal_nth_field( &mut self, src: &mut Partial<'_>, field_index: usize, ) -> Result<&mut Self, ReflectError>

Given a Partial for the same shape, and assuming that partial has the nth field initialized, move the value from src to self, marking it as deinitialized in src.

impl Partial<'_>

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

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

impl Partial<'_>

pub fn begin_list(&mut self) -> Result<&mut 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_list_item(&mut self) -> Result<&mut Self, ReflectError>

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

impl Partial<'_>

pub fn begin_map(&mut self) -> Result<&mut 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.

pub fn begin_key(&mut self) -> Result<&mut 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(&mut self) -> Result<&mut Self, ReflectError>

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

impl Partial<'_>

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

Begin building the Some variant of an Option

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

Begin building the inner value of a wrapper type

pub fn begin_custom_deserialization( &mut self, ) -> Result<&mut 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.

impl<'facet> Partial<'facet>

pub fn set_nth_field<U>( &mut self, idx: usize, value: U, ) -> Result<&mut 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>( &mut self, field_name: &str, value: U, ) -> Result<&mut Self, ReflectError>

where U: Facet<'facet>,

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

pub fn set_key<U>(&mut self, value: U) -> Result<&mut 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>(&mut self, value: U) -> Result<&mut Self, ReflectError>

where U: Facet<'facet>,

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

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

where U: Facet<'facet>,

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

Trait Implementations

impl<'facet> Drop for Partial<'facet>

fn drop(&mut self)

Executes the destructor for this type.