Article
11/18/2011

List<T> Constructor (Int32)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Initializes a new instance of the List<T> class that is empty and has the specified initial capacity.

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

Syntax

'Declaration
Public Sub New ( _
    capacity As Integer _
)

public List(
    int capacity
)

Parameters

capacity
Type: System.Int32
The number of elements that the new list can initially store.

Exceptions

Exception	Condition
ArgumentOutOfRangeException	capacity is less than 0.

Remarks

The capacity of a List<T> is the number of elements that the List<T> can hold. As elements are added to a List<T>, the capacity is automatically increased as required by reallocating the internal array.

If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the List<T>.

The capacity can be decreased by calling the TrimExcess method or by setting the Capacity property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the List<T>.

This constructor is an O(n) operation, where n is capacity.

Examples

The following code example demonstrates the List<T>(Int32) constructor. A List<T> of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the AsReadOnly method.

Imports System.Collections.Generic

Public Class Example

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)

      Dim dinosaurs As New List(Of String)(4)

      outputBlock.Text &= String.Format(vbLf & "Capacity: {0}", dinosaurs.Capacity) & vbCrLf

      dinosaurs.Add("Tyrannosaurus")
      dinosaurs.Add("Amargasaurus")
      dinosaurs.Add("Mamenchisaurus")
      dinosaurs.Add("Deinonychus")

      outputBlock.Text &= vbCrLf
      For Each dinosaur As String In dinosaurs
         outputBlock.Text &= dinosaur & vbCrLf
      Next

      outputBlock.Text &= vbLf & _
          "Dim roDinosaurs As IList(Of String) = dinosaurs.AsReadOnly" & vbCrLf
      Dim roDinosaurs As IList(Of String) = dinosaurs.AsReadOnly

      outputBlock.Text &= vbLf & "Elements in the read-only IList:" & vbCrLf
      For Each dinosaur As String In roDinosaurs
         outputBlock.Text &= dinosaur & vbCrLf
      Next

      outputBlock.Text &= vbLf & "dinosaurs(2) = ""Coelophysis""" & vbCrLf
      dinosaurs(2) = "Coelophysis"

      outputBlock.Text &= vbLf & "Elements in the read-only IList:" & vbCrLf
      For Each dinosaur As String In roDinosaurs
         outputBlock.Text &= dinosaur & vbCrLf
      Next

   End Sub
End Class

' This code example produces the following output:
'
'Capacity: 4
'
'Tyrannosaurus
'Amargasaurus
'Mamenchisaurus
'Deinonychus
'
'Dim roDinosaurs As IList(Of String) = dinosaurs.AsReadOnly
'
'Elements in the read-only IList:
'Tyrannosaurus
'Amargasaurus
'Mamenchisaurus
'Deinonychus
'
'dinosaurs(2) = "Coelophysis"
'
'Elements in the read-only IList:
'Tyrannosaurus
'Amargasaurus
'Coelophysis
'Deinonychus

using System;
using System.Collections.Generic;

public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      List<string> dinosaurs = new List<string>(4);

      outputBlock.Text += String.Format("\nCapacity: {0}", dinosaurs.Capacity) + "\n";

      dinosaurs.Add("Tyrannosaurus");
      dinosaurs.Add("Amargasaurus");
      dinosaurs.Add("Mamenchisaurus");
      dinosaurs.Add("Deinonychus");

      outputBlock.Text += "\n";
      foreach (string s in dinosaurs)
      {
         outputBlock.Text += s + "\n";
      }

      outputBlock.Text += "\nIList<string> roDinosaurs = dinosaurs.AsReadOnly()" + "\n";
      IList<string> roDinosaurs = dinosaurs.AsReadOnly();

      outputBlock.Text += "\nElements in the read-only IList:" + "\n";
      foreach (string dinosaur in roDinosaurs)
      {
         outputBlock.Text += dinosaur + "\n";
      }

      outputBlock.Text += "\ndinosaurs[2] = \"Coelophysis\"" + "\n";
      dinosaurs[2] = "Coelophysis";

      outputBlock.Text += "\nElements in the read-only IList:" + "\n";
      foreach (string dinosaur in roDinosaurs)
      {
         outputBlock.Text += dinosaur + "\n";
      }
   }
}

/* This code example produces the following output:

Capacity: 4

Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus

IList<string> roDinosaurs = dinosaurs.AsReadOnly()

Elements in the read-only IList:
Tyrannosaurus
Amargasaurus
Mamenchisaurus
Deinonychus

dinosaurs[2] = "Coelophysis"

Elements in the read-only IList:
Tyrannosaurus
Amargasaurus
Coelophysis
Deinonychus
 */

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Share via