C# | Capacity of a List

List<T>.Capacity Property is used to gets or sets the total number of elements the internal data structure can hold without resizing.

Properties of List:

• It is different from the arrays. A list can be resized dynamically but arrays cannot.
• List class can accept null as a valid value for reference types and it also allows duplicate elements.
• If the Count becomes equals to Capacity then the capacity of the List increases automatically by reallocating the internal array. The existing elements will be copied to the new array before the addition of the new element.

Capacity Vs Count:

• Count is always less than the Capacity. While adding the elements, if Count exceeds Capacity then the Capacity will increase automatically by reallocating the internal array before copying the old elements and adding the new elements.
• Capacity is the number of the elements which the List can store before resizing of List needed. But Count is the number of the elements which are actually present in the List.
• If the Capacity is much larger than the Count the user can decrease capacity by either calling the TrimExcess method or explicitly setting the Capacity to a lower value.
• If the Capacity is settled explicitly then the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied.
• Retrieving the value of Capacity property is an O(1) operation while setting the Capacity is an O(n) operation, where n is the new capacity.

Syntax:

public int Capacity { get; set; }

Return Value: This method returns the number of elements that the List<T> can contain before resizing is required of type System.Int32.

Exceptions:

• ArgumentOutOfRangeException : If the capacity is set to a value that is less than Count.
• OutOfMemoryException : If there is not enough memory available on the system.

Below programs illustrate the use of Capacity Property:

Example 1:

// C# program to illustrate the
// Capacity Property of List<T>
using System;
using System.Collections.Generic;

class Geeks {

    // Main Method
    public static void Main(String[] args)
    {

        // Creating a List of integers
        // Here we are not setting
        // Capacity explicitly
        List<int> firstlist = new List<int>();

        // adding elements in firstlist
        firstlist.Add(1);
        firstlist.Add(2);
        firstlist.Add(3);
        firstlist.Add(4);

        // Printing the Capacity of firstlist
        Console.WriteLine("Capacity Is: " + firstlist.Capacity);

        // Printing the Count of firstlist
        Console.WriteLine("Count Is: " + firstlist.Count);

        // Adding some more
        // elements in firstlist
        firstlist.Add(5);
        firstlist.Add(6);

        // Printing the Capacity of firstlist
        // It will give output 8 as internally
        // List is resized
        Console.WriteLine("Capacity Is: " + firstlist.Capacity);

        // Printing the Count of firstlist
        Console.WriteLine("Count Is: " + firstlist.Count);
    }
}

Output:

Capacity Is: 4
Count Is: 4
Capacity Is: 8
Count Is: 6

Example 2:

// C# program to illustrate the
// Capacity Property of List<T>
using System;
using System.Collections.Generic;

class Geeks {

    // Main Method
    public static void Main(String[] args)
    {

        // Creating a List of integers
        // Here we are setting Capacity
        // explicitly i.e.
        List<int> firstlist = new List<int>(10);

        // Printing the Capacity of firstlist
        Console.WriteLine("Capacity Is: " + firstlist.Capacity);

        // Printing the Count of firstlist
        Console.WriteLine("Count Is: " + firstlist.Count);

        // adding elements in firstlist
        firstlist.Add(1);
        firstlist.Add(2);
        firstlist.Add(3);
        firstlist.Add(4);

        // Printing the Capacity of firstlist
        Console.WriteLine("Capacity Is: " + firstlist.Capacity);

        // Printing the Count of firstlist
        Console.WriteLine("Count Is: " + firstlist.Count);

        // Adding some more
        // elements in firstlist
        firstlist.Add(5);
        firstlist.Add(6);

        // Printing the Capacity of firstlist
        // It will give output 10 as we have
        // already set the Capacity
        Console.WriteLine("Capacity Is: " + firstlist.Capacity);

        // Printing the Count of firstlist
        Console.WriteLine("Count Is: " + firstlist.Count);
    }
}

Output:

Capacity Is: 10
Count Is: 0
Capacity Is: 10
Count Is: 4
Capacity Is: 10
Count Is: 6

Reference:

• https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1.capacity?view=netframework-4.7.2