Skip to content

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:

::identity FUNCTION(@ARG:value AUTO& AUTO): DECLTYPE(value)
{
  RETURN FORWARD(value);
}

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 as t.
  • 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:

::box STRUCT
{
  .value VAR I32;

  .get FUNCTION(): MUT& I32
  {
    RETURN .value;
  }
}

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:

VAR value I32 := 9;
VAR reference MUT& I32 := value;
VAR pointer MUT->I32 := reference<-;

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.