C# examples

For example, in C#, if CatCategory:Articles with example C Sharp code is a subtype of AnimalCategory:Articles with example C Sharp code, then:

• IEnumerable<Cat>Category:Articles with example C Sharp code is a subtype of IEnumerable<Animal>Category:Articles with example C Sharp code. The subtyping is preserved because IEnumerable<T>Category:Articles with example C Sharp code is covariant on TCategory:Articles with example C Sharp code.
• Action<Animal>Category:Articles with example C Sharp code is a subtype of Action<Cat>Category:Articles with example C Sharp code. The subtyping is reversed because Action<T>Category:Articles with example C Sharp code is contravariant on TCategory:Articles with example C Sharp code.
• Neither IList<Cat>Category:Articles with example C Sharp code nor IList<Animal>Category:Articles with example C Sharp code is a subtype of the other, because IList<T>Category:Articles with example C Sharp code is invariant on TCategory:Articles with example C Sharp code.

The variance of a C# generic interface is declared by placing the outCategory:Articles with example C Sharp code (covariant) or inCategory:Articles with example C Sharp code (contravariant) attribute on (zero or more of) its type parameters.^[2]: 144 The above interfaces are declared as IEnumerable<out T>Category:Articles with example C Sharp code, Action<in T>Category:Articles with example C Sharp code, and IList<T>Category:Articles with example C Sharp code. Types with more than one type parameter may specify different variances on each type parameter. For example, the delegate type Func<in T, out TResult>Category:Articles with example C Sharp code represents a function with a contravariant input parameter of type TCategory:Articles with example C Sharp code and a covariant return value of type TResultCategory:Articles with example C Sharp code.^{[3][2]: 145} The compiler checks that all types are defined and used consistently with their annotations, and otherwise signals a compilation error.

The typing rules for interface variance ensure type safety. For example, an Action<T>Category:Articles with example C Sharp code represents a first-class function expecting an argument of type TCategory:Articles with example C Sharp code,^[2]: 144 and a function that can handle any type of animal can always be used instead of one that can only handle cats.

Covariant arrays in Java and C#

Early versions of Java and C# did not include generics, also termed parametric polymorphism. In such a setting, making arrays invariant rules out useful polymorphic programs.

For example, consider writing a function to shuffle an array, or a function that tests two arrays for equality using the Object.equals Category:Articles with example Java code method on the elements. The implementation does not depend on the exact type of element stored in the array, so it should be possible to write a single function that works on all types of arrays. It is easy to implement functions of type:

boolean equalArrays(Object[] a1, Object[] a2);
void shuffleArray(Object[] a);

However, if array types were treated as invariant, it would only be possible to call these functions on an array of exactly the type Object[] Category:Articles with example Java code. One could not, for example, shuffle an array of strings.

Therefore, both Java and C# treat array types covariantly. For instance, in Java String[] Category:Articles with example Java code is a subtype of Object[] Category:Articles with example Java code, and in C# string[]Category:Articles with example C Sharp code is a subtype of object[]Category:Articles with example C Sharp code.

As discussed above, covariant arrays lead to problems with writes into the array. Java^[4]: 126 and C# deal with this by marking each array object with a type when it is created. Each time a value is stored into an array, the execution environment will check that the run-time type of the value is equal to the run-time type of the array. If there is a mismatch, an ArrayStoreException Category:Articles with example Java code (Java)^[4]: 126 or ArrayTypeMismatchExceptionCategory:Articles with example C Sharp code (C#) is thrown:

// a is a single-element array of String
String[] a = new String[1];

// b is an array of Object
Object[] b = a;

// Assign an Integer (int) to b. This would be possible if b were actually
// an array of Object, but since it really is an array of String,
// we will get a java.lang.ArrayStoreException at runtime.
b[0] = 1;

In the above example, one can read from the array (b) safely. It is only trying to write to the array that can lead to trouble.

One drawback to this approach is that it leaves the possibility of a run-time error that a stricter type system could have caught at compile-time. Also, it hurts performance because each write into an array requires an additional run-time check.

With the addition of generics, Java^{[4]: 126–129} and C# now offer ways to write this kind of polymorphic function without relying on covariance. The array comparison and shuffling functions can be given the parameterized types

<T> boolean equalArrays(T[] a1, T[] a2);
<T> void shuffleArray(T[] a);

