Generics

As in Java, classes in Kotlin may have type parameters:

class Box<T>(t: T) {
    var value = t
}

In general, to create an instance of such a class, we need to provide the type arguments:

val box: Box<Int> = Box<Int>(1)

But if the parameters may be inferred, e.g. from the constructor arguments or by some other means, one is allowed to omit the type arguments:

val box = Box(1) // 1 has type Int, so the compiler figures out that we are talking about Box<Int>

Variance

One of the most tricky parts of Java’s type system is wildcard types (see Java Generics FAQ). And Kotlin doesn’t have any. Instead, it has two other things: declaration-site variance and type projections.

First, let’s think about why Java needs those mysterious wildcards. The problem is explained in Effective Java, 3rd Edition, Item 31: Use bounded wildcards to increase API flexibility. First, generic types in Java are invariant, meaning that List<String> is not a subtype of List<Object>

Why so? If List was not invariant, it would have been no better than Java’s arrays, since the following code would have compiled and caused an exception at runtime:

// Java
List < String > strs = new ArrayList < String >();
List < Object > objs = strs; // !!! The cause of the upcoming problem sits here. Java prohibits this!
objs.add(1); // Here we put an Integer into a list of Strings
String s = strs.get(0); // !!! ClassCastException: Cannot cast Integer to String

So, Java prohibits such things in order to guarantee run-time safety. But this has some implications. For example, consider the addAll() method from Collection interface. What’s the signature of this method? Intuitively, we’d put it this way:

// Java
interface Collection<E> ... {
  void addAll(Collection<E> items);
}

But then, we can’t do the following simple thing (which is perfectly safe):

// Java
void copyAll(Collection<Object> to, Collection<String> from) {
  to.addAll(from);
  // !!! Would not compile with the naive declaration of addAll:
  // Collection<String> is not a subtype of Collection<Object>
}

(In Java, we learned this lesson the hard way, see Effective Java, 3rd Edition, Item 28: Prefer lists to arrays)

That’s why the actual signature of addAll() is the following:

// Java
interface Collection<E> ... {
  void addAll(Collection<? extends E> items);
}

The **wildcard type argument** ? extends E--- indicates that this method accepts a collection of objects of E or some subtype of E, not just E itself. This means that we can safely read E’s from items (elements of this collection are instances of a subclass of E), but cannot write to it since we do not know what objects comply to that unknown subtype of E. In return for this limitation, we have the desired behaviour: Collection is a subtype of Collection<? extends Object>. In “clever words”, the wildcard with an extends-bound (upper bound) makes the type covariant.

The key to understanding why this trick works is rather simple: if you can only take items from a collection, then using a collection of Strings and reading Objects from it is fine. Conversely, if you can only put items into the collection, it’s OK to take a collection of Objects and put Strings into it: in Java we have

List<? super String> a supertype of List<Object>.

The latter is called contravariance, and you can only call methods that take String as an argument on

List<? super String> 

(e.g., you can call add(String) or set(int, String)), while if you call something that returns T in List, you don’t get a String, but an Object.

Joshua Bloch calls those objects you only read from Producers, and those you only write to Consumers. He recommends: “For maximum flexibility, use wildcard types on input parameters that represent producers or consumers”, and proposes the following mnemonic:

PECS stands for Producer-Extends, Consumer-Super.

NOTE: if you use a producer-object, say,

List<? extends Foo>

-you are not allowed to call add() or set() on this object, but this does not mean that this object is immutable: for example, nothing prevents you from calling clear() to remove all items from the list, since clear() does not take any parameters at all. The only thing guaranteed by wildcards (or other types of variance) is type safety. Immutability is a completely different story.

Declaration-site variance

Suppose we have a generic interface Source that does not have any methods that take T as a parameter, only methods that return T:

// Java
interface Source<T> {
  T nextT();
}

Then, it would be perfectly safe to store a reference to an instance of Source in a variable of type Source