When should you reach for a use-site projection (Array<out T>) versus declaration-site variance, and why can't Array itself be declared covariant?

## Two ways to introduce variance Kotlin offers variance at two levels: 1. **Declaration-site variance** — annotate the class's type parameter once: `class Source<out T>` or `interface Sink<in T>`. Every usage is automatically variant; callers write no extra keywords. 2. **Use-site projection (type projection)** — annotate a single usage: `fun f(a: Array<out T>)`. Variance applies only at that spot. ## When declaration-site variance is possible A class can be declared `out T` (covariant) only if `T` appears **exclusively in out positions** (return types) across all its public members — i.e., it is a pure **producer**. It can be `in T` (contravariant) only if `T` appears **exclusively in in positions** (parameters) — a pure **consumer**. The Kotlin compiler enforces this; it rejects `class Box<out T> { fun set(t: T) }` with a variance error. ## Why Array must stay invariant `Array<T>` exposes both: ```kotlin operator fun get(index: Int): T // T in OUT position operator fun set(index: Int, value: T) // T in IN position ``` Because `T` appears in **both** positions, the class is **invariant by necessity** — it cannot be declared `out` or `in` without becoming unsound. If `Array<Int>` were silently usable as `Array<Any>`, a `set(i, "x")` would corrupt it. The same is true of `MutableList<T>` and most mutable containers. ## The decision rule - The class is **naturally one-directional** and **you own it** → use **declaration-site variance**. Example: a read-only `interface Producer<out T> { fun next(): T }`. - The class is **invariant by necessity** (mutable, reads + writes) **or third-party / not annotatable** → use a **use-site projection** at each call site that needs one direction. - You only need the directional view in **one function**, not everywhere → projection keeps the restriction local. ```kotlin // Declaration-site: Producer is always covariant interface Producer<out T> { fun produce(): T } val p: Producer<Any> = object : Producer<String> { override fun produce() = "hi" } // OK // Use-site: Array stays invariant; project only where needed fun copyInto(dest: Array<in Any>, src: Array<out Any>) { for (i in src.indices) dest[i] = src[i] } ``` ## Trade-offs - Declaration-site is **DRY**: declared once, free everywhere; but only legal for one-directional types. - Use-site is **flexible and local**: works on any type including invariant ones and types you cannot modify; but you repeat the annotation at each site and lose the other direction's members there. ## Mental model Reach for declaration-site variance first when you control the type and it is purely producer or consumer. Reach for a projection when the type genuinely needs both `get` and `set` (so it must be invariant) but a given call site only needs one half.