v0.4.0

Assignment

An assignment stores a new value in a place that already exists — a var, a field, an element, the referent of a writable reference, or the target of a writable pointer.

OperatorMeaning
place = valuecopy value into place
place = move valuemove value into place
place += value, -=, *=, /=, %=place = place + value, and so on
place +%= value, -%=, *%=the wrapping forms
place &= value, |=, ^=the bitwise forms
place <<= value, >>=, >>>=the shift forms
place++, ++placeadd one
place--, --placesubtract one
var n: int32 = 10;
n += 5;
n -= 3;
n *= 4;
n /= 5;
n %= 5;

Each line starts from the result of the one before: 15, 12, 48, 9, 4. A compound arithmetic assignment, ++ and -- are checked like the operators they stand for, so an integer result that does not fit stops the program with Panic: integer overflow in '+=', naming the form written.

The target

The left side must be an assignable place: a variable, a field (p.x), a tuple element (pair.0), an indexed element (values[i]), a name bound to a &var reference, or a dereferenced pointer (*ptr, inside unsafe). And it must be mutable — a var, or something reached through one, a &var reference or a *var pointer:

var p = Point { x: 1, y: 2 };
p.x += 10;
p.y++;
var values: int32[3] = [1, 2, 3];
values[1] *= 7;
TargetError
a letcannot modify immutable variable 'fixed'
a constantcannot modify constant 'Limit'
a value that is not a placeoperator '=' requires an assignable target, but its left operand has type 'int'
through a read-only pointercannot modify data through read-only pointer '*int'

The error for a let comes with help: declare 'fixed' with 'var' to make it mutable. A parameter taken by value cannot be written either: cannot modify parameter 'x', whose help offers taking it as &var T or moving it into a var local.

A name bound to a &var T — a parameter, a receiver taken as &var self, or a let alias — writes through to the caller's storage: func Bump(count: &var int) { count += 1; } increments the argument, and pair = Pair { a: 0, b: 0 }; through pair: &var Pair replaces the caller's value whole. A reference is never reseated, so = through it always writes the referent. Writing through a raw pointer, *ptr = value, needs an unsafe context — see Pointers.

Type rules

The value must have the place's type, or widen to it without loss — an integer of the same signedness and a smaller width, as in a binding. A compound assignment follows the rules of its operator, and its result must still fit the place:

var total: int32 = 0;
let big: int64 = 5;
total += big;
error: operator '+=' produces 'int64', which cannot be stored in target type 'int32'

total += big as int32 converts first. Mixing kinds is refused just as the plain operator would refuse it: on an int32, score += 1.5 is error: operator '+=' cannot combine left operand 'int32' with right operand 'float64', and on a uint8, u += 300 is error: integer literal is out of range for type 'uint8'.

An assignment produces no value

An assignment is a complete action, not a value. The grammar reads a = b = c from the right, as a = (b = c), but b = c has nothing to give a:

first = second = 7;
error: an assignment produces no value and cannot be chained
  help: assign each target in its own statement

For the same reason = cannot stand in for == in a condition: if a = 5 { … } is refused, because the condition is not a bool.

++ and --

++ adds one and -- subtracts one. They apply to any integer or floating-point place, and need it to be mutable like any other assignment: on a let, k++ is error: cannot modify immutable variable 'k'.

On a line of its own, the prefix and postfix forms are the same. Used as a value, they differ in what they hand back:

FormValue of the expressionAfterwards
count++the old valueone higher
++countthe new valueone higher
count--the old valueone lower
--countthe new valueone lower
var count: int32 = 1;
let before = count++;
let after = ++count;
PrintLine("{} {} {}", before, after, count);

This prints 1 3 3. Code that leans on the difference is easy to misread; most Rux code keeps ++ and -- on lines of their own.

Rux has no unary +, so a =+ 3 does not parse; and a =- 3 is a = -3, a valid assignment of minus three. The operator always comes before the =.

Moving with move

place = move value moves instead of copying: the value is handed over and its source may not be read again. The new value is produced first, then the place's old value is destroyed and the new one installed, just as with a copy:

let first = Buffer { size: 4 };
var second = Buffer { size: 0 };
second = move first;

Reading first afterwards is error: value 'first' is used after it was moved. Only plain data copies: a type that owns resources is assigned from a named source with move, or from a copy made with Clone(), and without either it is error: cannot copy 'String', which owns resources. A fresh value, such as a call's result, needs neither. The old arrow, second <- first;, is error: '<-' is not an assignment operator with help: write 'target = move source'. When copy and move apply, and what replacing a value destroys, are covered in Copy and move.

See also