> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dart Subtraction Assignment
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.
```dart theme={"dark"}
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.
```dart theme={"dark"}
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.
```dart theme={"dark"}
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
