Composites¶
A composite is an anonymous structural record. It has ordinary struct storage, field construction, copying, moving, and destruction. Its type is determined by its field names and declared field types.
For an introduction with structural record examples, see the Composites Overview.
Literal syntax¶
AUTO record := :{
.a = 1 AS I32;
.b = 9 AS I32;
.nested = :{ .x = 3 AS I32; };
.THIS = 5;
.OTHER = 7;
};
AUTO empty := :{};
ASSERT(record.nested.x == 3);
ASSERT(COMPOSITE_FIELD_COUNT(DECLTYPE(empty)) == 0);
A named field is .name = expression or .name: expression. Fields may be
separated by semicolons or commas, with an optional trailing separator. Field
names must be unique. Ordinary identifiers and
the keyword names accepted for named call arguments, including THIS, OTHER,
ARG, and RETURN, are accepted. A valid field name can still be reserved
when the record is used in a call.
Initializer expressions are evaluated once, in source order. The record's
canonical field order places positional members in numeric order first, then
named members in lexicographic order. Access uses ordinary .field
syntax, including nested projections.
Type identity and literal storage¶
Field types preserve initializer expression types, including references. Two composites have the same type exactly when their field names and declared field types match; initializer order is irrelevant:
AUTO first := :{ .z = 9 AS I32; .a = 1 AS I32; };
AUTO second := :{ .a = 4 AS I32; .z = 8 AS I32; };
ASSERT(SAME_TYPES(DECLTYPE(first), DECLTYPE(second)));
An expression naming an ordinary mutable local has type MUT& T, so storing it
directly creates a reference field. An expression producing a pure T creates
an owned field. Existing CONST&, MUT&, TEMP&, and WRITE& field types are
preserved.
Unconverted numeric and string literals retain their exact literal types. They have no stored payload. Numeric literals with different values therefore produce different field types:
AUTO record := :{ .number = 42; .text = "example"; };
ASSERT(SAME_TYPES(COMPOSITE_FIELD_TYPE(DECLTYPE(record), "number"), TYPEOF(42)));
VAR number I32 := record.number;
ASSERT(number == 42);
STATIC_IF (ARCH_IS_LAYOUTLESS == FALSE)
{
ASSERT(SIZEOF(TYPEOF(42)) == 0);
ASSERT(SIZEOF(DECLTYPE(record)) == 0);
}
An explicit conversion such as 42 AS I32 stores an ordinary numeric value. A
field of that type can later hold a different I32. Zero-size literal
fields do not add payload bytes to a containing record; ordinary layout and
alignment rules still apply to its other fields. Layout queries are subject
to the target's layout restrictions.
APPLY¶
The expression form is:
The argument composite is evaluated first, then the callable. Each expression is evaluated once. Positional members become positional arguments and named fields become named arguments; nested composites remain individual values. The expression's result is the result of the call.
::clamp FUNCTION(@value I32, @minimum I32 DEFAULT(0), @maximum I32 DEFAULT(100)): I32
{
IF (value < minimum) { RETURN minimum; }
IF (value > maximum) { RETURN maximum; }
RETURN value;
}
AUTO options := :{ .value = 150; .maximum = 80; };
ASSERT((APPLY options TO clamp) == 80);
Normal parameter adaptation, default arguments, and overload resolution apply.
Field projection uses the source's ordinary reference access.
COMPOSITE_FORWARD exposes owned values as TEMP& arguments.
Functions, procedure pointers, lambdas, bound member functions, and objects
with OPERATOR() are supported. APPLY does not invoke constructors. It rejects a non-composite argument, a
RETURN field, and an explicit THIS field when the callable already supplies
an implicit receiver. A free function may accept an explicitly declared
@THIS parameter. Parenthesize APPLY when using its result as an operand of
another expression.
Named argument capture¶
@KWARGS ... and @KWARGS:name ... declare named argument packs. Their fields
are independent genvalues. The pack reference specifies parameter
capture, expansion, and consuming forwarding.
Static reflection¶
Metadata queries require a composite type, commonly DECLTYPE(record). The
queries also accept a reference to a composite type. Field selectors must
be compile-time constants.
| Operation | Result and arguments |
|---|---|
COMPOSITE_CONTAINS(T, name) |
Boolean indicating whether composite type T has the compile-time string name. |
COMPOSITE_FIELD_COUNT(T) |
Compile-time numeric literal containing the number of fields. |
COMPOSITE_FIELD_NAME(T, index) |
String literal naming the field at the zero-based canonical index. |
COMPOSITE_FIELD_TYPE(T, selector) |
Declared field type, selected by a compile-time string name or unsigned index. |
COMPOSITE_FIELD_GET(value, selector) |
Ordinary field projection from a composite value, selected by name or index. |
Indices enumerate positional members numerically, then named fields
lexicographically, independently of initializer order.
An unknown field or out-of-range index is an error; COMPOSITE_CONTAINS returns
false for an absent name. COMPOSITE_FIELD_TYPE reports the declared field
type, while COMPOSITE_FIELD_GET preserves normal access qualification:
AUTO record := :{ .z = 9 AS I32; .a = 1 AS I32; };
ASSERT(COMPOSITE_CONTAINS(DECLTYPE(record), "a"));
ASSERT(SAME_TYPES(COMPOSITE_FIELD_TYPE(DECLTYPE(record), 0), I32));
ASSERT(SAME_TYPES(TYPEOF(COMPOSITE_FIELD_GET(record, "a")), MUT& I32));
ASSERT(COMPOSITE_FIELD_GET(record, 1) == 9);
STATIC_WHILE provides indexed iteration over heterogeneous fields, as shown
in the Overview.
Reference transforms¶
COMPOSITE_TIE(source) and COMPOSITE_FORWARD(source) evaluate source once
and return a new composite with the same names and reference fields.
| Declared source field | COMPOSITE_TIE |
COMPOSITE_FORWARD |
|---|---|---|
Owned T, mutable source |
MUT& T |
TEMP& T |
Owned T, constant source |
CONST& T |
CONST& T |
| Existing reference | Same reference type | Same reference type |
The transforms are shallow: an owned nested composite becomes a reference to
that composite. They require a readable source and do not copy or move its
owned fields. A WRITE& field already stored inside a readable composite keeps
its qualifier. Neither transform extends the lifetime of referenced objects.
AUTO record := :{ .amount = 5 AS I32; };
AUTO tied := COMPOSITE_TIE(record);
AUTO forwarded := COMPOSITE_FORWARD(record);
ASSERT(SAME_TYPES(COMPOSITE_FIELD_TYPE(DECLTYPE(tied), "amount"), MUT& I32));
ASSERT(SAME_TYPES(COMPOSITE_FIELD_TYPE(DECLTYPE(forwarded), "amount"), TEMP& I32));
tied.amount := 13;
ASSERT(record.amount == 13);
Field transforms¶
| Operation | Result |
|---|---|
COMPOSITE_JOIN(left, right) |
Concatenate positional members and combine disjoint named fields. |
COMPOSITE_SELECT(source, name, ...) |
Only the named fields. |
COMPOSITE_EXCLUDE(source, name, ...) |
All fields except the named fields. |
COMPOSITE_SPLIT(source, name, ...) |
A composite with .selected and .remainder composites. |
Selection names are compile-time strings. Missing names and repeated selection
names are errors. Join rejects named-field collisions. Positional members are
concatenated and renumbered; selection, exclusion, and splitting also renumber
the remaining positional members contiguously from zero. With no names, select returns an empty composite, exclude retains all
fields, and split returns an empty .selected with all fields in .remainder.
Join evaluates its left source before its right source.
Transforms preserve the selected fields' declared types and use ordinary
construction. Owned fields copy from a readable lvalue when copying is
supported, or move from an expiring source when moving is supported. Existing
reference fields retain their bindings. Move-only fields require a suitable
source, for example COMPOSITE_SELECT(MOVE(record), "item").
Splitting does not reassign the storage of the original record's subobjects. To share fields across the results, split a tied or forwarded composite:
AUTO record := :{ .a = 1 AS I32; .b = 2 AS I32; .c = 3 AS I32; };
AUTO parts := COMPOSITE_SPLIT(COMPOSITE_TIE(record), "a", "c");
parts.selected.a := 19;
ASSERT(record.a == 19);
AUTO joined := COMPOSITE_JOIN(parts.selected, parts.remainder);
ASSERT(joined.c<- == record.c<-);
See References, Move Semantics, Call Arguments, and Variadic Packs.
Positional composites and argument unpacking¶
:[a, b] creates a composite with members "0" and "1". The explicit
spelling can mix positional and named members:
Explicit indices must form a contiguous sequence starting at zero, without
duplicates. :[] creates an empty composite. COMPOSITE_FIELD_GET projects a
positional field by index.
COMPOSITE_UNPACK(value) expands a composite inside a call's argument list:
::sum FUNCTION(%left I32, %right I32, @offset I32): I32
{
RETURN left + right + offset;
}
VAR result I32 := sum(COMPOSITE_UNPACK(:[3, 5]), @offset 7);
TEST_ASSERT(result == 15);
Multiple expansions and explicit arguments can be interleaved. Operands are
evaluated once in source order. Positional members append to the positional
argument list; named members must not collide with another supplied name.
RETURN is reserved, and an explicit THIS cannot collide with a bound receiver.
Expansion works in ordinary calls, constructor argument lists, and NEW.
Positional and named argument packs use pack expansion.
Function specialization¶
Inside a function specialization, COMPOSITE_UNPACK(type) accepts a composite
type and expands its field types into specialization arguments:
VAR arguments := :[3 AS I32, 5 AS I32];
VAR selected := sum#(COMPOSITE_UNPACK(TYPEOF(arguments)), @offset I32);
VAR result I32 := selected(COMPOSITE_UNPACK(COMPOSITE_FORWARD(arguments)), @offset 7);
Positional fields preserve their numeric order. Named fields supply the matching parameter names. Duplicate names in the specialization argument list are rejected. Unpacking requires a composite type and a function binding; class and alias template argument lists do not accept specialization unpacking. Specialization selects a callable without evaluating runtime arguments. Invocation performs the selected callable's ordinary parameter conversions and default argument evaluation.