List<T>.Capacity Property

public:
 property int Capacity { int get(); void set(int value); };

public int Capacity { get; set; }

member this.Capacity : int with get, set

Public Property Capacity As Integer

Property Value

The number of elements that the List<T> can contain before resizing is required.

Exceptions

Examples

The following example demonstrates how to check the capacity and count of a List<T> that contains a simple business object, and illustrates using the TrimExcess method to remove extra capacity.

using System;
using System.Collections.Generic;
// Simple business object. A PartId is used to identify a part
// but the part name be different for the same Id.
public class Part : IEquatable<Part>
{
 public string PartName { get; set; }
 public int PartId { get; set; }
 public override string ToString()
 {
 return "ID: " + PartId + " Name: " + PartName;
 }
 public override bool Equals(object obj)
 {
 if (obj == null) return false;
 Part objAsPart = obj as Part;
 if (objAsPart == null) return false;
 else return Equals(objAsPart);
 }
 public override int GetHashCode()
 {
 return base.GetHashCode();
 }
 public bool Equals(Part other)
 {
 if (other == null) return false;
 return (this.PartId.Equals(other.PartId));
 }
 // Should also override == and != operators.
}
public class Example
{

 public static void Main()
 {
 List<Part> parts = new List<Part>();

 Console.WriteLine("\nCapacity: {0}", parts.Capacity);

 parts.Add(new Part() { PartName = "crank arm", PartId = 1234 });
 parts.Add(new Part() { PartName = "chain ring", PartId = 1334 });
 parts.Add(new Part() { PartName = "seat", PartId = 1434 });
 parts.Add(new Part() { PartName = "cassette", PartId = 1534 });
 parts.Add(new Part() { PartName = "shift lever", PartId = 1634 }); ;

 Console.WriteLine();
 foreach (Part aPart in parts)
 {
 Console.WriteLine(aPart);
 }

 Console.WriteLine("\nCapacity: {0}", parts.Capacity);
 Console.WriteLine("Count: {0}", parts.Count);

 parts.TrimExcess();
 Console.WriteLine("\nTrimExcess()");
 Console.WriteLine("Capacity: {0}", parts.Capacity);
 Console.WriteLine("Count: {0}", parts.Count);

 parts.Clear();
 Console.WriteLine("\nClear()");
 Console.WriteLine("Capacity: {0}", parts.Capacity);
 Console.WriteLine("Count: {0}", parts.Count);
 }
 /*
 This code example produces the following output.
 Capacity: 0

 ID: 1234 Name: crank arm
 ID: 1334 Name: chain ring
 ID: 1434 Name: seat
 ID: 1534 Name: cassette
 ID: 1634 Name: shift lever

 Capacity: 8
 Count: 5

 TrimExcess()
 Capacity: 5
 Count: 5

 Clear()
 Capacity: 5
 Count: 0
 */
}

Imports System.Collections.Generic

' Simple business object. A PartId is used to identify a part 
' but the part name can change.
Public Class Part
 Implements IEquatable(Of Part)
 Public Property PartName() As String
 Get
 Return m_PartName
 End Get
 Set(value As String)
 m_PartName = Value
 End Set
 End Property
 Private m_PartName As String
 Public Property PartId() As Integer
 Get
 Return m_PartId
 End Get
 Set(value As Integer)
 m_PartId = Value
 End Set
 End Property
 Private m_PartId As Integer
 Public Overrides Function ToString() As String
 Return "ID: " & PartId & " Name: " & PartName
 End Function
 Public Overrides Function Equals(obj As Object) As Boolean
 If obj Is Nothing Then
 Return False
 End If
 Dim objAsPart As Part = TryCast(obj, Part)
 If objAsPart Is Nothing Then
 Return False
 Else
 Return Equals(objAsPart)
 End If
 End Function
 Public Overrides Function GetHashCode() As Integer
 Return MyBase.GetHashCode()
 End Function
 Public Overloads Function Equals(other As Part) As Boolean Implements IEquatable(Of Part).Equals
 If other Is Nothing Then
 Return False
 End If
 Return (Me.PartId.Equals(other.PartId))
 End Function
 ' Should also override == and != operators.

