What is out keyword in kotlin
The variance modifiers out
and in
allow us to make our generic types less restrictive and more reusable by allowing subtyping.
Let's understand this with the help of contrasting examples. We'll use examples of cases as containers of various weapons. Assume that we have the following type hierarchy:
open class Weapon
open class Rifle : Weapon()
class SniperRifle : Rifle()
out
produces T
and preserves subtyping
When you declare a generic type with an out
modifier, it's called covariant. A covariant is a producer of T
, that means functions can return T
but they can't take T
as arguments:
class Case<out T> {
private val contents = mutableListOf<T>()
fun produce(): T = contents.last() // Producer: OK
fun consume(item: T) = contents.add(item) // Consumer: Error
}
The Case
declared with the out
modifier produces T
and its subtypes:
fun useProducer(case: Case<Rifle>) {
// Produces Rifle and its subtypes
val rifle = case.produce()
}
With the out
modifier, the subtyping is preserved, so the Case<SniperRifle>
is a subtype of Case<Rifle>
when SniperRifle
is a subtype of Rifle
. As a result, the useProducer()
function can be called with Case<SniperRifle>
too:
useProducer(Case<SniperRifle>()) // OK
useProducer(Case<Rifle>()) // OK
useProducer(Case<Weapon>()) // Error
This is less restrictive and more reusable while producing but our class becomes read only.
in
consumes T
and reverses subtyping
When you declare a generic type with an in
modifier, it's called contravariant
. A contravariant is a consumer of T
, that means functions can take T
as arguments but they can't return T
:
class Case<in T> {
private val contents = mutableListOf<T>()
fun produce(): T = contents.last() // Producer: Error
fun consume(item: T) = contents.add(item) // Consumer: OK
}
The Case
declared with the in
modifier consumes T
and its subtypes:
fun useConsumer(case: Case<Rifle>) {
// Consumes Rifle and its subtypes
case.consume(SniperRifle())
}
With the in
modifier, the subtyping is reversed, so now the Case<Weapon>
is a subtype of Case<Rifle>
when Rifle
is a subtype of Weapon
. As a result, the useConsumer()
function can be called with Case<Weapon>
too:
useConsumer(Case<SniperRifle>()) // Error
useConsumer(Case<Rifle>()) // OK
useConsumer(Case<Weapon>()) // OK
This is less restrictive and more reusable while consuming but our class becomes write only.
Invariant produces and consumes T
, disallows subtyping
When you declare a generic type without any variance modifier, it's called invariant. An invariant is a producer as well as a consumer of T
, that means functions can take T
as arguments and can also return T
:
class Case<T> {
private val contents = mutableListOf<T>()
fun produce(): T = contents.last() // Producer: OK
fun consume(item: T) = contents.add(item) // Consumer: OK
}
The Case
declared without in
or out
modifier produces and consumes T
and its subtypes:
fun useProducerConsumer(case: Case<Rifle>) {
// Produces Rifle and its subtypes
case.produce()
// Consumes Rifle and its subtypes
case.consume(SniperRifle())
}
Without the in
or out
modifier, the subtyping is disallowed, so now neither Case<Weapon>
nor Case<SniperRifle>
is a subtype of Case<Rifle>
. As a result, the useProducerConsumer()
function can only be called with Case<Rifle>
:
useProducerConsumer(Case<SniperRifle>()) // Error
useProducerConsumer(Case<Rifle>()) // OK
useProducerConsumer(Case<Weapon>()) // Error
This is more restrictive and less reusable while producing and consuming but we can read and write.
Conclusion
The List
in Kotlin is a producer only. Because it's declared using the out
modifier: List<out T>
. This means you cannot add elements to it as the add(element: T)
is a consumer function. Whenever you want to be able to get()
as well as add()
elements, use the invariant version MutableList<T>
.
That's it! Hopefully that helps understand the in
s and out
s of the variance!
List<out T>
in Kotlin is equivalent to List<? extends T>
in Java.
List<in T>
in Kotlin is equivalent to List<? super T>
in Java
For example in Kotlin you can do things like
val value : List<Any> = listOf(1,2,3)
//since List signature is List<out T> in Kotlin
The reasoning is you can mark generic "out" if you returning it, but never receiving. And you can mark it "in" if you receive it, but never return.