Skip to main content

Module struct_patch

Module struct_patch 

Source
Expand description

Struct patches: sparse, O(changes) edits to the fields of an input struct.

A struct patch keeps, drops, replaces, or inserts fields relative to an input struct without enumerating untouched fields. Patches are built with a StructPatchBuilder, which validates conflicting operations and lowers nested field paths into recursive patches. Three flavors share the same builder surface, differing only in their item type and terminal build step:

§Worked example

Every builder call names one edit relative to an input field:

ⓘ
builder
    .prepend(first)
    .insert_after("a", x)
    .replace("b", bb)
    .drop("c")
    .append(last)

Applied to { a, b, c }, walking the input fields in order:

input field:   (none)     a              b          c        (none)
edit:          prepend    keep +after    replace    drop     append
emits:         first      a, x           bb         nothing  last

output:        { first, a, x, bb, last }

Field a is untouched and passes through in place, which is what makes the patch cost O(edits) rather than O(struct width). The _at variants (e.g. insert_after_at) apply the same edits to a nested struct named by path.

§Flattening to a dense projection

An engine whose projection operator takes one expression per output column has to expand the patch, which is the walk the example above traces. Emit prepended_fields, then visit the input struct’s fields in order: look each one up in field_patches, emit the field itself when the entry is absent or sets keep_input, and emit that entry’s insertions after it. An entry that keeps nothing and inserts nothing drops the field. Finish with appended_fields. A nested patch arrives as an Expression::StructPatch insertion, so the same walk recurses with that patch’s input_path as the struct to expand against.

ProjectionStructPatchBuilder hands back the flattened schema already, so a caller building both halves can pair its dense field list with the expressions this walk produces rather than deriving the field names again.

Structs§

ExpressionFieldPatch
A patch affecting a single input field.
ExpressionStructPatch
A sparse expression patch over the fields of one input struct.
ProjectionStructPatchBuilder
Builds schema and expression patches together over an input schema.
StructPatchBuilder
Builds a sparse struct patch from a sequence of requested patch operations.