Kotlin has a robust type system, but one of the trickiest concepts to grasp is contravariance. If you’ve ever scratched your head wondering how contravariance works and why it’s useful, you’re in the right place. This blog will break it down in simple terms with examples so you can fully understand Kotlin contravariance and use it effectively in your projects.

Understanding Variance in Kotlin

Before diving into Kotlin contravariance, let’s briefly cover variance. Variance determines how subtyping relationships between generic types work. Kotlin has three main types:

1. Invariance (T) – No subtyping allowed.
2. Covariance (out T) – Allows a subtype to be returned but not consumed.
3. Contravariance (in T) – Allows a supertype to be accepted as input.

Contravariance is often misunderstood because it involves a reversed subtyping rule. Let’s break it down.

Contravariance: reversed subtyping relation

Contravariance is the opposite of covariance and it can be understood as a mirror image of covariance. When a class is contravariant, the subtyping relationship between its type arguments is the reverse of the subtyping relationship between the classes themselves.

To illustrate this concept, let’s consider the example of the Comparator interface. This interface has a single method called compare, which takes two objects and compares them:

interface Comparator<in T> {
    fun compare(e1: T, e2: T): Int { ... }
}

In this case, you’ll notice that the compare method only consumes values of type T. This means that the type parameter T is used in “in” positions only, indicating that it is a contravariant type. To indicate contravariance, the “in” keyword is placed before the declaration of T.

A comparator defined for values of a certain type can, of course, compare the values of any subtype of that type. For example, if you have a Comparator, you can use it to compare values of any specific type.

val anyComparator = Comparator<Any> { e1, e2 -> e1.hashCode() - e2.hashCode() }

val strings: List<String> = listOf("abc","xyz")
strings.sortedWith(anyComparator)     // You can use the comparator for any objects to compare specific objects, such as strings.

Here, the sortedWith function expects a Comparator (a comparator that can compare strings), and it’s safe to pass one that can compare more general types. If you need to perform comparisons on objects of a certain type, you can use a comparator that handles either that type or any of its supertypes. This means Comparator<Any> is a subtype of Comparator<String>, where Any is a supertype of String. The subtyping relation between comparators for two different types goes in the opposite direction of the subtyping relation between those types.

What is contravariance?

A class that is contravariant on the type parameter is a generic class (let’s consider Consumer<T> as an example) for which the following holds: Consumer<A> is a subtype of Consumer<B> if B is a subtype of A. The type arguments A and B changed places, so we say the subtyping is reversed. For example, Consumer<Animal> is a subtype of Consumer<Cat>.

In simple words, contravariance in Kotlin means that the subtyping relationship between two generic types is reversed compared to the normal inheritance hierarchy. If B is a subtype of A, then a generic class or interface that is contravariant on its type parameter T will have the relationship ClassName<A> is a subtype of ClassName<B>.

For a covariant type Producer, the subtyping is preserved, but for a contravariant type Consumer, the subtyping is reversed

Here, we see the difference between the subtyping relation for classes that are covariant and contravariant on a type parameter. You can see that for the Producer class, the subtyping relation replicates the subtyping relation for its type arguments, whereas for the Consumer class, the relation is reversed.

The “in” keyword means values of the corresponding type are passed in to methods of this class and consumed by those methods. Similar to the covariant case, constraining use of the type parameter leads to the specific subtyping relation. The “in” keyword on the type parameter T means the subtyping is reversed and T can be used only in “in” positions.

When to Use Contravariance

Contravariance is useful when designing APIs that consume values. It is commonly used in:

• Event handlers
• Callbacks and listeners
• Comparator implementations (Comparator<in T>)

Conclusion

Kotlin contravariance can be tricky at first, but once you understand its reversed subtyping rule, it becomes a powerful tool for designing flexible and reusable APIs. By using the in keyword, you allow broader types to be used while ensuring type safety.

Next time you design a consumer-style interface, consider whether Kotlin contravariance could make your code more robust.