> ## 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.
# Kotlin Subtraction Assignment
The `-=` operator is an augmented assignment operator that subtracts the right-hand operand from the left-hand operand and assigns the result back to the left-hand operand. In Kotlin, its behavior is resolved at compile-time based on the mutability of the left-hand operand and the presence of specific operator functions (`minusAssign` or `minus`).
## Compiler Resolution
When the Kotlin compiler encounters `a -= b`, it attempts to resolve the operation in the following order:
1. **`minusAssign` Function:** If the left-hand operand has an accessible `minusAssign` member or extension function that accepts the right-hand operand, the compiler translates the expression to a mutating operation. The return type of `minusAssign` must be `Unit`.
2. **`minus` Function:** If `minusAssign` is not available, the compiler falls back to the standard `minus` operator function. It evaluates `a.minus(b)` and reassigns the result to `a`. This requires `a` to be declared as a mutable variable (`var`).
If both `minusAssign` and `minus` are applicable and `a` is a `var`, the compiler will throw an overload ambiguity error.
```kotlin theme={"dark"}
// Standard syntax
a -= b
// Translation 1: Mutating operation (if minusAssign is defined)
a.minusAssign(b)
// Translation 2: Reassignment operation (if minusAssign is absent)
a = a.minus(b)
```
## Primitive Types
For built-in primitive types (e.g., `Int`, `Double`, `Float`), `-=` performs standard arithmetic subtraction and reassignment. The left-hand operand must be a `var`.
```kotlin theme={"dark"}
var count = 10
count -= 3 // Evaluates to: count = count.minus(3)
```
## Collection Behavior
The `-=` operator exhibits distinct behaviors depending on whether it is applied to a read-only collection or a mutable collection.
**Mutable Collections (`MutableList`, `MutableSet`, etc.)**
The operator resolves to `minusAssign`. It mutates the existing collection in place by removing the specified element. Because the collection instance itself is modified, the reference can be declared as a `val`.
```kotlin theme={"dark"}
val mutableItems = mutableListOf(1, 2, 3)
mutableItems -= 2 // Calls mutableItems.minusAssign(2). Collection is modified in place.
```
**Read-only Collections (`List`, `Set`, etc.)**
The operator resolves to `minus`. It creates a completely new collection containing all elements of the original collection except the subtracted element, and then reassigns the new collection to the variable. The reference must be declared as a `var`.
```kotlin theme={"dark"}
var readOnlyItems = listOf(1, 2, 3)
readOnlyItems -= 2 // Calls readOnlyItems = readOnlyItems.minus(2). New collection allocated.
```
## Operator Overloading
To enable the `-=` operator for custom classes, you must explicitly define the `minusAssign` operator function using the `operator` modifier.
```kotlin theme={"dark"}
class Vector(var x: Int, var y: Int) {
// Defines the behavior for `this -= other`
operator fun minusAssign(other: Vector) {
this.x -= other.x
this.y -= other.y
}
}
val v1 = Vector(5, 5)
val v2 = Vector(2, 3)
v1 -= v2 // v1 is mutated; v1.x becomes 3, v1.y becomes 2
```
Tired of Poor Kotlin Skills? Fix That With Deep Grasping!
Learn More
