List<'T>.Capacity Property

 

Gets or sets the total number of elements the internal data structure can hold without resizing.

Namespace:   System.Collections.Generic
Assembly:  mscorlib (in mscorlib.dll)

member Capacity : int with get, set

Property Value

Type: System.Int32

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

Exception Condition
ArgumentOutOfRangeException

Capacity is set to a value that is less than Count.

OutOfMemoryException

There is not enough memory available on the system.

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.

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.

No code example is currently available or this language may not be supported.

The following example shows the Capacity property at several points in the life of a list. The default 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.


[<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
    *)

Universal Windows Platform
Available since 8
.NET Framework
Available since 2.0
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top
Show: