Skip to main content
The -= operator is a compound assignment operator in Dart, specifically known as the subtraction assignment operator. It subtracts the value of the right-hand expression from the current value of the left-hand assignable expression and assigns the resulting value back to that left-hand target. 
target -= expression;
While conceptually similar to target = target - expression, the -= operator evaluates the left-hand side exactly once. This distinction is critical when the left operand is a complex expression with side effects. For example, list[i++] -= 1 evaluates the index i only once, whereas list[i++] = list[i++] - 1 evaluates i twice, leading to divergent logical outcomes.

​
Technical Characteristics

Evaluation Order Dart enforces strict left-to-right evaluation. The execution sequence for a compound assignment like LHS -= RHS strictly follows these steps:
  1. Evaluate the left-hand side (LHS) to determine the target (e.g., a variable binding, property access, or index expression), and immediately read its current value (invoking the getter or indexer if applicable). The LHS expression is evaluated exactly once.
  2. Evaluate the right-hand side (RHS) expression.
  3. Invoke the - operator on the previously read LHS value, passing the evaluated RHS value as the argument.
  4. Assign the resulting value back to the LHS target (invoking the setter or index assignment if applicable).
Because the LHS value is read prior to the RHS evaluation, any state changes triggered by the RHS expression will not affect the initial value used for the subtraction. Mutability Requirements The left operand must be an assignable expression. This includes mutable local variables, class properties with setters, and collection index expressions. Attempting to use -= on a target that cannot be reassigned—such as a variable declared as final or const, or a getter-only property—results in a compile-time error. In Dart, variables and properties act as bindings that hold references to objects. The assignment phase of the -= operator requires that the target binding can be updated to point to the newly computed reference. Type Safety and Casting Dart’s static typing rules apply strictly to the assignment phase of the -= operator. The result of the subtraction operation must be assignable to the declared static type of the left operand. 
int x = 10;
x -= 3; // Valid: x becomes 7

double y = 10.5;
y -= 2; // Valid: y becomes 8.5 (int 2 is implicitly handled by double subtraction)

int z = 5;
// z -= 1.5; // Compile-time error: The result of int - double is double, which cannot be assigned to int.
Operator Overloading Dart does not permit direct overriding of the -= operator. Instead, -= is automatically derived from the - operator. To use -= with instances of a custom class, the class must override operator -. The return type of the overridden operator - must be compatible with the static type of the left operand to satisfy assignment rules. 
class Vector {
  final int x;
  Vector(this.x);

  // Overriding the subtraction operator implicitly enables -=
  Vector operator -(Vector other) {
    return Vector(this.x - other.x);
  }
}

void main() {
  Vector v1 = Vector(10);
  Vector v2 = Vector(3);
  
  v1 -= v2; // Valid: Reads v1, evaluates v2, subtracts, and reassigns the new Vector to v1
}
Tired of Poor Dart Skills? Fix That With Deep Grasping!Learn More