Skip to content

Overview of References

A reference gives non-owning access to an existing object. Its qualifier says whether that access is mutable, read-only, expiring, or output-only.

VAR value I32 := 7;
VAR mutable_reference MUT& I32 := value;
VAR constant_reference CONST& I32 := value;

mutable_reference := 8;
ASSERT(constant_reference == 8);

Reference qualifiers

  • MUT& T reads and modifies an existing T.
  • CONST& T reads without modifying through that reference.
  • TEMP& T marks an expiring source that may be moved from.
  • WRITE& T is an output destination whose previous value is not input.
  • AUTO& T deduces an incoming reference qualifier.

WRITE& declares a pure output parameter:

::split FUNCTION(@value I32, @high WRITE& I32, @low WRITE& I32)
{
  high := value / 10;
  low := value % 10;
}

Forwarding and returned references

AUTO& AUTO deduces both qualifier and target type. FORWARD preserves the deduced category:

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

A function can return a reference to existing storage:

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

References do not own or extend the lifetime of their targets. An existing invalidated reference may be retained without being used. Any use of it is undefined behavior, including accessing an object through it, creating a new reference from it, copying it, or taking its address with postfix <-. A pointer represents an association that may be null. Copying an invalidated pointer is well-defined; dereferencing it is undefined behavior.

Reference

See the References Reference for binding and qualification rules, output references, deduction patterns, forwarding, returned-reference lifetime, and conversion to pointer form.