addressToReference · Builtins

`addressToReference (address modelValue -- reconstructedValue)`

Inputs

address: A known or unknown Natx storage address, supplied directly or through a non-NIL Ref. storageAddress produces a known or unknown Natx; it produces 0nx only for known NIL Ref, Text, and Code objects.
modelValue: Object that supplies the result schema case. When it is a Ref, it also supplies the result mutability; Text and Code keep their fixed schema semantics.

Outputs

reconstructedValue: Object reconstructed from the address and model object schema.

addressToReference reconstructs a typed result from a Natx storage address and a model object.

The model object is used only to choose the result schema case and, for a Ref model, the result mutability. Construction does not dereference the model, read storage, validate the address, or make a nonzero address safe for later use; the caller owns address validity and alignment.

For a non-static, non-callable In-place local or field (see selection), NAME or .NAME supplies the immutable Ref model case, while @NAME supplies the mutable case for a local and .@NAME supplies it for a field only when the enclosing Dict is reached through a mutable path.

Behavior

A Ref, Code, or Text model object produces a result of that same schema reconstructed from the supplied address.
For a Text model and an address not known to be zero, the result is an unknown Text whose data pointer is the supplied address and whose run-time byte length is zero; the builtin neither scans UTF-8 storage nor copies the model's length.
If the address is known to be zero, the builtin produces the known nil result of the implied schema. For direct non-Ref-like model objects, that implied schema is the corresponding Ref schema.
If the address is not known to be zero, the result is unknown: a Ref for a Ref or direct model, or unknown Text or Code for those models.
A direct non-Meta, non-Ref-like model object produces a mutable Ref to the model schema.
A Meta model object is invalid.

Example

{} () {} [
  value: 7;
  text: "hello";
  code: {} () {} codeRef;

  "-- Ref model value --" printCompilerMessage
  @value storageAddress @value addressToReference printStack _:;
  0nx @value addressToReference printStack _:; # a NIL Ref

  "-- immutable Ref model value --" printCompilerMessage
  @value storageAddress value addressToReference printStack _:;
  0nx value addressToReference printStack _:;

  "-- direct In-place model value --" printCompilerMessage
  0nx 7 addressToReference printStack _:;

  "-- Text and Code model values --" printCompilerMessage
  text storageAddress text addressToReference printStack _:;
  0nx text addressToReference printStack _:;
  0nx @code addressToReference printStack _:;
] "main" exportFunction

Expected Output During Compilation

-- Ref model value --
Int32 Ref
Int32 NIL
-- immutable Ref model value --
Int32 Cref
Int32 CNIL
-- direct In-place model value --
Int32 NIL
-- Text and Code model values --
Text
Text CNIL
{} () {} codeRef CNIL