C# InsertRange

InsertRange is a List method. It places a collection of elements into a certain index of a List. The List resizes to accommodate the inserted elements. InsertRange handles collections that implement IEnumerable.

Example

First, the InsertRange is closely related to the AddRange method, which allows you to add an array or other collection on the end of a List. InsertRange, as shown below, is exactly the same except that it can insert the IEnumerable range in between existing elements, or at the very start.

This C# program shows how to use the InsertRange method on List.

Program that uses InsertRange [C#]

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
	List<int> a = new List<int>();
	a.Add(1);
	a.Add(2);
	a.Add(5);
	a.Add(6);

	// Contains:
	// 1
	// 2
	// 5
	// 6

	int[] b = new int[3];
	b[0] = 7;
	b[1] = 6;
	b[2] = 7;

	a.InsertRange(1, b);

	// Contains:
	// 1
	// 7 [inserted]
	// 6 [inserted]
	// 7 [inserted]
	// 2
	// 5
	// 6
	foreach (int i in a)
	{
	    Console.WriteLine(i);
	}
    }
}

Output

1
7
6
7
2
5
6

Notes. The program populates a new List instance with four integral values in the Main entry point. Next, it creates an array with three more values. Finally, it inserts the array into the List at the second index.

Implementation

Here we look inside the base class library in the .NET Framework and see that InsertRange is implemented by using Array.Copy and the CopyTo instance method on arrays. This means that the entire array inside the List will have to be copied, making the InsertRange method very expensive.

InsertRange method body [C#]

this.EnsureCapacity(this._size + count);
if (index < this._size)
{
    Array.Copy(...);
}
if (this == is2)
{
    Array.Copy(...);
    Array.Copy(...);
}
else
{
    T[] array = new T[count];
    is2.CopyTo(array, 0);
    array.CopyTo(...);
}

Notes. This is the internal code for InsertRange. If the new range fits in the allocated size, the new range is simply copied. Sometimes 2 Array.Copy calls are needed (one for the elements before, and one for the elements after). Sometimes a new array is allocated.

Summary

We looked at the InsertRange method, seeing an example of how you can add an array to a List. We then looked at the algorithmic time complexity of the InsertRange method, seeing that it can be a very expensive and slow operation. If you have a requirement for inserting elements very often, the LinkedList class would be faster, as you would only need to adjust one reference and not copy and elements. The AddRange method is closely related.