@ (ordinal structValue -- selectedItem)

Inputs

• ordinal: Zero-based item ordinal to read.
• structValue: Struct object or Ref to Struct being read.

Outputs

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

Reads one selected item by zero-based item ordinal, with the ordinal before the Struct object.

Builtin @ does not call callable items automatically.

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.
• An unknown ordinal is invalid on a non-uniform or Meta Struct.
• 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 @. 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.

In the example below, each heading performs the mutable read first with @dict, then the immutable read with dict.

Example

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

  "-- In-place item --" printCompilerMessage
  0 @dict @ printStack _:;
  0 dict @ printStack _:;

  "-- Ref item --" printCompilerMessage
  1 @dict @ printStack _:;
  1 dict @ printStack _:;

  "-- static item --" printCompilerMessage
  dict 2 fieldIsVirtual printStack _:;
  2 @dict @ printStack _:;
  2 dict @ printStack _:;

  "-- text item --" printCompilerMessage
  3 @dict @ printStack _:;
  3 dict @ printStack _:;

  "-- code item --" printCompilerMessage
  4 @dict @ printStack _:;
  4 dict @ printStack _:;

  "-- meta item --" printCompilerMessage
  5 @dict @ printStack _:;
  5 dict @ printStack _:;

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

  0
] "main" exportFunction

Expected Output During Compilation

-- In-place item --
1 Ref
1 Cref
-- Ref item --
7 Ref
7 Cref
-- static item --
TRUE
2
2
-- text item --
Text
Text
-- code item --
{} () {} codeRef CNIL
{} () {} codeRef CNIL
-- meta item --
()
()
-- uniform struct through unknown ordinal --
Int32 Ref
Int32 Cref

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 one-item write with the ordinal before the Struct target.
• callField builtin (inputs... dict name -- outputs...) Known-name data-input Dict field selection with .NAME-style semantics.
• 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 object before the ordinal.
• fieldWrite builtin (source structTarget ordinal --) Ordinal-based one-item write with the Struct target before the ordinal.