End Class
Public Class Example

 Public Shared Sub Main()
 Dim parts As New List(Of Part)()

 Console.WriteLine(vbLf & "Capacity: {0}", parts.Capacity)

 ' Add parts to the list.
 parts.Add(New Part() With { _
 .PartName = "crank arm", _
 .PartId = 1234 _
 })
 parts.Add(New Part() With { _
 .PartName = "chain ring", _
 .PartId = 1334 _
 })
 parts.Add(New Part() With { _
 .PartName = "regular seat", _
 .PartId = 1434 _
 })
 parts.Add(New Part() With { _
 .PartName = "banana seat", _
 .PartId = 1444 _
 })
 parts.Add(New Part() With { _
 .PartName = "cassette", _
 .PartId = 1534 _
 })
 parts.Add(New Part() With { _
 .PartName = "shift lever", _
 .PartId = 1634 _
 })



 Console.WriteLine()
 For Each aPart As Part In parts
 Console.WriteLine(aPart)
 Next

 Console.WriteLine(vbLf & "Capacity: {0}", parts.Capacity)
 Console.WriteLine("Count: {0}", parts.Count)

 parts.TrimExcess()
 Console.WriteLine(vbLf & "TrimExcess()")
 Console.WriteLine("Capacity: {0}", parts.Capacity)
 Console.WriteLine("Count: {0}", parts.Count)

 parts.Clear()
 Console.WriteLine(vbLf & "Clear()")
 Console.WriteLine("Capacity: {0}", parts.Capacity)
 Console.WriteLine("Count: {0}", parts.Count)
 End Sub
 '
 ' This code example produces the following output. 
 ' Capacity: 0
 '
 ' ID: 1234 Name: crank arm
 ' ID: 1334 Name: chain ring
 ' ID: 1434 Name: seat
 ' ID: 1534 Name: cassette
 ' ID: 1634 Name: shift lever
 '
 ' Capacity: 8
 ' Count: 6
 '
 ' TrimExcess()
 ' Capacity: 6
 ' Count: 6
 '
 ' Clear()
 ' Capacity: 6
 ' Count: 0
 ' 

End Class

The following example shows the Capacity property at several points in the life of a list. The parameterless constructor is used to create a list of strings with a capacity of 0, and the Capacity property is displayed to demonstrate this. After the Add method has been used to add several items, the items are listed, and then the Capacity property is displayed again, along with the Count property, to show that the capacity has been increased as needed.

The Capacity property is displayed again after the TrimExcess method is used to reduce the capacity to match the count. Finally, the Clear method is used to remove all items from the list, and the Capacity and Count properties are displayed again.

List<string> dinosaurs = new List<string>();

Console.WriteLine("\nCapacity: {0}", dinosaurs.Capacity);

dinosaurs.Add("Tyrannosaurus");
dinosaurs.Add("Amargasaurus");
dinosaurs.Add("Mamenchisaurus");
dinosaurs.Add("Deinonychus");
dinosaurs.Add("Compsognathus");
Console.WriteLine();
foreach(string dinosaur in dinosaurs)
{
 Console.WriteLine(dinosaur);
}

Console.WriteLine("\nCapacity: {0}", dinosaurs.Capacity);
Console.WriteLine("Count: {0}", dinosaurs.Count);

Console.WriteLine("\nContains(\"Deinonychus\"): {0}",
 dinosaurs.Contains("Deinonychus"));

Console.WriteLine("\nInsert(2, \"Compsognathus\")");
dinosaurs.Insert(2, "Compsognathus");

Console.WriteLine();
foreach(string dinosaur in dinosaurs)
{
 Console.WriteLine(dinosaur);
}

// Shows accessing the list using the Item property.
Console.WriteLine("\ndinosaurs[3]: {0}", dinosaurs[3]);

Console.WriteLine("\nRemove(\"Compsognathus\")");
dinosaurs.Remove("Compsognathus");

Console.WriteLine();
foreach(string dinosaur in dinosaurs)
{
 Console.WriteLine(dinosaur);
}

dinosaurs.TrimExcess();
Console.WriteLine("\nTrimExcess()");
Console.WriteLine("Capacity: {0}", dinosaurs.Capacity);
Console.WriteLine("Count: {0}", dinosaurs.Count);

dinosaurs.Clear();
Console.WriteLine("\nClear()");
Console.WriteLine("Capacity: {0}", dinosaurs.Capacity);
Console.WriteLine("Count: {0}", dinosaurs.Count);

/* This code example produces the following output:

Capacity: 0

Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus
Compsognathus

Capacity: 8
Count: 5

Contains("Deinonychus"): True

Insert(2, "Compsognathus")

Tyrannosaurus
Amargasaurus
Compsognathus
Mamenchisaurus
Deinonychus
Compsognathus

dinosaurs[3]: Mamenchisaurus

Remove("Compsognathus")

Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus
Compsognathus

TrimExcess()
Capacity: 5
Count: 5

Clear()
Capacity: 5
Count: 0
 */

Imports System.Collections.Generic

