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.
List<int> scores = [90, 72, 85]; scores.Add(100); Console.WriteLine(scores[0]); // 90
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 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
CountversusCapacity.Countis the number of items;Capacityis the size of the internal array. When the array is full, the list allocates a bigger one (double the size) and copies the items, soAddis 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,IndexOfandRemoveare O(n). For many membership tests use aHashSet<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 useCollectionsMarshal.AsSpan(list)and slice the span. - Lists of structs return copies from the indexer, so
list[0].X = 5does not compile. Replace the whole element or useCollectionsMarshal.AsSpan. - Collection expressions (
List<int> a = [1, 2, 3];) create lists withoutnew. 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>orlist.AsReadOnly()when they should only read.