C# List Add Method

Add places an element at the end of a List. It handles both value types and reference types. The Add instance method on the List type has internal logic that allows you to add elements to the end of the collection quickly.

This C# example program uses the Add method on the List type.

Example

First, here we declare a new List with an integer (Int32) type parameter and use the Add method four times. This example shows how you can create a new List of unspecified size, and add four prime numbers to it. Importantly, the angle brackets are part of the declaration type, not conditional operators that mean less or more than. They are treated differently in the language.

Program that uses Add method [C#]

using System.Collections.Generic;

class Program
{
    static void Main()
    {
	// Add first four numbers to the List.
	List<int> primes = new List<int>();
	primes.Add(2);
	primes.Add(3);
	primes.Add(5);
	primes.Add(7);
    }
}

Program result. When you execute the above program, the List instance called 'primes' will contain four integers in its internal data structure. The integers 2, 3, 5 and 7 will be stored in that order in the List's internal array. Whenever you loop over the List's contents, the integers will be accessed in that order.

Add objects

Here we declare a custom class, and then add instances of it to a new List. The type in between the angle brackets is the name of the new class Test. This means the List will only contain Test objects. Because the Test type is a reference type, the List in the example will store reference values to the objects allocated as Test objects on the managed heap.

Program that adds objects to List [C#]

using System.Collections.Generic;

class Program
{
    static void Main()
    {
	// Add three objects to a List.
	List<Test> list = new List<Test>();
	list.Add(new Test(1, 2));
	list.Add(new Test(3, 4));
	list.Add(new Test(5, 6));
    }

    class Test
    {
	int _a;
	int _b;
	public Test(int a, int b)
	{
	    _a = a;
	    _b = b;
	}
    };
}

Description. The above example will allocate an object containing an internal array of Test object references. These object references do not contain the integer fields on the Test class inline; instead, the references contain the storage location of the Test class instance on the managed heap.

Implementation

When you call Add each time, the EnsureCapacity method may be invoked. If you are adding an element that will not fit in the array size, the array is resized with the Array.Copy method. Resizing an array is slow, but if you are using a reference type in your List, the references themselves are small and will not require excessive copying.

Capacity algorithm. Because the List collection is dynamically resized, it must manage its capacity in a way that is algorithmically efficient. It first allocates the internal array with a length of 4; afterwards, it doubles the array size each time it runs out of room during an Add call.

Summary

We looked at the List collection's Add instance method in the C# programming language. This method receives a single parameter of the same type as is contained in the List. We noted the usage of the Add method with integers and object references, and also mentioned how the capacity of the List is managed internally. Finally, for adding many elements at once, you can use the AddRange method on List for less code.