Partial Public Class Program
 Public Shared Sub ShowPlanets()
 Dim planets As New List(Of String)

 Console.WriteLine(vbLf & "Capacity: {0}", planets.Capacity)

 planets.Add("Mercury")
 planets.Add("Venus")
 planets.Add("Earth")
 planets.Add("Mars")
 planets.Add("Jupiter")

 Console.WriteLine()
 For Each planet As String In planets
 Console.WriteLine(planet)
 Next

 Console.WriteLine(vbLf & "Capacity: {0}", planets.Capacity)
 Console.WriteLine("Count: {0}", planets.Count)

 Console.WriteLine(vbLf & "Contains(""Mars""): {0}", _
 planets.Contains("Mars"))

 Console.WriteLine(vbLf & "Insert(2, ""Saturn"")")
 planets.Insert(2, "Saturn")

 Console.WriteLine()
 For Each planet As String In planets
 Console.WriteLine(planet)
 Next
 ' Shows how to access the list using the Item property.
 Console.WriteLine(vbLf & "planets(3): {0}", planets(3))
 Console.WriteLine(vbLf & "Remove(""Jupiter"")")
 planets.Remove("Jupiter")

 Console.WriteLine()
 For Each planet As String In planets
 Console.WriteLine(planet)
 Next

 planets.TrimExcess()
 Console.WriteLine(vbLf & "TrimExcess()")
 Console.WriteLine("Capacity: {0}", planets.Capacity)
 Console.WriteLine("Count: {0}", planets.Count)

 planets.Clear()
 Console.WriteLine(vbLf & "Clear()")
 Console.WriteLine("Capacity: {0}", planets.Capacity)
 Console.WriteLine("Count: {0}", planets.Count)
 End Sub
End Class

' This code example produces the following output:
'
' Capacity: 0
'
' Mercury
' Venus
' Earth
' Mars
' Jupiter
'
' Capacity: 8
' Count: 5
'
' Contains("Mars"): True
'
' Insert(2, "Saturn")
'
' Mercury
' Venus
' Saturn
' Earth
' Mars
' Jupiter
'
' planets(3): Earth
'
' Remove("Jupiter")
'
' Mercury
' Venus
' Saturn
' Earth
' Mars
'
' TrimExcess()
' Capacity: 5
' Count: 5
'
' Clear()
' Capacity: 5
' Count: 0

[<EntryPoint>]
let main argv = 
 // We refer to System.Collections.Generic.List<'T> by its type 
 // abbreviation ResizeArray<'T> to avoid conflict with the List module. 
 // Note: In F# code, F# linked lists are usually preferred over
 // ResizeArray<'T> when an extendable collection is required.
 let dinosaurs = ResizeArray<_>()
 
 // Write out the dinosaurs in the ResizeArray.
 let printDinosaurs() =
 printfn ""
 dinosaurs |> Seq.iter (fun p -> printfn "%O" p) 
 
 
 printfn "\nCapacity: %i" dinosaurs.Capacity
 
 dinosaurs.Add("Tyrannosaurus")
 dinosaurs.Add("Amargasaurus")
 dinosaurs.Add("Mamenchisaurus")
 dinosaurs.Add("Deinonychus")
 dinosaurs.Add("Compsognathus")
 
 printDinosaurs()
 
 printfn "\nCapacity: %i" dinosaurs.Capacity
 printfn "Count: %i" dinosaurs.Count
 
 printfn "\nContains(\"Deinonychus\"): %b" (dinosaurs.Contains("Deinonychus"))
 
 printfn "\nInsert(2, \"Compsognathus\")"
 dinosaurs.Insert(2, "Compsognathus")
 
 printDinosaurs()
 
 // Shows accessing the list using the Item property.
 printfn "\ndinosaurs[3]: %s" dinosaurs.[3]
 
 printfn "\nRemove(\"Compsognathus\")"
 dinosaurs.Remove("Compsognathus") |> ignore
 
 printDinosaurs()
 
 dinosaurs.TrimExcess()
 printfn "\nTrimExcess()"
 printfn "Capacity: %i" dinosaurs.Capacity
 printfn "Count: %i" dinosaurs.Count
 
 dinosaurs.Clear()
 printfn "\nClear()"
 printfn "Capacity: %i" dinosaurs.Capacity
 printfn "Count: %i" dinosaurs.Count
 
 0 // return an integer exit code
 
 (* This code example produces the following output:
 
Capacity: 0
 
Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus
Compsognathus
 
Capacity: 8
Count: 5
 
Contains("Deinonychus"): true
 
Insert(2, "Compsognathus")
 
Tyrannosaurus
Amargasaurus
Compsognathus
Mamenchisaurus
Deinonychus
Compsognathus
 
dinosaurs[3]: Mamenchisaurus
 
Remove("Compsognathus")
 
Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus
Compsognathus
 
TrimExcess()
Capacity: 5
Count: 5
 
Clear()
Capacity: 5
Count: 0
 *)

Remarks

Capacity is the number of elements that the List<T> can store before resizing is required, whereas Count is the number of elements that are actually in the List<T>.

Capacity is always greater than or equal to Count. If Count exceeds Capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements.

If the capacity is significantly larger than the count and you want to reduce the memory used by the List<T>, you can decrease capacity by calling the TrimExcess method or by setting the Capacity property explicitly to a lower value. When the value of Capacity is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied.

Retrieving the value of this property is an O(1) operation; setting the property is an O(n) operation, where n is the new capacity.

See also

• Count