Remainder Assignment

The %= operator is the augmented assignment operator for the remainder operation. It evaluates the remainder of the division of the left-hand operand by the right-hand operand and assigns that computed value back to the left-hand operand.

Syntax and Desugaring

In Kotlin, a %= b is not a primitive language construct but is syntactically translated by the compiler into a corresponding function call. The resolution mechanism depends on the mutability of the left-hand operand and the available operator functions.

During compilation, the Kotlin compiler resolves this operator using the following rules:

1. remAssign Resolution: The compiler first looks for an operator member or extension function named remAssign on the left-hand operand’s type. If found, a %= b is desugared to an in-place mutation:

a.remAssign(b)

Because this is an in-place mutation, the left-hand operand a can be a read-only reference (val), provided the object itself is mutable and the function modifies its internal state. 2. rem Fallback: If remAssign is not defined, the compiler falls back to the standard remainder operator function rem. In this scenario, a %= b is desugared to a reassignment:

a = a.rem(b)

For this fallback to compile, the left-hand operand a is strictly required to be a mutable reference (var), and the return type of rem must be assignable to the declared type of a. 3. Ambiguity Error: If both remAssign and rem are applicable (i.e., both functions are defined and the left-hand operand is a var), the compiler does not silently prioritize remAssign. Instead, it throws an assignment operator ambiguity error because it cannot safely determine whether to mutate the existing object or reassign the variable to a new object.

Technical Characteristics

• Remainder vs. Modulo: Kotlin explicitly defines this as a remainder operation (rem), replacing the deprecated mod function from earlier versions. The sign of the result strictly follows the sign of the dividend (the left-hand operand). For example, -5 %= 3 results in -2, whereas a true mathematical Euclidean modulo would result in 1.
• Return Type: The %= operation is a statement, not an expression. When implemented via remAssign, the function must return Unit. Consequently, the operator cannot be chained or assigned to another variable (e.g., val c = (a %= b) is a compilation error).
• Type Constraints: When the compiler utilizes the a = a.rem(b) fallback, if a.rem(b) returns a wider type (e.g., a is Int, b is Long), the compiler will throw a type mismatch error.

Operator Overloading

To enable the %= operator for custom types, you must explicitly overload the remAssign function using the operator keyword.

class Scalar(var value: Int) {
    // Overloading the %= operator
    operator fun remAssign(divisor: Int) {
        this.value = this.value.rem(divisor)
    }
}

// A read-only reference (val) is permitted because remAssign mutates internal state
val scalar = Scalar(14)
scalar %= 4 // Desugars to scalar.remAssign(4)

Master Kotlin with Deep Grasping Methodology!

Learn More