Tagless overlapping storage for one value chosen from a fixed list of schemas.
Union
Construct with a schema list in tuple form, for example (Int32 Nat8) Union.
Union
(alternatives -- union) Constructs untagged overlapping storage.- Construction initializes the raw storage fields but does not initialize or destroy an alternative's managed value.
- Use a nonempty
ListorTupleof alternative-schema objects, such as (Int32Nat8). Their schemas and views describe the alternatives; their stored prototype values are not copied into the payload. - Union requires compatible iteration over the ordinal alternatives.
- A plain named Dict without iteration fails with
Built-in text, tuple, Iter, or Iterable expected.
Remarks
Fields
SCHEMA_NAME: staticTextwith value"Union".Items: static NILRefdescriptor for the alternative collection, not a stored copy of its values.data: the same alignment-based unsigned scalar choice as Variant.memory—oneNat8,Nat16,Nat32, orNat64.pad:Nat8array of lengthMAXIMUM_SIZE - MAXIMUM_ALIGNMENT.
Storage rules
- Union's payload starts at the beginning of the object. Total size includes any tail padding required by the maximum alignment; the supported payload alignments are 1, 2, 4, and 8 bytes.
- All measurements are target-dependent. Query
storageSizeandalignmentfor whole-object layout. - The
String/Int32case has Variant/Union sizes24/16on 64-bit targets and16/12under-32bits.
Methods
get
(key -- ref) Returns a borrowed typed view of the overlapping storage interpreted as the schema at key.keyis anInt32ordinal. A known key selects an in-range alternative; unknown keys require uniform alternative schemas. Runtime bounds are not checked for an unknown key, so the caller must keep it in range.- No active tag or stored-representation check is performed. Access through another valid key reinterprets the same storage.
- The result is mutable only when both the receiver view and the selected prototype view permit mutation; otherwise it is immutable. Use mutable prototype views when writable alternatives are required.
MAXIMUM_ALIGNMENT
(-- alignment) Returns the greatest alternative alignment in bytes as Int32, with a minimum of 1.Remarks
- This is a compile-time layout query over the stored alternative-schema descriptor, not a per-instance counter.
MAXIMUM_SIZE
(-- size) Returns the greatest alternative storage size in bytes as Int32, with a minimum of 1.Remarks
- This is a compile-time layout query over the stored alternative-schema descriptor, not a per-instance counter.
Getter result schemas
"Union" use
"control" use
{} () {} [
u: (Int32 Nat8) Union;
0 @u.get printStack _:;
1 @u.get printStack _:;
] "main" exportFunctionExpected Output During Compilation
Int32 Ref
Nat8 RefWrite through typed refs
"String" use
"Union" use
"control" use
{} Int32 {} [
u: (Int32 Nat8) Union;
123 0 @u.get set
("int=" 0 @u.get new LF) printList
7n8 1 @u.get set
("nat=" 1 @u.get new LF) printList
0
] "main" exportFunctionExpected Output
int=123
nat=7Reinterpret the same storage through another key
"String" use
"Union" use
"control" use
{} Int32 {} [
u: (Int32 Nat32) Union;
-1 0 @u.get set
("asInt=" 0 @u.get new LF
"asNat=" 1 @u.get new LF) printList
0
] "main" exportFunctionExpected Output
asInt=-1
asNat=4294967295Storage, lifetime, and copy semantics
- Returned views refer to the Union's backing storage, whose address does not change while that object remains alive and unmoved. This does not establish the lifetime or validity of every alternative. Initialize a managed alternative before using it, and do not use it after destroying it without reinitialization.
- Alternatives overlap from the start of the payload but may have different sizes. Writes affect the overlapping bytes; another alternative's decoded value need not change. The caller is responsible for the selected representation and alternative lifetime.
- Ordinary copying copies raw storage fields, not an alternative's managed ownership. Copies can therefore share pointers embedded in the payload.
- The Union wrapper does not destroy such payloads or prevent double destruction by the caller. Manage initialization, copying, ownership transfer, and destruction explicitly for managed alternatives; do not assume a raw source is cleared by a move-like expression.