fieldRead (structValue ordinal -- selectedItem)

Inputs

• structValue: Struct object or Ref to Struct from which the selected item is read.
• ordinal: Zero-based item ordinal used for selection.

Outputs

• selectedItem: Stack object produced by reading the selected item.

fieldRead reads one selected item by zero-based item ordinal, with the Struct object before the ordinal. Both inputs are dereferenced first.

Selection happens inside the builtin from data inputs. fieldRead does not call callable items automatically. A mutable Ref result from a non-static In-place item can serve as the already-selected destination for set.

Behavior

• The ordinal input must be a non-NIL Int32.
• A known in-bounds ordinal reads the selected item 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 read succeeds, but the exact selected item is not known at compile time.
• A non-static In-place item produces a new Ref to the selected item. The result is a mutable Ref when structValue was reached mutably and an immutable Ref otherwise.
• A Ref, Code, or Text item produces the copied object of that item.
• A static item produces a new object from schema data instead of runtime field storage.
• A Meta item produces a new Meta object of the selected item schema.

fieldIsRef and fieldIsVirtual describe the selected item schema, not the stack result produced by fieldRead. A non-static In-place item can therefore yield a Ref result even when fieldIsRef is FALSE, while a static or Meta item can still yield a copied or newly constructed result even when fieldIsVirtual is TRUE.

Example

{} 0 {} [
  dict: {
    ordinaryField: 0;
    staticField: 1 virtual;
    textField: 0 ("") dynamic @; # an unknown Text
    codeField: {} () {} codeRef;
    metaField: ();
  };
  list: (1 2) dynamic;
  ordinal: 0 dynamic;

  "-- In-place field through mutable struct --" printCompilerMessage
  @dict 0 fieldRead printStack _:;

  "-- In-place field through immutable struct --" printCompilerMessage
  dict 0 fieldRead printStack _:;

  "-- static field --" printCompilerMessage
  dict 1 fieldIsVirtual printStack _:;
  @dict 1 fieldRead printStack _:;

  "-- text field --" printCompilerMessage
  @dict 2 fieldRead printStack _:;

  "-- code field --" printCompilerMessage
  @dict 3 fieldRead printStack _:;

  "-- meta field --" printCompilerMessage
  @dict 4 fieldRead printStack _:;

  "-- uniform struct through unknown ordinal --" printCompilerMessage
  @list ordinal fieldRead printStack _:;

  0
] "main" exportFunction

Expected Output During Compilation

-- In-place field through mutable struct --
0 Ref
-- In-place field through immutable struct --
0 Cref
-- static field --
TRUE
1
-- text field --
Text
-- code field --
{} () {} codeRef CNIL
-- meta field --
()
-- uniform struct through unknown ordinal --
Int32 Ref

See also

• .@NAME node .@NAME Named field read without calling.
• .NAME node .NAME Named field mention and call if callable.
• ! builtin (source 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 object. Callable items are read, not called.
• callField builtin (inputs... dict name -- outputs...) Known-name data-input Dict field selection with .NAME-style field handling. Callable fields are called; non-callable fields are read.
• 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.
• fieldWrite builtin (source structTarget ordinal --) Ordinal-based data-input selection and write with the Struct target before the ordinal.
• set builtin (source destination --) Final replacement step after a separate selection form such as a mutable fieldRead result.