fieldWrite (value structTarget ordinal --)

Inputs

• value: Value written to the selected item.
• structTarget: Struct value or Ref to Struct used for selection and receiving the write.
• ordinal: Zero-based item ordinal used for selection.

Outputs

• None.

Writes one selected item by zero-based item ordinal, with the value and Struct target before the ordinal.

Selection happens inside the builtin from data inputs. Both value and structTarget are dereferenced first. For In-place selected items, a Ref value therefore contributes the value it references. For Ref selected items, replacement still follows the selected item's own Ref schema.

Behavior

• The destination Struct must be mutable.
• The ordinal input must be a non-NIL Int32.
• A known in-bounds ordinal applies the selected item write rule directly.
• A known out-of-bounds ordinal is invalid.
• An unknown ordinal is valid only on a non-Meta uniform Struct. In that case the write succeeds, and any known enclosing uniform Struct value becomes unknown because the exact modified item is not known at compile time.
• An unknown ordinal is invalid on a non-uniform or Meta Struct.
• A non-static In-place item takes a direct value of the same schema by move.
• A Ref item replaces its stored Ref value. The selected referent is not rewritten; only the stored Ref value changes. The input value may be either a Ref whose target schema matches the referent schema or a direct value of the referent schema. An immutable Ref input is invalid when the selected item is a mutable Ref.
• A Text item takes a same-schema Text input value by move.
• A Code item accepts either a same-schema Code input value or a Block input value, which is compiled and stored without being called.
• A static item is invalid.
• No user-visible result is pushed.

fieldIsRef describes the selected item schema, not the accepted source form after dereferencing. A non-static In-place item can therefore still require a direct same-schema value even though reading the same item yields a Ref result, while a Ref item can accept either a matching Ref or a direct value of its referent schema.

Example

{} 0 {} [
  value: 1;
  dict: {
    ordinaryField: 2;
    mutableReferenceField: @value;
    immutableReferenceField: value;
    codeField: {} () {} codeRef;
  };

  "-- In-place item write rule --" printCompilerMessage
  dict 0 fieldIsRef printStack _:;
  7 @dict 0 fieldWrite
  @dict 0 fieldRead new printStack _:;

  "-- mutable Ref item write rule --" printCompilerMessage
  dict 1 fieldIsRef printStack _:;
  5 @dict 1 fieldWrite
  @dict 1 fieldRead printStack _:;

  "-- immutable Ref item write rule --" printCompilerMessage
  dict 2 fieldIsRef printStack _:;
  6 @dict 2 fieldWrite
  @dict 2 fieldRead printStack _:;

  "-- code item write rule --" printCompilerMessage
  dict 3 fieldIsRef printStack _:;
  ["-- code field compiled --" printCompilerMessage] @dict 3 fieldWrite
  @dict 3 fieldRead printStack _:;

  list: (1 2) dynamic;
  ordinal: 0 dynamic;
  "-- uniform struct through unknown ordinal --" printCompilerMessage
  9 @list ordinal fieldWrite
  @list new printStack _:;

  0
] "main" exportFunction

Expected Output During Compilation

-- In-place item write rule --
FALSE
7
-- mutable Ref item write rule --
TRUE
5 Ref
-- immutable Ref item write rule --
TRUE
6 Cref
-- code item write rule --
TRUE
-- code field compiled --
{} () {} codeRef
-- uniform struct through unknown ordinal --
Int32 2 array

See also

• !NAME node source form Named destination write by source-text name.
• .!NAME node source form Named field write by source-text name on a popped mutable Dict.
• ! builtin (value ordinal structTarget --) Ordinal-based data-input selection and write with the ordinal before the Struct target.
• @ builtin (ordinal structValue -- selectedItem) Ordinal-based data-input selection and read with the ordinal before the Struct value. Callable items are read, not called.
• fieldIsRef builtin (schema ordinal -- isRefLike) Ref-like test for one selected item schema.
• fieldIsVirtual builtin (schema ordinal -- hasNoStorage) No-storage test for one selected item.
• fieldRead builtin (structValue ordinal -- selectedItem) Ordinal-based data-input selection and read with the Struct value before the ordinal. Callable items are read, not called.
• set builtin (value destination --) Replaces an already-selected mutable same-schema destination after a separate selection step.