Packs¶
A pack is a generation-time binding containing independent field values. Each field has a name, a type, and a value category. A pack has no aggregate runtime storage. A field can own an object, bind a reference, or contain another pack.
A composite is an ordinary generated struct with aggregate storage. Pack declarations and operations specify argument assembly and ownership transfer.
Declarations and literals¶
PACK named ...{ .first = I32(@OTHER 19), .second = I32(@OTHER 23) };
PACK positional ...[19, 23];
PACK empty ...{};
PACK nested ...{ .arguments = ...{ .value = 42 } };
Named literals accept .name = expression, .name: expression, and numeric
members such as [0] = expression. Fields are evaluated once in source order.
Numeric members are ordered numerically before lexicographically ordered named
members. A literal's numeric members form a contiguous sequence beginning at
zero. Field names are unique.
An owned initializer supplies its genvalue directly. A reference initializer retains its reference type. Pack construction does not construct an intermediate composite or invoke field copy or move constructors. Addressable fields can have ordinary storage independently of other fields. A nested pack initializer transfers the nested pack binding into the new field.
Pack operands are accepted by pack declarations, pack operations, and argument
expansions. An ordinary VAR initializer, value parameter, return value, or
member-access expression requires an ordinary value. PACK name := source;
and pack.field are invalid.
Parameter packs¶
A positional parameter pack uses %...name T. The parameter type TT
accepts the complete supplied type, including its reference category:
::relay FUNCTION(%...values TT, @KWARGS ...): I32
{
RETURN target(...FORWARD PACK(values), ...FORWARD PACK(KWARGS));
}
@KWARGS ... captures unmatched named arguments. @KWARGS:name ... supplies
an explicit local name. Explicit parameters consume their matching arguments
before the named pack is formed. An empty pack is valid.
Named pack parameters¶
A named parameter declared with ... accepts one complete pack. Multiple
named pack parameters can appear in the same function declaration.
::apply FUNCTION(@funcs ..., @args ..., @KWARGS ...): I32
{
VAR callback EMIT FIELD("callback") FROM (funcs);
RETURN FORWARD PACK(args) TO callback;
}
apply(@funcs ...{ .callback = consume },
@args ...{ .value = make_value() },
@option TRUE);
Explicit named pack parameters bind before unmatched named arguments enter
KWARGS. Each parameter has a separate schema and ownership state. The call
passes independent fields through the parameter ABI without an intermediate
composite. Nested packs retain their field structure. Expanding a pack containing named
pack fields supplies those fields to the corresponding named pack parameters.
A bare named pack argument supplies borrowed fields and preserves the caller's
pack. @args FORWARD PACK(arguments) consumes the caller's pack and transfers
its owned fields. A fresh pack literal transfers its fields directly. An
ordinary value cannot bind to a named pack parameter.
Calls and construction¶
PACK arguments ...{ .value = I32(@OTHER 42) };
consume(...arguments);
FORWARD PACK(arguments) TO consume;
...arguments expands a named pack without consuming its binding. Each owned
field is supplied through ordinary lvalue parameter adaptation. Reference
fields retain their declared reference categories. A by-value parameter may
therefore require a copy constructor.
FORWARD PACK(arguments) TO callable consumes the pack and forwards its field
genvalues. The pack operand is evaluated before the callable. Each owned field
can initialize a value parameter directly. Reference fields retain their
reference categories. The source pack cannot subsequently be used.
...FORWARD PACK(arguments) supplies consuming expansion within an argument
list. It is accepted by function calls, constructor calls, constructor
delegates, NEW, and PLACE. A fresh literal expansion such as
consume(...{ .value = make_value() }) also consumes its independent fields.
Duplicate named arguments and reserved RETURN arguments are rejected.
Fusion and fission¶
PACK first ...{ .a = 1, .b = 2 };
PACK selected FISSION FIELDS("b") FROM (first);
PACK combined FUSE(first, selected);
FISSION removes the selected fields from its named source and binds them to
the declared pack. The source becomes the remainder. Each selector is a
compile-time string naming an existing field. Repeated selectors are invalid.
FUSE consumes its source packs and binds their fields to one pack. Named
fields must be unique across the operands. Positional fields are concatenated
in operand order. Both operations transfer genvalues without invoking field
constructors.
Extraction and capture¶
VAR value EMIT FIELD("value") FROM (arguments);
CAPTURE(value) NAMED("renamed") INTO(arguments);
PACK child EMIT FIELD("child") FROM (nested);
EMIT removes one field and binds its existing genvalue to the declared name.
A VAR binding retains the extracted field's type, including a reference type.
A nested pack requires a PACK binding. Extraction does not convert an owned
field to a prvalue or invoke a constructor. The extracted binding owns the field
until that binding is transferred or its scope ends.
CAPTURE removes a named local binding and attaches its genvalue to the named
destination pack. The destination field name is a compile-time string and must
be absent from the destination. Capturing a reference transfers the reference
binding; the referent retains its existing owner. An owned captured value follows
the destination pack's scope. A consumed local name can be declared again.
Inspection¶
| Operation | Result |
|---|---|
PACK_FIELD_COUNT(pack) |
Number of fields. |
PACK_FIELD_NAME(pack, index) |
Field name at a canonical ordinal. |
PACK_FIELD_TYPE(pack, selector) |
Declared field type selected by name or ordinal. |
PACK_CONTAINS(pack, name) |
Whether the schema contains the named field. |
PACK_FIELD_GET(pack, selector) |
Ordinary borrowed access to a field selected by name or ordinal. |
PACK_SIZE(pack) |
Number of fields. |
PACK_ARG(pack, index) |
Ordinary borrowed access to a positional field. |
Selectors and indices are compile-time values. Field access leaves the pack
binding available. A nested pack is extracted with PACK ... EMIT before its
fields are accessed or forwarded.
Type expansion and stored composites¶
...PACK_TYPES(pack) expands the declared field types in a specialization or
callability query. ...PACK_TYPES_EXCEPT(pack, "field", ...) omits selected
fields from that type expansion without changing the pack. Excluded names must
exist and must be unique.
COMPOSITE_TO_PACK(record) creates a pack of field projections from an ordinary
composite. The projections follow the record expression's reference category.
A temporary-qualified record supplies temporary-qualified projections for its
owned fields. Existing reference fields preserve their declared types. The
record and its referents must outlive uses of the projections. This operation
supports invocation of stored argument records.
Lifetime and control flow¶
Each owned field has an independent lifetime. Unconsumed fields are destroyed when their owning scope ends. Consuming invocation transfers owned value arguments to their parameters and retires the source field bindings after the call. A field borrowed during a consuming call is kept alive through the call.
A transfer is rejected when an enclosing exception handler's entry state requires the transferred source to be live. Pack ownership and field selection must agree at control-flow joins. Pack storage and ownership operations are resolved during generation and do not introduce runtime ownership checks.
Coroutine controller hooks receive their ARGUMENTS parameter as a pack.
Ordinary owned call operands are supplied through temporary references so the
calling expression retains their lifetimes across suspension. Explicit named
pack operands preserve their independent field ownership. Frame initialization
applies the coroutine parameter-capture rules when constructing frame storage.
Consuming a pack of
references transfers the reference bindings and does not transfer ownership
of the referenced objects.