Alternatively, to enforce that a C# method accesses a collection in a read-only way, one can use the interface IEnumerable<object>Category:Articles with example C Sharp code instead of passing it an array object[]Category:Articles with example C Sharp code.

Covariant method return type

In a language which allows covariant return types, a derived class can override the getAnimalForAdoption Category:Articles with example Java code method to return a more specific type:

class CatShelter extends AnimalShelter {

    Cat getAnimalForAdoption() {
        return new Cat();
    }
}

Among mainstream OO languages, Java, C++ and C# (as of version 9.0 ^[7]) support covariant return types. Adding the covariant return type was one of the first modifications of the C++ language approved by the standards committee in 1998.^[8] Scala and D also support covariant return types.

Contravariant method parameter type

Similarly, it is type safe to allow an overriding method to accept a more general argument than the method in the base class:

class CatShelter extends AnimalShelter {
    void putAnimal(Object animal) {
        // ...
    }
}

Only a few object-oriented languages actually allow this (for example, Python when typechecked with mypy). C++, Java and most other languages that support overloading and/or shadowing would interpret this as a method with an overloaded or shadowed name.

However, Sather supported both covariance and contravariance. Calling convention for overridden methods are covariant with out parameters and return values, and contravariant with normal parameters (with the mode in).

Covariant method parameter type

A couple of mainstream languages, Eiffel and Dart^[9] allow the parameters of an overriding method to have a more specific type than the method in the superclass (parameter type covariance). Thus, the following Dart code would type check, with putAnimal Category:Articles with example Java code overriding the method in the base class:

class CatShelter extends AnimalShelter {

    void putAnimal(covariant Cat animal) {
        // ...
    }
}

This is not type safe. By up-casting a CatShelter Category:Articles with example Java code to an AnimalShelter Category:Articles with example Java code, one can try to place a dog in a cat shelter. That does not meet CatShelter Category:Articles with example Java code parameter restrictions and will result in a runtime error. The lack of type safety (known as the "catcall problem" in the Eiffel community, where "cat" or "CAT" is a Changed Availability or Type) has been a long-standing issue. Over the years, various combinations of global static analysis, local static analysis, and new language features have been proposed to remedy it,^[10][11] and these have been implemented in some Eiffel compilers.

Despite the type safety problem, the Eiffel designers consider covariant parameter types crucial for modeling real world requirements.^[11] The cat shelter illustrates a common phenomenon: it is a kind of animal shelter but has additional restrictions, and it seems reasonable to use inheritance and restricted parameter types to model this. In proposing this use of inheritance, the Eiffel designers reject the Liskov substitution principle, which states that objects of subclasses should always be less restricted than objects of their superclass.

One other instance of a mainstream language allowing covariance in method parameters is PHP in regards to class constructors. In the following example, the __construct() method is accepted, despite the method parameter being covariant to the parent's method parameter. Were this method anything other than __construct(), an error would occur:

interface AnimalInterface {}


interface DogInterface extends AnimalInterface {}


class Dog implements DogInterface {}


class Pet
{
    public function __construct(AnimalInterface $animal) {}
}


class PetDog extends Pet
{
    public function __construct(DogInterface $dog)
    {
        parent::__construct($dog);
    }
}

Another example where covariant parameters seem helpful is so-called binary methods, i.e. methods where the parameter is expected to be of the same type as the object the method is called on. An example is the compareTo Category:Articles with example Java code method: a.compareTo(b) Category:Articles with example Java code checks whether a Category:Articles with example Java code comes before or after b Category:Articles with example Java code in some ordering, but the way to compare, say, two rational numbers will be different from the way to compare two strings. Other common examples of binary methods include equality tests, arithmetic operations, and set operations like subset and union.

In older versions of Java, the comparison method was specified as an interface Comparable Category:Articles with example Java code:

interface Comparable {

    int compareTo(Object o);
}

The drawback of this is that the method is specified to take an argument of type Object Category:Articles with example Java code. A typical implementation would first down-cast this argument (throwing an error if it is not of the expected type):

class RationalNumber implements Comparable {
    int numerator;
    int denominator;
    // ...
 
    public int compareTo(Object other) {
        RationalNumber otherNum = (RationalNumber)other;
        return Integer.compare(numerator * otherNum.denominator,
                               otherNum.numerator * denominator);
    }
}

