Modulo Assignment

The %= operator is a compound assignment operator in Dart, formally known as the modulo assignment operator. It performs a modulo operation using the left-hand and right-hand operands, and assigns the resulting value back to the left-hand operand.

target %= expression;

This syntax is semantically equivalent to the expanded assignment, with the technical distinction that the left-hand target is evaluated only once:

target = target % expression;

Technical Characteristics:

Evaluation Order: Dart evaluates the left-hand expression first to determine the exact assignment target (such as resolving an object reference, property getter, or array index). It then evaluates the right-hand expression, performs the modulo operation against the target’s current value, and finally executes the assignment.
Type Constraints: The left-hand operand must be a mutable variable or a settable property (cannot be const or final after initialization). While natively supported by Dart’s built-in numeric types (int, double, num), the %= operator is not restricted to numbers; it can be applied to any custom class that explicitly overrides operator %.
Euclidean Modulo (Numeric Types): For Dart’s core numeric types, the underlying % operator implements Euclidean division. Consequently, the assigned remainder will always be a non-negative value, regardless of whether the left-hand or right-hand operand is negative.
Division by Zero (Numeric Types): If the right-hand operand evaluates to 0, the operation yields NaN (Not-a-Number) if the left-hand variable is a double, or throws an UnsupportedError if the variable is an int.

Execution Example:

int a = 10;
a %= 3; 
// 1. Evaluates the left-hand target 'a'
// 2. Evaluates 10 % 3, which results in 1
// 3. Assigns 1 back to 'a'

int b = -5;
b %= 3;
// 1. Evaluates the left-hand target 'b'
// 2. Evaluates -5 % 3. Due to Euclidean modulo, the result is 1
// 3. Assigns 1 back to 'b'

// Custom class example
class Vector {
  final int value;
  Vector(this.value);
  
  Vector operator %(int divisor) {
    return Vector(value % divisor);
  }
}

Vector v = Vector(10);
v %= 3; // Valid because Vector implements operator %