TList.Capacity Property

Specifies the allocated size of the array of pointers maintained by the TList object.

Pascal

property Capacity: Integer;

C++

__property int Capacity;

Description

Set Capacity to the number of pointers the list will need to contain. When setting the Capacity property, an EOutOfMemory exception occurs if there is not enough memory to expand the list to its new size.

Read Capacity to learn number of objects the list can hold without reallocating memory. Do not confuse Capacity with the Count property, which is the number of entries in the list that are in use. The value of Capacity is always greater than or equal to the value of Count. When Capacity is greater than Count, the unused memory can be reclaimed by setting Capacity to Count.

When an object is added to a list that is already filled to capacity, the Capacity property is automatically increased. Setting Capacity before adding objects can reduce the number of memory reallocations and thereby improve performance. For example,

Note: Delphi example:

Copy Code

  List.Clear;
  List.Capacity := Count;
  for I := 1 to Count do List.Add(...);

Note: C++ example:

Copy Code

  List->Clear();
  List->Capacity = Count;
  for (int I = 0; I < Count; I++)
    List->Add(...);

The assignment to Capacity before the for loop ensures that each of the following Add operations doesn't cause the list to be reallocated. Avoiding reallocations on the calls to Add improves performance and ensures that the Add operations never raise an exception.