Array.Copy Benchmark List List AddRange List Capacity Prime

Add

Consider an empty C# List: it has no elements, so we must add elements to it. With Add() we place (or append) an element at the end of a List.

Method details

Add() handles both value types and reference types. This method has internal logic that allows us to quickly add elements to the end of the collection.

First example

This example shows how to create a List of unspecified size, and append values to it. We use prime numbers in a List.

Part 1 We declare a List with an int type parameter. We invoke the Add() method 4 times with a different prime number argument each time.

Part 2 We use a foreach-loop and the Console.WriteLine method to display the values to the screen.

Important The angle brackets are part of the declaration type, not numeric operators. They are treated differently in the language.

using System;
using System.Collections.Generic;

// Part 1: add first 4 numbers to the List.
List<int> primes = new List<int>();
primes.Add(2);
primes.Add(3);
primes.Add(5);
primes.Add(7);

// Part 2: display the list.
foreach (int value in primes)
{
    Console.WriteLine(value);
}2
3
5
7

Example 2

Next 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.

And Because the Test type is a reference type, the List stores references to the Test objects on the managed heap.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        // Add 3 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));
        Console.WriteLine("DONE: {0}", list.Count);
    }

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

Performance, Add

This benchmark tests the Add() method and the AddRange method. A 3-element int array is appended to a newly-created list.

Version 1 This code creates a new, empty List, and then appends 3 elements from an array directly with AddRange.

Version 2 This version of the code uses a foreach-loop and calls Add() on each element of the 3-element int array.

Result In .NET 5 for Linux, it is faster to call Add() over each element of the array. Using AddRange() is slower.

using System;
using System.Collections.Generic;
using System.Diagnostics;

const int _max = 1000000;
int[] array = { 10, 20, 30 };

// Version 1: use AddRange.
var s1 = Stopwatch.StartNew();
for (int i = 0; i < _max; i++)
{
    var list = new List<int>();
    list.AddRange(array);
    if (list.Count != 3)
    {
        return;
    }
}
s1.Stop();
// Version 2: use Add.
var s2 = Stopwatch.StartNew();
for (int i = 0; i < _max; i++)
{
    var list = new List<int>();
    foreach (int value in array)
    {
        list.Add(value);
    }
    if (list.Count != 3)
    {
        return;
    }
}
s2.Stop();
Console.WriteLine(((double)(s1.Elapsed.TotalMilliseconds * 1000000) / _max).ToString("0.00 ns"));
Console.WriteLine(((double)(s2.Elapsed.TotalMilliseconds * 1000000) / _max).ToString("0.00 ns"));52.83 ns    AddRange
27.18 ns    Add

Internals

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 Array.Copy.

Info Resizing an array is slow, but if you are using a reference type in your List, the references themselves are small and fast to copy.

Tip Faster copying is an advantage to reference types. References are also faster to copy to arguments during method calls.

`Capacity`

Because the List 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.

Then It doubles the array size each time it runs out of room during an Add call.

Summary

Add receives a single parameter. We noted the usage of Add() with integers and object references. When calling Add(), the capacity of the List is managed internally.