Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Collections

The List<T> class

Reference for C# List<T>: creating lists, indexing, Count and Capacity, adding and searching items, ranges, conversions and the errors that lists throw.

List<T> is the standard growable, ordered collection in .NET. It stores its items in an internal array and grows that array automatically when you add more elements. You get fast access by index (list[i]), fast appends, and a large set of methods for adding, removing, searching, sorting and converting.

Lists allow duplicates and null (for reference types), keep insertion order, and are not thread-safe for concurrent writes. The type lives in System.Collections.Generic, which is imported by default.

C#
List<int> scores = [90, 72, 85];
scores.Add(100);
Console.WriteLine(scores[0]);   // 90

Try it

C# Creating and reading a list

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# Capacity and errors

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 class List<T> : IList<T>, IReadOnlyList<T>, IList
{
    public List();
    public List(int capacity);
    public List(IEnumerable<T> collection);

    public int Count { get; }
    public int Capacity { get; set; }
    public T this[int index] { get; set; }

    public void Add(T item);
    public void AddRange(IEnumerable<T> collection);
    public bool Contains(T item);
    public int IndexOf(T item);
    public List<T> GetRange(int index, int count);
    public T[] ToArray();
    public void Clear();
    public void TrimExcess();
}
Name Description
capacity Initial size of the internal array. Does not change Count.
collection Items copied into the new list, in enumeration order.
index Zero-based position. Valid values are 0 to Count - 1.
item The element to add or find. Equality uses EqualityComparer<T>.Default.

Returns: IndexOf returns -1 when the item is not found; Contains returns a bool.

Errors: reading or writing an index outside 0..Count-1 throws ArgumentOutOfRangeException. Passing null to AddRange or the collection constructor throws ArgumentNullException. Changing the list during foreach makes the next step throw InvalidOperationException.

Usage notes

  • Count versus Capacity. Count is the number of items; Capacity is the size of the internal array. When the array is full, the list allocates a bigger one (double the size) and copies the items, so Add is O(1) amortized but an individual call can be O(n).
  • Pre-size large lists with new List<T>(n) to avoid repeated reallocation.
  • Indexing is O(1); Contains, IndexOf and Remove are O(n). For many membership tests use a HashSet<T>.
  • Inserting or removing in the middle is O(n) because later items shift. Appending and removing the last item are cheap.
  • The slice list[1..4] copies the items into a new list. For a no-copy view use CollectionsMarshal.AsSpan(list) and slice the span.
  • Lists of structs return copies from the indexer, so list[0].X = 5 does not compile. Replace the whole element or use CollectionsMarshal.AsSpan.
  • Collection expressions (List<int> a = [1, 2, 3];) create lists without new. A spread, [..a, 4], copies existing items.
  • Not thread-safe for writes. Wrap access in a lock, or use a concurrent collection.
  • Exposing a list publicly lets callers change it. Return IReadOnlyList<T> or list.AsReadOnly() when they should only read.