Operator overloading in Kotlin
This is a chapter from the book Kotlin Essentials. You can find it on LeanPub.
In Kotlin, we can add an element to a list using the
+ operator. In the same way, we can add two strings together. We can check if a collection contains an element using the
in operator. We can also add, subtract or multiply elements of type
BigDecimal, which is a JVM class that is used to represent possibly big numbers with unlimited precision.
Using operators between objects is possible thanks to the Kotlin feature called operator overloading, which allows special kinds of methods to be defined that can be used as operators. Let's see this in a custom class example.
An example of operator overloading
Let's say that you need to represent complex numbers in your application. These are special kinds of numbers in mathematics that are represented by two parts: real and imaginary. Complex numbers are useful for a variety of kinds of calculations in physics and engineering.
In mathematics, there is a range of operations that we can do on complex numbers. For instance, you can add two complex numbers or subtract a complex number from another complex number. This is done using the
- operators. Therefore, it is reasonable that we should support these operators for our
Complex class. To support the
+ operator, we need to define a method that has an
operator modifier that is called
plus and a single parameter. To support the
- operator, we need to define a method that has an
operator modifier called
minus and a single parameter.
- operators is equivalent to calling the
minus functions. These two can be used interchangeably.
Kotlin defines a concrete set of operators, for each of which there is a specific name and a number of supported arguments. Additionally, all operators need to be a method (so, either a member function or an extension function), and these methods need the
Well-used operators can help us improve our code readability as much as poorly used operators can harm it1. Let's discuss all the Kotlin operators.
Let's start with arithmetic operators, like plus or times. These are easiest for the Kotlin compiler because it just needs to transform the left column to the right.
% translates to
rem, which is a short form of "remainder". This operator returns the remainder left over when one operand is divided by a second operand, so it is similar to the modulo operation0.
Another interesting operator is
rangeTo, thanks to which you can create a range by using two dots between two values. When we use
rangeTo between two numbers of type
Int, the result is
IntRange. To create a
ClosedRange, you can use
.. between any two numbers that are comparable.
The rangeUntil operator
Kotlin 1.7.20 introduced experimental support for a new operator called
rangeUntil, which is basically a replacement for the
until function. It is implemented using the
rangeUntil function and can be used with the
One of my favorite operators is
in. The expression
a in b translates to
b.contains(a). There is also
!in, which translates to negation.
There are a few ways to use this operator. Firstly, for collections, instead of checking if a list contains an element, you can check if the element is in the list.
Why would you do that? Primarily for readability. Would you ask "Does the fridge contain a beer?" or "Is there a beer in the fridge?"? Using the
in operator gives us the possibility to choose.
We also often use the
in operator together with ranges. The expression
1..10 produces an object of type
IntRange, which has a
contains method. This is why you can use
in and a range to check if a number is in this range.
You can make a range from any objects that are comparable, and the result
ClosedRange also has a
contains method. This is why you can use a range check for any objects that are comparable, such as big numbers or objects representing time.
The iterator operator
You can use for-loop to iterate over any object that has an
iterator operator method. Every object that implements an
Iterable interface must support the
You can define objects that can be iterated over, but do not implement
Map is a great example. It does not implement the
Iterable interface, yet you can iterate over it using a for-loop. How so? It is thanks to the
iterator operator, which is defined as an extension function in Kotlin stdlib.
To better understand how a for-loop works, consider the code below.
Under the hood, a for-loop is compiled into bytecode that uses a while-loop to iterate over the object's iterator, as presented in the snippet below.
The equality and inequality operators
In Kotlin, there are two types of equality:
Structural equality - checked with the
equalsmethod or the
==operator (and its negated counterpart
a == btranslates to
ais not nullable, otherwise it translates to
a?.equals(b) ?: (b === null). Structural equality is generally preferred over referential equality. The
equalsmethod can be overridden in custom class.
Referential equality - checked with the
===operator (and its negated counterpart
truewhen both sides point to the same object.
!==(identity checks) are not overloadable.
equals is implemented in
Any, which is the superclass of every class, we can check the equality of any two objects.
Some classes have natural order, which is the order that is used by default when we compare two instances of a given class. Numbers are a good example: 10 is a smaller number than 100. There is a popular Java convention that classes with natural order should implement a
Comparable interface, which requires the
compareTo method, which is used to compare two objects.
As a result, there is a convention that we should compare two objects using the
compareTo method. However, using the
compareTo method directly is not very intuitive. Let's say that you see
a.compareTo(b) > 0 in code. What does it mean? Kotlin simplifies this by making
compareTo an operator that can be replaced with intuitive mathematical comparison operators:
I often use comparison operators to compare amounts kept in objects of type
I also like to compare time references the same way.
The indexed access operator
In programming, there are two popular conventions for getting or setting elements in collections. The first uses box brackets, while the second uses the
set methods. In Java, we use the first convention for arrays and the second one for other kinds of collections. In Kotlin, both conventions can be used interchangeably because the
set methods are operators that can be used with box brackets.
Square brackets are translated to
set calls with appropriate numbers of arguments. Variants of
set functions with more arguments might be used by data processing libraries. For instance, you could have an object that represents a table and use box brackets with two arguments:
When we set a new value for a variable, this new value is often based on its previous value. For instance, we might want to add a value to the previous one. For this, augmented assignments were introduced3. For example,
a += b is a shorter notation of
a = a + b. There are similar notations for other arithmetic operations.
Notice that augmented assignments can be used for all types that support the appropriate arithmetic operation, including lists or strings. Such augmented assignments need a variable to be read-write, namely
var, and the result of the mathematical operation must have a proper type (to translate
a += b to
a = a + b, the variable
a needs to be
a + b needs to be a subtype of type
Augmented assignments can be used in another way: to modify a mutable object. For instance, we can use
+= to add an element to a mutable list. In such a case,
a += b translates to
If both kinds of augmented assignment can be applied, Kotlin chooses to modify a mutable object by default.
Unary prefix operators
A plus, minus, or negation in front of a single value is also an operator. Operators that are used with only a single value are called unary operators4. Kotlin supports operator overloading for the following unary operators:
Here is an example of overloading the
unaryPlus operator is often used as part of Kotlin DSLs, which are described in detail in the next book of this series, Functional Kotlin.
Increment and decrement
As part of many algorithms used in older languages, we often needed to add or subtract the value
1 from a variable, which is why increment and decrement were invented. The
++ operator is used to add
1 to a variable; so, if
a is an integer, then
a++ translates to
a = a + 1. The
-- operator is used to subtract
1 from a variable; so, if
a is an integer, then
a-- translates to
a = a - 1.
Both increment and decrement can be used before or after a variable, and this determines the value returned by this operation.
- If you use
++before a variable, it is called pre-increment; it increments the variable and then returns the result of this operation.
- If you use
++after a variable, it is called post-increment; it increments the variable but then returns the value before the operation.
- If you use
--before a variable, it is called pre-decrement; it decrements the variable and then returns the result of this operation.
- If you use
--after a variable, it is called post-decrement; it decrements the variable but then returns the value before the operation.
Based on the
dec methods, Kotlin supports increment and decrement overloading, which should increment or decrement a custom object. I have never seen this capability used in practice, so I think it is enough to know that it exists.
|Expression||Translates to (simplified)|
The invoke operator
Objects with the
invoke operator can be called like functions, so with parentheses straight after the variable representing this object. Calling an object translates to the
invoke method call with the same arguments.
invoke operator is used for objects that represent functions, such as lambda expressions2 or UseCases objects from Clean Architecture.
What is the result of the expression
1 + 2 * 3? The answer is
9, because in mathematics we multiply before adding. We say that multiplication has higher precedence than addition.
Precedence is also extremely important in programming because when the compiler evaluates an expression such as
1 + 2 == 3, it needs to know if it should first add
2, or compare
3. The following table compares the precedence of all the operators, including those that can be overloaded and those that cannot.
|Highest||Postfix||++, --, . (regular call), ?. (safe call)|
|Prefix||-, +, ++, --, !|
|Type casting||as, as?|
|Multiplicative||*, /, %|
|Named checks||in, !in, is, !is|
|Comparison||<, >, <=, >=|
|Equality||==, !=, ===, !==|
|Lowest||Assignment||=, +=, -=, *=, /=, %=|
On the basis of this table, can you predict what the following code will print?
This is a popular Kotlin puzzle. The answer is
0, because a single minus in front of a function is an operator whose precedence is lower than an explicit
plus method call. So, we first call the method and then call
unaryMinus on the result, therefore we change from
-2. To use
-1 literally, wrap it with parentheses.
We use a lot of operators in Kotlin, many of which can be overloaded. This can be used to improve our code’s readability. From the cognitive standpoint, using an intuitive operator can be a huge improvement over using methods everywhere. Therefore, iit’s good to know what options are available and to be open to using operators defined by Kotlin stdlib, but it’s also good to be able to define our own operators.
This operator was previously called
mod, which comes from "modulo", but this name is now deprecated. In mathematics, both the remainder and the modulo operations act the same for positive numbers, but the difference lies in negative numbers. The result of -5 remainder 4 is -1, because -5 = 4 * (-1) + (-1). The result of -5 modulo 4 is 3, because -5 = 4 * (-2) + 3. Kotlin’s
% operator implements the behavior of remainder, which is why its name needed to be changed from
You can find more about this in Effective Kotlin, Item 12: An operator’s meaning should be consistent with its function name and Item 13: Use operators to increase readability.
There will be more about lambda expressions in the next book of the series, Functional Kotlin.
I am not sure which language introduced augmented assignments first, but they are even supported by languages as old as C.
Unary operators are used with only a single value (operand). Operators used with two values are known as binary operators; however, since most operators are binary, this type is often treated as the default. Operators used with three values are known as ternary operators. Since there is only one ternary operator in mainstream programming languages, namely the conditional operator, it is often referred as the ternary operator.