Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Collections

ICollection<T> and IList<T>

Reference for C# ICollection<T>, IList<T>, IReadOnlyCollection<T> and IReadOnlyList<T>: members, which classes implement them and how to choose a parameter type.

These interfaces describe what you can do with a collection, independent of its concrete class. IEnumerable<T> gives read-only forward iteration. ICollection<T> adds Count, Add, Remove, Contains, Clear and CopyTo. IList<T> adds an indexer, Insert, RemoveAt and IndexOf, so items have positions.

Since .NET 4.5 there are also read-only counterparts: IReadOnlyCollection<T> (Count) and IReadOnlyList<T> (Count plus a get-only indexer). They are the right type for parameters and return values when the code only reads.

C#
IList<string> list = new List<string> { "a", "b" };
list.Insert(1, "x");     // a, x, b
IReadOnlyList<string> view = list.ToList();

Try it

C# Writing code against interfaces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Read-only interfaces for APIs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public interface ICollection<T> : IEnumerable<T>
{
    int Count { get; }
    bool IsReadOnly { get; }
    void Add(T item);
    bool Remove(T item);
    bool Contains(T item);
    void Clear();
    void CopyTo(T[] array, int arrayIndex);
}

public interface IList<T> : ICollection<T>
{
    T this[int index] { get; set; }
    int IndexOf(T item);
    void Insert(int index, T item);
    void RemoveAt(int index);
}

public interface IReadOnlyCollection<out T> : IEnumerable<T> { int Count { get; } }
public interface IReadOnlyList<out T> : IReadOnlyCollection<T> { T this[int index] { get; } }
Interface Added over its base Implemented by
ICollection<T> Count, Add, Remove, Contains, Clear, CopyTo List<T>, HashSet<T>, LinkedList<T>, Dictionary, arrays, ...
IList<T> indexer, IndexOf, Insert, RemoveAt List<T>, arrays, Collection<T>, ObservableCollection<T>
IReadOnlyCollection<T> Count almost every collection, including HashSet<T> and Dictionary
IReadOnlyList<T> read-only indexer List<T>, arrays, ImmutableArray<T>, ReadOnlyCollection<T>

Returns: Remove returns true when the item was found and removed. IndexOf returns -1 when not found.

Errors: NotSupportedException when the instance is read-only or fixed-size (arrays throw on Add, Remove, Insert and RemoveAt). ArgumentOutOfRangeException for a bad index.

Usage notes

  • Pick the narrowest interface a method needs. Only iterating: IEnumerable<T>. Need Count or to iterate twice cheaply: IReadOnlyCollection<T>. Need an index: IReadOnlyList<T>. Modifying: ICollection<T> or IList<T>.
  • IReadOnly... is not immutable. A List<T> passed as IReadOnlyList<T> can still be changed by its owner or cast back by a caller. See ReadOnlyCollection and immutable collections.
  • Arrays implement IList<T> but are fixed-size, so check IsReadOnly or expect NotSupportedException from structural changes.
  • IReadOnlyList<T> is covariant (out T), so IReadOnlyList<string> converts to IReadOnlyList<object>. IList<T> is invariant because it can write.
  • Dictionaries are ICollection<KeyValuePair<K,V>>, not IList; see IDictionary and IReadOnlyDictionary.
  • Performance of IList<T> calls: each call goes through the interface, which is slower than a call on List<T> itself in hot loops. Accept the interface in public APIs, use the concrete type internally.
  • Contains cost depends on the class: O(1) for HashSet<T>, O(n) for List<T>.
  • Collection expressions ([1, 2, 3]) can target IEnumerable<T>, IReadOnlyList<T>, ICollection<T> and IList<T>.