References¶
A reference is a non-owning, non-null association with an existing Quxlang object. Its qualifier describes the access and value category carried by that association.
| Form | Contract |
|---|---|
MUT& T or &T |
Read and modify an existing T. |
CONST& T |
Read an existing T without modifying it through this reference. |
TEMP& T |
Refer to an expiring T that may be consumed or moved from. |
WRITE& T |
Initialize or replace a T without requiring a readable input value. |
AUTO& T |
Deduce the incoming reference qualifier while matching target type T. |
References do not own their target and do not extend its lifetime.
Binding references¶
A reference initializer must identify compatible live storage:
VAR value I32 := 7;
VAR mutable_reference MUT& I32 := value;
VAR constant_reference CONST& I32 := value;
mutable_reference := 8;
ASSERT(constant_reference == 8);
MUT& requires mutable access. CONST& may bind where a read-only view is
valid. Reference qualification participates in overload resolution, so an API
can distinguish mutable, constant, and expiring arguments.
::inspect FUNCTION(@ARG:value CONST& record)
{
use(value);
}
::update FUNCTION(@ARG:value MUT& record)
{
value.revision++;
}
WRITE& output references¶
WRITE& is for a destination whose previous value is not part of the
function's input contract:
::divide FUNCTION(@numerator I32, @denominator I32,
@quotient WRITE& I32, @remainder WRITE& I32)
{
quotient := numerator / denominator;
remainder := numerator % denominator;
}
The callee must establish a valid result before an operation that requires the
destination to be readable. WRITE& is not a mutable-input reference spelled
differently; use MUT& when the old value is an input.
Temporary references and forwarding¶
TEMP& marks an expiring source and is the reference category used by move
conversion constructors. A forwarding parameter combines reference-category
and type deduction:
AUTO& AUTO means: deduce the reference qualifier and deduce the referenced
type. FORWARD(value) preserves the deduced category. Returning value
directly would treat the named parameter as an ordinary named expression and
would not express the same forwarding contract.
See Move Semantics and Type Queries.
Reference deduction patterns¶
Reference forms may contain type patterns:
AUTO& AUTO(t)deduces the qualifier and the non-reference target ast.AUTO& TT(t)can retain a type pattern that includes reference information where the surrounding declaration accepts it.CONST& AUTO(t)fixes const access while deducing the target type.TEMP& AUTO(t)fixes the expiring category while deducing the target type.
These are template-matching forms, not runtime reference objects with unknown types.
Member and return references¶
A member function can return a reference to storage owned by its receiver:
The reference becomes invalid when the box object's lifetime ends. Retaining
an existing invalidated reference without using it is permitted. Any use of an
invalidated reference is undefined behavior, including accessing an object
through it, creating a new reference from it, copying it, or taking its address
with postfix <-. The same rule applies to references to array
elements, references obtained by iterator dereference, and references returned
by user-defined operators.
References and object state¶
A reference itself is not nullable. A Pointer represents an
association that may be absent or may be reseated as a stored value. Creating a
pointer with postfix <- preserves a reference to the same object but changes
the type-level contract from non-null reference to pointer:
Copying an invalidated pointer is well-defined. Dereferencing it is undefined behavior, including dereferencing it to create a new reference. Any use of an invalidated reference, including copying it or taking its address, is undefined behavior.
Named temporary references¶
Naming a captured TEMP& T binding gives ordinary mutable access to its object.
FORWARD(binding) recovers the declared forwarding category.
MOVE(binding) requests an expiring reference explicitly.
External access qualification¶
IBC precedes a reference qualifier, as in IBC MUT& I32 or
IBC CONST& I32. Adding or removing it requires an explicit cast.
AUTO& deduction preserves it. See External Memory.