In a language with covariant parameters, the argument to compareTo Category:Articles with example Java code could be directly given the desired type RationalNumber Category:Articles with example Java code, hiding the typecast. (Of course, this would still give a runtime error if compareTo Category:Articles with example Java code was then called on e.g. a String Category:Articles with example Java code.)

Avoiding the need for covariant parameter types

Other language features can provide the apparent benefits of covariant parameters while preserving Liskov substitutability.

In a language with generics (a.k.a. parametric polymorphism) and bounded quantification, the previous examples can be written in a type-safe way.^[12] Instead of defining AnimalShelter Category:Articles with example Java code, we define a parameterized class Shelter<T> Category:Articles with example Java code. (One drawback of this is that the implementer of the base class needs to foresee which types will need to be specialized in the subclasses.)

class Shelter<T extends Animal> {

    T getAnimalForAdoption() {
        // ...
    }

    void putAnimal(T animal) {
        // ...
    }
}

    
class CatShelter extends Shelter<Cat> {

    Cat getAnimalForAdoption() {
        // ...
    }

    void putAnimal(Cat animal) {
        // ...
    }
}

Similarly, in recent versions of Java the Comparable Category:Articles with example Java code interface has been parameterized, which allows the downcast to be omitted in a type-safe way:

class RationalNumber implements Comparable<RationalNumber> {

    int numerator;
    int denominator;
    // ...
         
    public int compareTo(RationalNumber otherNum) {
        return Integer.compare(numerator * otherNum.denominator, 
                               otherNum.numerator * denominator);
    }
}

Another language feature that can help is multiple dispatch. One reason that binary methods are awkward to write is that in a call like a.compareTo(b) Category:Articles with example Java code, selecting the correct implementation of compareTo Category:Articles with example Java code really depends on the runtime type of both a Category:Articles with example Java code and b Category:Articles with example Java code, but in a conventional OO language only the runtime type of a Category:Articles with example Java code is taken into account. In a language with Common Lisp Object System (CLOS)-style multiple dispatch, the comparison method could be written as a generic function where both arguments are used for method selection.

Giuseppe Castagna^[13] observed that in a typed language with multiple dispatch, a generic function can have some parameters which control dispatch and some "left-over" parameters which do not. Because the method selection rule chooses the most specific applicable method, if a method overrides another method, then the overriding method will have more specific types for the controlling parameters. On the other hand, to ensure type safety the language still must require the left-over parameters to be at least as general. Using the previous terminology, types used for runtime method selection are covariant while types not used for runtime method selection of the method are contravariant. Conventional single-dispatch languages like Java also obey this rule: only one argument is used for method selection (the receiver object, passed along to a method as the hidden argument this Category:Articles with example Java code), and indeed the type of this Category:Articles with example Java code is more specialized inside overriding methods than in the superclass.

Castagna suggests that examples where covariant parameter types are superior (particularly, binary methods) should be handled using multiple dispatch; which is naturally covariant. However, most programming languages do not support multiple dispatch.

Summary of variance and inheritance

This section does not cite any sources. Please help improve this section by adding citations to reliable sources. Unsourced material may be challenged and removed. (June 2024) (Learn how and when to remove this message)

The following table summarizes the rules for overriding methods in the languages discussed above.

Declaration-site variance annotations

The most popular languages with declaration-site variance annotations are C# and Kotlin (using the keywords outCategory:Articles with example C Sharp code and inCategory:Articles with example C Sharp code), and Scala and OCaml (using the keywords +Category:Articles with example OCaml code and -Category:Articles with example OCaml code). C# only allows variance annotations for interface types, while Kotlin, Scala and OCaml allow them for both interface types and concrete data types.

interface IEnumerator<out T>
{
    T Current { get; }
    bool MoveNext();
}

interface IList<T>
{
    void Insert(int index, T item);
    IEnumerator<T> GetEnumerator();
}

sealed abstract class List[+A] extends AbstractSeq[A] {
    def head: A
    def tail: List[A]

    /** Adds an element at the beginning of this list. */
    def ::[B >: A] (x: B): List[B] =
        new scala.collection.immutable.::(x, this)
    /** ... */
}

def :: (x: A): List[A]

type ('a, 'b) t = T of ('a -> 'b)

type (-'a, +'b) t = T of ('a -> 'b)

