Operator overloading in Kotlin

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.

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 + and - 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.

Using the + and - operators is equivalent to calling the plus and 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 operator modifier.

Well-used operators can help us improve our code readability as much as poorly used operators can harm it¹. 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.

Notice that % 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 operation⁰.

It is also worth mentioning .. and ..< operators, that are used to create ranges. We can use them between integers to create IntRange, over which we can iterate in for-loop. We can also use those operators between any values that implement Comparable interface, to define a range by extremes of this range.

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.

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 iterator method.

You can define objects that can be iterated over, but do not implement Iterable interface. 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.

In Kotlin, there are two types of equality:

Since 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: >, <, >=, and <=.

I often use comparison operators to compare amounts kept in objects of type BigDecimal or BigInteger.

I also like to compare time references the same way.

In programming, there are two popular conventions for getting or setting elements in collections. The first uses box brackets, while the second uses the get and 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 get and set methods are operators that can be used with box brackets.

Square brackets are translated to get and set calls with appropriate numbers of arguments. Variants of get and 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: x and y coordinates.

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 introduced³. 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 var, and a + b needs to be a subtype of type a).

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 a.plusAssign(b).

If both kinds of augmented assignment can be applied, Kotlin chooses to modify a mutable object by default.

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 operators⁴. Kotlin supports operator overloading for the following unary operators:

Here is an example of overloading the unaryMinus operator.

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.

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.

Based on the inc and 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.

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.

The invoke operator is used for objects that represent functions, such as lambda expressions² or UseCases objects from Clean Architecture.

What is the result of the expression 1 + 2 * 3? The answer is 7, not 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 1 to 2, or compare 2 and 3. The following table compares the precedence of all the operators, including those that can be overloaded and those that cannot.

On the basis of this table, can you predict what the following code will print?

This is a popular Kotlin puzzle. The answer is -2, not 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 -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.