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.
IList<string> list = new List<string> { "a", "b" }; list.Insert(1, "x"); // a, x, b IReadOnlyList<string> view = list.ToList();
Try it
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.
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
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>. NeedCountor to iterate twice cheaply:IReadOnlyCollection<T>. Need an index:IReadOnlyList<T>. Modifying:ICollection<T>orIList<T>. IReadOnly...is not immutable. AList<T>passed asIReadOnlyList<T>can still be changed by its owner or cast back by a caller. SeeReadOnlyCollectionand immutable collections.- Arrays implement
IList<T>but are fixed-size, so checkIsReadOnlyor expectNotSupportedExceptionfrom structural changes. IReadOnlyList<T>is covariant (out T), soIReadOnlyList<string>converts toIReadOnlyList<object>.IList<T>is invariant because it can write.- Dictionaries are
ICollection<KeyValuePair<K,V>>, notIList; seeIDictionaryandIReadOnlyDictionary. - Performance of
IList<T>calls: each call goes through the interface, which is slower than a call onList<T>itself in hot loops. Accept the interface in public APIs, use the concrete type internally. Containscost depends on the class: O(1) forHashSet<T>, O(n) forList<T>.- Collection expressions (
[1, 2, 3]) can targetIEnumerable<T>,IReadOnlyList<T>,ICollection<T>andIList<T>.