module type S =
    sig
        type key
        type (+'a) t
        val empty: 'a t
        val mem: key -> 'a t -> bool
        ...
    end

Use-site variance annotations (wildcards)

One drawback of the declaration-site approach is that many interface types must be made invariant. For example, we saw above that IListCategory:Articles with example C Sharp code needed to be invariant, because it contained both InsertCategory:Articles with example C Sharp code and GetEnumeratorCategory:Articles with example C Sharp code. In order to expose more variance, the API designer could provide additional interfaces which provide subsets of the available methods (e.g. an "insert-only list" which only provides InsertCategory:Articles with example C Sharp code). However this quickly becomes unwieldy.

Use-site variance means the desired variance is indicated with an annotation at the specific site in the code where the type will be used. This gives users of a class more opportunities for subtyping without requiring the designer of the class to define multiple interfaces with different variance. Instead, at the point a generic type is instantiated to an actual parameterized type, the programmer can indicate that only a subset of its methods will be used. In effect, each definition of a generic class also makes available interfaces for the covariant and contravariant parts of that class.

Java provides use-site variance annotations through wildcards, a restricted form of bounded existential types. A parameterized type can be instantiated by a wildcard ? Category:Articles with example Java code together with an upper or lower bound, e.g. List<? extends Animal> Category:Articles with example Java code or List<? super Animal> Category:Articles with example Java code. An unbounded wildcard like List<?> Category:Articles with example Java code is equivalent to List<? extends Object> Category:Articles with example Java code. Such a type represents List<X> Category:Articles with example Java code for some unknown type X Category:Articles with example Java code which satisfies the bound.^[4]: 139 For example, if l Category:Articles with example Java code has type List<? extends Animal> Category:Articles with example Java code, then the type checker will accept

Animal a = l.get(3);

because the type X Category:Articles with example Java code is known to be a subtype of Animal Category:Articles with example Java code, but

l.add(new Animal());

will be rejected as a type error since an Animal Category:Articles with example Java code is not necessarily an X Category:Articles with example Java code. In general, given some interface I<T> Category:Articles with example Java code, a reference to an I<? extends T> Category:Articles with example Java code forbids using methods from the interface where T Category:Articles with example Java code occurs contravariantly in the type of the method. Conversely, if l Category:Articles with example Java code had type List<? super Animal> Category:Articles with example Java code one could call l.add Category:Articles with example Java code but not l.get Category:Articles with example Java code.

While non-wildcard parameterized types in Java are invariant (e.g. there is no subtyping relationship between List<Cat> Category:Articles with example Java code and List<Animal> Category:Articles with example Java code), wildcard types can be made more specific by specifying a tighter bound. For example, List<? extends Cat> Category:Articles with example Java code is a subtype of List<? extends Animal> Category:Articles with example Java code. This shows that wildcard types are covariant in their upper bounds (and also contravariant in their lower bounds). In total, given a wildcard type like C<? extends T> Category:Articles with example Java code, there are three ways to form a subtype: by specializing the class C Category:Articles with example Java code, by specifying a tighter bound T Category:Articles with example Java code, or by replacing the wildcard ? Category:Articles with example Java code with a specific type (see figure).^[4]: 139

By applying two of the above three forms of subtyping, it becomes possible to, for example, pass an argument of type List<Cat> Category:Articles with example Java code to a method expecting a List<? extends Animal> Category:Articles with example Java code. This is the kind of expressiveness that results from covariant interface types. The type List<? extends Animal> Category:Articles with example Java code acts as an interface type containing only the covariant methods of List<T> Category:Articles with example Java code, but the implementer of List<T> Category:Articles with example Java code did not have to define it ahead of time.

In the common case of a generic data structure IListCategory:Articles with example C Sharp code, covariant parameters are used for methods getting data out of the structure, and contravariant parameters for methods putting data into the structure. The mnemonic for Producer Extends, Consumer Super (PECS), from the book Effective Java by Joshua Bloch gives an easy way to remember when to use covariance and contravariance.^[4]: 141

Wildcards are flexible, but there is a drawback. While use-site variance means that API designers need not consider variance of type parameters to interfaces, they must often instead use more complicated method signatures. A common example involves the Comparable interface.^[4]: 66 Suppose we want to write a function that finds the biggest element in a collection. The elements need to implement the compareTo Category:Articles with example Java code method,^[4]: 66 so a first try might be

<T extends Comparable<T>> T max(Collection<T> coll);

However, this type is not general enough—one can find the max of a Collection<Calendar> Category:Articles with example Java code, but not a Collection<GregorianCalendar> Category:Articles with example Java code. The problem is that GregorianCalendar does not implement Comparable<GregorianCalendar> Category:Articles with example Java code, but instead the (better) interface Comparable<Calendar> Category:Articles with example Java code. In Java, unlike in C#, Comparable<Calendar> Category:Articles with example Java code is not considered a subtype of Comparable<GregorianCalendar> Category:Articles with example Java code. Instead the type of max Category:Articles with example Java code has to be modified:

<T extends Comparable<? super T>> T max(Collection<T> coll);

The bounded wildcard ? super T Category:Articles with example Java code conveys the information that max Category:Articles with example Java code calls only contravariant methods from the Comparable Category:Articles with example Java code interface. This particular example is frustrating because all the methods in Comparable Category:Articles with example Java code are contravariant, so that condition is trivially true. A declaration-site system could handle this example with less clutter by annotating only the definition of Comparable Category:Articles with example Java code.

The max Category:Articles with example Java code method can be changed even further by using an upper bounded wildcard for the method parameter:^[18]

<T extends Comparable<? super T>> T max(Collection<? extends T> coll);

Comparing declaration-site and use-site annotations

Use-site variance annotations provide additional flexibility, allowing more programs to type check. However, they have been criticized for the complexity they add to the language, leading to complicated type signatures and error messages.

One way to assess whether the extra flexibility is useful is to see if it is used in existing programs. A survey of a large set of Java libraries^[16] found that 39% of wildcard annotations could have been directly replaced by declaration-site annotations. Thus the remaining 61% is an indication of places where Java benefits from having the use-site system available.

In a declaration-site language, libraries must either expose less variance, or define more interfaces. For example, the Scala Collections library defines three separate interfaces for classes which employ covariance: a covariant base interface containing common methods, an invariant mutable version which adds side-effecting methods, and a covariant immutable version which may specialize the inherited implementations to exploit structural sharing.^[19] This design works well with declaration-site annotations, but the large number of interfaces carry a complexity cost for clients of the library. And modifying the library interface may not be an option—in particular, one goal when adding generics to Java was to maintain binary backwards compatibility.

On the other hand, Java wildcards are themselves complex. In a conference presentation^[20] Joshua Bloch criticized them as being too hard to understand and use, stating that when adding support for closures "we simply cannot afford another wildcards". Early versions of Scala used use-site variance annotations but programmers found them difficult to use in practice, while declaration-site annotations were found to be very helpful when designing classes.^[21] Later versions of Scala added Java-style existential types and wildcards; however, according to Martin Odersky, if there were no need for interoperability with Java then these would probably not have been included.^[22]

Ross Tate argues^[23] that part of the complexity of Java wildcards is due to the decision to encode use-site variance using a form of existential types. The original proposals^[24][25] used special-purpose syntax for variance annotations, writing List<+Animal> Category:Articles with example Java code instead of Java's more verbose List<? extends Animal> Category:Articles with example Java code.

Since wildcards are a form of existential types they can be used for more things than just variance. A type like List<?> Category:Articles with example Java code ("a list of unknown type"^[26]) lets objects be passed to methods or stored in fields without exactly specifying their type parameters. This is particularly valuable for classes such as Class where most of the methods do not mention the type parameter.

However, type inference for existential types is a difficult problem. For the compiler implementer, Java wildcards raise issues with type checker termination, type argument inference, and ambiguous programs.^[27] In general it is undecidable whether a Java program using generics is well-typed or not,^[28] so any type checker will have to go into an infinite loop or time out for some programs. For the programmer, it leads to complicated type error messages. Java type checks wildcard types by replacing the wildcards with fresh type variables (so-called capture conversion). This can make error messages harder to read, because they refer to type variables that the programmer did not directly write. For example, trying to add a Cat Category:Articles with example Java code to a List<? extends Animal> Category:Articles with example Java code will give an error like

method List.add (capture#1) is not applicable
  (actual argument Cat cannot be converted to capture#1 by method invocation conversion)
where capture#1 is a fresh type-variable:
  capture#1 extends Animal from capture of ? extends Animal

Since both declaration-site and use-site annotations can be useful, some type systems provide both.^[16][23]