! (value ordinal structTarget --)

Inputs

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

Outputs

• None.

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

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;
    referenceField: @value;
    codeField: {} () {} codeRef;
  };

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

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

  "-- code item write rule --" printCompilerMessage
  dict 2 fieldIsRef printStack _:;
  ["-- code item compiled --" printCompilerMessage] 2 @dict !
  2 @dict @ printStack _:;

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

  0
] "main" exportFunction

Expected Output During Compilation

-- In-place item write rule --
FALSE
7
-- Ref item write rule --
TRUE
5 Ref
-- code item write rule --
TRUE
-- code item 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 (ordinal structValue -- selectedItem) Ordinal-based one-item read with the ordinal before the Struct value.
• 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 one-item read with the Struct value before the ordinal.
• fieldWrite builtin (value structTarget ordinal --) Ordinal-based one-item write with the Struct target before the ordinal.
• set builtin (value destination --) Replaces an already-selected mutable same-schema destination.