pub struct Partial<'facet, const BORROW: bool = true> { /* private fields */ }Expand description
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§
Source§impl<'facet> Partial<'facet, true>
impl<'facet> Partial<'facet, true>
Sourcepub fn alloc<T: Facet<'facet>>() -> Result<Self, AllocError>
pub fn alloc<T: Facet<'facet>>() -> Result<Self, AllocError>
Create a new borrowing Partial for the given type.
This allocates memory for a value of type T and returns a Partial
that can be used to initialize it incrementally.
Sourcepub fn alloc_with_plan(plan: Arc<TypePlanCore>) -> Result<Self, AllocError>
pub fn alloc_with_plan(plan: Arc<TypePlanCore>) -> Result<Self, AllocError>
Create a new borrowing Partial from a prebuilt TypePlanCore.
This is useful when callers manage their own plan caching.
Sourcepub unsafe fn alloc_shape(shape: &'static Shape) -> Result<Self, AllocError>
pub unsafe fn alloc_shape(shape: &'static Shape) -> Result<Self, AllocError>
Create a new borrowing Partial from a shape.
This allocates memory for a value described by the shape and returns a Partial
that can be used to initialize it incrementally.
§Safety
The caller must ensure that the shape is valid and corresponds to a real type. Using an incorrect or maliciously crafted shape can lead to undefined behavior when materializing values.
Source§impl Partial<'static, false>
impl Partial<'static, false>
Sourcepub fn alloc_owned<T: Facet<'static>>() -> Result<Self, AllocError>
pub fn alloc_owned<T: Facet<'static>>() -> Result<Self, AllocError>
Create a new owned Partial for the given type.
This allocates memory for a value of type T and returns a Partial
that can be used to initialize it incrementally.
Sourcepub fn alloc_owned_with_plan(
plan: Arc<TypePlanCore>,
) -> Result<Self, AllocError>
pub fn alloc_owned_with_plan( plan: Arc<TypePlanCore>, ) -> Result<Self, AllocError>
Create a new owned Partial from a prebuilt TypePlanCore.
This is useful when callers manage their own plan caching.
Sourcepub unsafe fn alloc_shape_owned(
shape: &'static Shape,
) -> Result<Self, AllocError>
pub unsafe fn alloc_shape_owned( shape: &'static Shape, ) -> Result<Self, AllocError>
Create a new owned Partial from a shape.
This allocates memory for a value described by the shape and returns a Partial
that can be used to initialize it incrementally. The resulting value will be
fully owned (’static lifetime).
§Safety
The caller must ensure that the shape is valid and corresponds to a real type. Using an incorrect or maliciously crafted shape can lead to undefined behavior when materializing values.
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub unsafe fn from_raw(
data: PtrUninit,
plan: Arc<TypePlanCore>,
type_plan_id: NodeId,
) -> Result<Self, AllocError>
pub unsafe fn from_raw( data: PtrUninit, plan: Arc<TypePlanCore>, type_plan_id: NodeId, ) -> Result<Self, AllocError>
Creates a new Partial pointing to caller-provided memory.
This is a low-level API that lets the caller:
- Control where the value is allocated (stack, existing heap allocation, etc.)
- Avoid the heap allocation that Partial::alloc does
- Use MaybeUninit on the stack for the final value
§Safety
The caller MUST ensure:
datapoints to properly aligned, writable memory of at leastshape.layout.size()bytes- The memory remains valid for the lifetime of this Partial and any value built from it
- The memory is not aliased by any other mutable references while the Partial exists
- If the Partial is dropped without calling
build(), the caller handles the uninitialized memory
§Example: Stack allocation with MaybeUninit
use std::mem::MaybeUninit;
// Stack-allocate space for the value
let mut slot = MaybeUninit::<MyStruct>::uninit();
let data = PtrUninit::new(slot.as_mut_ptr().cast());
// Build the TypePlan (can be reused via Arc)
let plan = TypePlan::<MyStruct>::build()?;
// Create Partial pointing to our stack memory
let partial = unsafe { Partial::from_raw(data, plan.core(), plan.core().root_id())? };
// Initialize fields...
let partial = partial.set_field("name", "test")?.set_field("value", 42)?;
// Build consumes the Partial but does NOT allocate - value is already in `slot`
let heap_value = partial.build()?;
// SAFETY: We fully initialized the value, so we can assume_init
let value = unsafe { slot.assume_init() };§Memory ownership
The returned Partial has external ownership, which means:
- On successful
build(): memory ownership transfers to the returned HeapValue - On drop without
build(): partially initialized memory is dropped in place, but memory is NOT deallocated (caller must handle the memory)
Sourcepub unsafe fn from_raw_with_shape(
data: PtrUninit,
shape: &'static Shape,
) -> Result<Self, AllocError>
pub unsafe fn from_raw_with_shape( data: PtrUninit, shape: &'static Shape, ) -> Result<Self, AllocError>
Creates a new Partial from caller-provided memory and a shape.
This is a convenience API over Self::from_raw that resolves the root
type plan from shape and reuses the process-global TypePlan cache under
std.
§Safety
Same requirements as Self::from_raw, plus the caller must ensure that
shape is valid and corresponds to a real type.
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub fn enter_deferred(self) -> Self
pub fn enter_deferred(self) -> Self
Enter deferred mode for the current frame.
In deferred mode, frames can be stored when popped via end() and restored
when re-entered via begin_field(). This enables formats like TOML where
keys for the same table may appear non-contiguously.
§Returns
A new Partial in deferred mode. The original Partial is consumed.
§Deferred mode behavior
- When
end()is called on a frame that isn’t fully initialized, the frame is stored (keyed by its path) instead of being validated. - When
begin_field()is called for a stored frame, it’s restored instead of creating a new one. - Call
finish_deferred()when done to validate all stored frames and exit deferred mode.
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub fn build(self) -> Result<HeapValue<'facet, BORROW>, ReflectError>
pub fn build(self) -> Result<HeapValue<'facet, BORROW>, ReflectError>
Builds the value, consuming the Partial.
Sourcepub fn finish_in_place(self) -> Result<(), ReflectError>
pub fn finish_in_place(self) -> Result<(), ReflectError>
Finishes deserialization in-place, validating the value without moving it.
This is intended for use with from_raw where the value
is deserialized into caller-provided memory (e.g., a MaybeUninit<T> on the stack).
On success, the caller can safely assume the memory contains a fully initialized,
valid value and call MaybeUninit::assume_init().
On failure, any partially initialized data is cleaned up (dropped), and the memory should be considered uninitialized.
§Panics
Panics if called with more than one frame on the stack (i.e., if you haven’t
called end() enough times to return to the root level).
§Example
use std::mem::MaybeUninit;
use facet_core::{Facet, PtrUninit};
use facet_reflect::Partial;
let mut slot = MaybeUninit::<MyStruct>::uninit();
let ptr = PtrUninit::new(slot.as_mut_ptr().cast());
let partial = unsafe { Partial::from_raw_with_shape(ptr, MyStruct::SHAPE)? };
// ... deserialize into partial ...
partial.finish_in_place()?;
// Now safe to assume initialized
let value = unsafe { slot.assume_init() };Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub fn selected_variant(&self) -> Option<Variant>
pub fn selected_variant(&self) -> Option<Variant>
Get the currently selected variant for an enum
Sourcepub fn selected_variant_plan(&self) -> Option<&VariantPlanMeta>
pub fn selected_variant_plan(&self) -> Option<&VariantPlanMeta>
Get the currently selected variant’s plan metadata.
Returns the VariantPlanMeta for the selected variant, which contains precomputed
information like has_flatten and field_lookup for fast field lookups.
Sourcepub fn find_variant(
&self,
variant_name: &str,
) -> Option<(usize, &'static Variant)>
pub fn find_variant( &self, variant_name: &str, ) -> Option<(usize, &'static Variant)>
Find a variant by name in the current enum.
This searches by effective name (respecting #[facet(rename = "...")] attributes).
Sourcepub fn select_nth_variant(self, index: usize) -> Result<Self, ReflectError>
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.
Sourcepub fn select_variant_named(
self,
variant_name: &str,
) -> Result<Self, ReflectError>
pub fn select_variant_named( self, variant_name: &str, ) -> Result<Self, ReflectError>
Pushes a variant for enum initialization by name.
This searches by effective name (respecting #[facet(rename = "...")] attributes).
See Self::select_nth_variant for more notes.
Sourcepub fn select_variant(self, discriminant: i64) -> Result<Self, ReflectError>
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.
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn field_index(&self, field_name: &str) -> Option<usize>
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.
Sourcepub fn is_field_set(&self, index: usize) -> Result<bool, ReflectError>
pub fn is_field_set(&self, index: usize) -> Result<bool, ReflectError>
Check if a struct field at the given index has been set
Sourcepub fn begin_field(self, field_name: &str) -> Result<Self, ReflectError>
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.
Sourcepub fn begin_nth_field(self, idx: usize) -> Result<Self, ReflectError>
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
Sourcepub fn set_nth_field_to_default(self, idx: usize) -> Result<Self, ReflectError>
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
Defaultimplementation 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.
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn init_list(self) -> Result<Self, ReflectError>
pub fn init_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.
init_list does not clear the list if it was previously initialized.
init_list does not push a new frame to the stack, and thus does not
require end to be called afterwards.
Sourcepub fn init_list_with_capacity(
self,
capacity: usize,
) -> Result<Self, ReflectError>
pub fn init_list_with_capacity( self, capacity: usize, ) -> Result<Self, ReflectError>
Initializes a list with a capacity hint for pre-allocation.
Like init_list, but reserves space for capacity elements upfront.
This reduces allocations when the number of elements is known or estimated.
Sourcepub fn init_array(self) -> Result<Self, ReflectError>
pub fn init_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 init_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.
init_array does not push a new frame to the stack.
Sourcepub fn begin_list_item(self) -> Result<Self, ReflectError>
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
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn init_map(self) -> Result<Self, ReflectError>
pub fn init_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.
Sourcepub fn begin_key(self) -> Result<Self, ReflectError>
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.
Sourcepub fn begin_value(self) -> Result<Self, ReflectError>
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
Sourcepub fn begin_object_entry(self, key: &str) -> Result<Self, ReflectError>
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.
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub fn with<F, E>(self, f: F) -> Result<Self, E>
pub fn with<F, E>(self, f: F) -> Result<Self, E>
Applies a closure to this Partial, enabling chaining with operations that
take ownership and return Result<Self, E>.
This is useful for chaining deserializer methods that need &mut self:
wip = wip
.begin_field("name")?
.with(|w| deserializer.deserialize_into(w))?
.end()?;Sourcepub fn is_active(&self) -> bool
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.
Sourcepub const fn frame_count(&self) -> usize
pub const 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.
Sourcepub fn shape(&self) -> &'static Shape
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).
Sourcepub fn try_shape(&self) -> Option<&'static Shape>
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.
Sourcepub fn type_plan_core(&self) -> &TypePlanCore
pub fn type_plan_core(&self) -> &TypePlanCore
Returns the TypePlanCore for this Partial.
This provides access to the arena-based type plan data, useful for resolving field lookups and accessing precomputed metadata.
Sourcepub fn struct_plan(&self) -> Option<&StructPlan>
pub fn struct_plan(&self) -> Option<&StructPlan>
Returns the precomputed StructPlan for the current frame, if available.
This provides O(1) or O(log n) field lookup instead of O(n) linear scanning.
Returns None if:
- The Partial is not active
- The current frame has no TypePlan (e.g., custom deserialization frames)
- The current type is not a struct
Sourcepub fn enum_plan(&self) -> Option<&EnumPlan>
pub fn enum_plan(&self) -> Option<&EnumPlan>
Returns the precomputed EnumPlan for the current frame, if available.
This provides O(1) or O(log n) variant lookup instead of O(n) linear scanning.
Returns None if:
- The Partial is not active
- The current type is not an enum
Sourcepub fn field_plans(&self) -> Option<&[FieldPlan]>
pub fn field_plans(&self) -> Option<&[FieldPlan]>
Returns the precomputed field plans for the current frame.
This provides access to precomputed validators and default handling without runtime attribute scanning.
Returns None if the current type is not a struct or enum variant.
Sourcepub fn plan_node(&self) -> Option<&TypePlanNode>
pub fn plan_node(&self) -> Option<&TypePlanNode>
Returns the precomputed TypePlanNode for the current frame.
This provides access to the precomputed deserialization strategy and other metadata computed at Partial allocation time.
Returns None if:
- The Partial is not active
- There are no frames
Sourcepub fn plan_node_id(&self) -> Option<NodeId>
pub fn plan_node_id(&self) -> Option<NodeId>
Returns the node ID for the current frame’s type plan.
Returns None if:
- The Partial is not active
- There are no frames
Sourcepub fn deser_strategy(&self) -> Option<&DeserStrategy>
pub fn deser_strategy(&self) -> Option<&DeserStrategy>
Returns the precomputed deserialization strategy for the current frame.
This tells facet-format exactly how to deserialize the current type without runtime inspection of Shape/Def/vtable. The strategy is computed once at TypePlan build time.
If the current node is a BackRef (recursive type), this automatically follows the reference to return the target node’s strategy.
Returns None if:
- The Partial is not active
- There are no frames
Sourcepub fn proxy_nodes(&self) -> Option<&ProxyNodes>
pub fn proxy_nodes(&self) -> Option<&ProxyNodes>
Returns the precomputed proxy nodes for the current frame’s type.
These contain TypePlan nodes for all proxies (format-agnostic and format-specific) on this type, allowing runtime lookup based on format namespace.
Sourcepub fn is_building_smart_ptr_slice(&self) -> bool
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.
Sourcepub fn current_path(&self) -> Option<Path>
pub fn current_path(&self) -> Option<Path>
Returns the current path in deferred mode (for debugging/tracing).
Sourcepub fn begin_deferred(self) -> Result<Self, ReflectError>
pub fn begin_deferred(self) -> 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 = 1followed bycount = 2theninner.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.
Sourcepub fn finish_deferred(self) -> Result<Self, ReflectError>
pub fn finish_deferred(self) -> Result<Self, ReflectError>
Finishes deferred mode: validates all stored frames and finalizes.
This method:
- Validates that all stored frames are fully initialized
- Processes frames from deepest to shallowest, updating parent ISets
- Validates the root frame
§Errors
Returns an error if any required fields are missing or if the partial is not in deferred mode.
Sourcepub fn end(self) -> Result<Self, ReflectError>
pub fn end(self) -> Result<Self, ReflectError>
Pops the current frame off the stack, indicating we’re done initializing the current field
Sourcepub fn path(&self) -> Path
pub fn path(&self) -> Path
Returns a path representing the current traversal in the builder.
The returned facet_path::Path can be formatted as a human-readable string
using Path::format_with_shape(),
e.g., fieldName[index].subfield.
Sourcepub fn root_shape(&self) -> &'static Shape
pub fn root_shape(&self) -> &'static Shape
Sourcepub fn err(&self, kind: ReflectErrorKind) -> ReflectError
pub fn err(&self, kind: ReflectErrorKind) -> ReflectError
Create a ReflectError with the current path context.
This is a convenience method for constructing errors inside Partial methods
that automatically captures the current traversal path.
Sourcepub fn parent_field(&self) -> Option<&Field>
pub fn parent_field(&self) -> Option<&Field>
Get the field for the parent frame
Sourcepub fn current_field(&self) -> Option<&Field>
pub fn current_field(&self) -> Option<&Field>
Gets the field for the current frame
Sourcepub fn nearest_field(&self) -> Option<&Field>
pub fn nearest_field(&self) -> Option<&Field>
Gets the nearest active field when nested wrapper frames are involved.
This walks frames from innermost to outermost and returns the first frame that currently points at a struct/enum field.
Sourcepub fn data_ptr(&self) -> Option<PtrConst>
👎Deprecated: use initialized_data_ptr() instead, which checks initialization
pub fn data_ptr(&self) -> Option<PtrConst>
Returns a const pointer to the current frame’s data.
This is useful for validation - after deserializing a field value, validators can read the value through this pointer.
§Safety
The returned pointer is valid only while the frame exists. The caller must ensure the frame is fully initialized before reading through this pointer.
Sourcepub fn initialized_data_ptr(&mut self) -> Option<PtrConst>
pub fn initialized_data_ptr(&mut self) -> Option<PtrConst>
Returns a const pointer to the current frame’s data, but only if fully initialized.
This is the safe way to get a pointer for validation - it verifies that the frame is fully initialized before returning the pointer.
Returns None if:
- The partial is not in active state
- The current frame is not fully initialized
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn begin_some(self) -> Result<Self, ReflectError>
pub fn begin_some(self) -> Result<Self, ReflectError>
Begin building the Some variant of an Option
Sourcepub fn begin_inner(self) -> Result<Self, ReflectError>
pub fn begin_inner(self) -> Result<Self, ReflectError>
Begin building the inner value of a wrapper type
Sourcepub fn begin_custom_deserialization(self) -> Result<Self, ReflectError>
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.
This uses the format-agnostic proxy. For format-specific proxies, use
begin_custom_deserialization_with_format.
Sourcepub fn begin_custom_deserialization_from_shape(
self,
) -> Result<(Self, bool), ReflectError>
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).
Sourcepub fn begin_custom_deserialization_from_shape_with_format(
self,
format_namespace: Option<&str>,
) -> Result<(Self, bool), ReflectError>
pub fn begin_custom_deserialization_from_shape_with_format( self, format_namespace: Option<&str>, ) -> Result<(Self, bool), ReflectError>
Begin building the source shape for custom deserialization using container-level proxy, with support for format-specific proxy resolution.
If format_namespace is provided (e.g., Some("xml")), looks for a format-specific
proxy first (e.g., #[facet(xml::proxy = XmlProxy)]), falling back to the format-agnostic
proxy if no format-specific one is found.
Returns Ok((self, true)) if a proxy was found and we’ve begun custom deserialization,
Ok((self, false)) if not (self is returned unchanged).
Sourcepub fn begin_custom_deserialization_with_format(
self,
format_namespace: Option<&str>,
) -> Result<Self, ReflectError>
pub fn begin_custom_deserialization_with_format( self, format_namespace: Option<&str>, ) -> Result<Self, ReflectError>
Begin building the source shape for custom deserialization using field-level proxy, with support for format-specific proxy resolution.
If format_namespace is provided (e.g., Some("xml")), looks for a format-specific
proxy first (e.g., #[facet(xml::proxy = XmlProxy)]), falling back to the format-agnostic
proxy if no format-specific one is found.
This is the format-aware version of begin_custom_deserialization.
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn begin_smart_ptr(self) -> Result<Self, ReflectError>
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.)
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn begin_ok(self) -> Result<Self, ReflectError>
pub fn begin_ok(self) -> Result<Self, ReflectError>
Begin building the Ok variant of a Result
Sourcepub fn begin_err(self) -> Result<Self, ReflectError>
pub fn begin_err(self) -> Result<Self, ReflectError>
Begin building the Err variant of a Result
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Set a shared slice reference (&[T]) to an empty slice without knowing T at compile time.
This writes a valid wide reference with len=0 and a suitably aligned dangling data pointer.
Sourcepub fn set<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
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.
Sourcepub unsafe fn set_shape(
self,
src_value: PtrConst,
src_shape: &'static Shape,
) -> Result<Self, ReflectError>
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.
Sourcepub fn set_datetime(
self,
year: i32,
month: u8,
day: u8,
hour: u8,
minute: u8,
second: u8,
nanos: u32,
kind: DynDateTimeKind,
) -> Result<Self, ReflectError>
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.
Sourcepub unsafe fn set_from_function<F>(self, f: F) -> Result<Self, ReflectError>
pub unsafe fn set_from_function<F>(self, f: F) -> Result<Self, 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.
Sourcepub fn set_default(self) -> Result<Self, ReflectError>
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.
Sourcepub unsafe fn set_from_peek(
self,
peek: &Peek<'_, '_>,
) -> Result<Self, ReflectError>
pub unsafe fn set_from_peek( self, peek: &Peek<'_, '_>, ) -> Result<Self, ReflectError>
Sourcepub fn parse_from_str(self, s: &str) -> Result<Self, ReflectError>
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.
Sourcepub fn parse_from_bytes(self, bytes: &[u8]) -> Result<Self, ReflectError>
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.
Source§impl<const BORROW: bool> Partial<'_, BORROW>
impl<const BORROW: bool> Partial<'_, BORROW>
Sourcepub fn init_set(self) -> Result<Self, ReflectError>
pub fn init_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.
init_set does not clear the set if it was previously initialized.
init_set does not push a new frame to the stack, and thus does not
require end to be called afterwards.
Sourcepub fn begin_set_item(self) -> Result<Self, ReflectError>
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.
Source§impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
impl<'facet, const BORROW: bool> Partial<'facet, BORROW>
Sourcepub fn set_nth_field<U>(
self,
idx: usize,
value: U,
) -> Result<Self, ReflectError>where
U: Facet<'facet>,
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.
Sourcepub fn set_field<U>(
self,
field_name: &str,
value: U,
) -> Result<Self, ReflectError>where
U: Facet<'facet>,
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.
Sourcepub fn set_key<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
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.
Sourcepub fn set_value<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
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.
Sourcepub fn push<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
pub fn push<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
Shorthand for: begin_list_item(), set(), end()
Sourcepub fn insert<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
pub fn insert<U>(self, value: U) -> Result<Self, ReflectError>where
U: Facet<'facet>,
Shorthand for: begin_set_item(), set(), end()