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.

// 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.

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.

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.

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.

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

Master Kotlin with Deep Grasping Methodology!

Learn More