C# Array Length Property

Array length. Every array has a Length. In the C# language we access the Length property on a non-null array.

We see what happens when you get the Length of a one-dimensional array, an empty array, and a null array reference.

Null Array

Example. To start, we see examples of accessing Length on several instances of arrays. We also see related properties, such as LongLength and the GetLength method. In most programs, Length is the most important.

C# program that uses array Length

using System;

class Program
{
    static void Main()
    {
	// A
	// Basic array length example.
	int[] arrayA = new int[5];
	int lengthA = arrayA.Length;
	Console.WriteLine(lengthA); // Writes 5

	// B
	// Long array length example.
	long longLength = arrayA.LongLength;
	Console.WriteLine(longLength); // Writes 5

	// C
	// Zero length array example.
	int[] zero = new int[0];
	int lengthZero = zero.Length;
	Console.WriteLine(lengthZero); // Writes 0

	// D
	// Null array length example exception.
	// int[] dead = null;
	// Console.WriteLine(dead.Length);

	// E
	// GetLength 0 example.
	int lengthE = arrayA.GetLength(0);
	Console.WriteLine(lengthE); // Writes 5

	// F
	// GetLength 1 example exception.
	// int lengthF = arrayA.GetLength(1);
	// Console.WriteLine(lengthF);

	// G
	// Two-dimensional GetLength example.
	int[,] two = new int[5, 10];
	Console.WriteLine(two.GetLength(0)); // Writes 5
	Console.WriteLine(two.GetLength(1)); // Writes 10

	// H
	// Two-dimensional Length example.
	Console.WriteLine(two.Length); // Writes 50
    }
}

Output

5
5
0
5
5
10
50

Description of part A. This is the first section. It uses the Length property to get the length of a new array. Length has no parentheses, as it is a property. It is read-only—you cannot assign Length.

Property

Part B: Here we use the LongLength property on an array. You will most likely not need to use this property.

Part C: Here we get the length of an array with no elements. The Length property returns the value 0. This doesn't raise an exception.

Part D is commented out. It will raise an exception when you run it. Because the array reference is null, you will get an exception—a "System.NullReferenceException: Object reference not set to an instance of an object."

NullNullReferenceException

Description of part E. Here we see the GetLength method, which returns the length of an array at a dimension. Here we get dimension zero of a one-dimensional array. This results in the same value as Length.

Part F uses GetLength but raises an exception. This is because the array has one dimension, but we asked for the second dimension. The exception is "System.IndexOutOfRangeException: Index was outside the bounds of the array."

IndexOutOfRangeException

Part G: Here we see a simple example of using GetLength on a two-dimensional array.

Note: Part G first shows the length of the first dimension. Next, it shows the second dimension.

Part H. Finally we see that the Length property, when used on a two-dimensional array, will return the total number of elements, not just a dimension. Here it returns 5 * 10 elements, which is 50.

2D Array

Discussion. Jagged arrays are essentially single-dimensional arrays of single-dimensional arrays. You can access their lengths the same as with one-dimensional arrays. Their declaration syntax differs.

Jagged Arrays

Count from LINQ. This is an extension method that acts on IEnumerable. You can use it to get the array length. However, it is many times slower and unnecessary for array types. Avoid it unless you have a special design requirement.

Count Array Elements

String arrays. Like all arrays, regardless of type, string arrays are of type Array and will have the Length property. Therefore, string arrays work the same as int arrays here. The type is the only difference.

String Array

Initialization. It does not matter if the array elements are initialized. You can get the length of any allocated array, regardless of whether the elements have been assigned. Int array elements are initialized to 0.

Int Array

Tip: The default value of elements in an array can be determined with the default operator.

Default

Performance. Is the Length property fast? Yes, in general. However, in a really tight loop where hoisting the Length check will not affect JIT, you can cache it in a variable for a performance boost.

Tip: It is a good idea to always test this. The JIT compiler sometimes generates slower instructions if you cache the length.

Also: The LongLength property, which returns a long number, has no performance advantage.

LongLength. The array type offers also the LongLength property. This is only useful when you have an element count greater than the max value of an int. I have not been able to compile a program with this case.

Note: The max value of int is greater than 2 billion. If each array element is a byte, this comes to nearly 2 gigabytes of memory.

And: Depending on your system configuration, it may be impossible to allocate an array this large.

To test LongLength, I decided to benchmark it. I found it is several times slower than using the regular Length property. But the result it returns is the same on a small array. It returns a correct number.

Benchmark

Input array for benchmark: C#

int[] array = new int[short.MaxValue];

Code that uses Length property: C#

int length = array.Length;
if (length != short.MaxValue)
{
    throw new Exception();
}

Code that uses LongLength property: C#

long length = array.LongLength;
if (length != short.MaxValue)
{
    throw new Exception();
}

Result

0.64 ns   Length
2.55 ns   LongLength

Summary. We saw lots of examples of different array instances and their Length properties. Further, we looked at the exceptions raised by Length and GetLength. This is useful for debugging purposes. We discussed the finer points of array lengths.

Related Links