47

What is difference between ImmutableArray<T> and ImmutableList<T>, and where would it be best to use each?

JohnD
  • 3,884
  • 1
  • 28
  • 40
user3391731
  • 473
  • 4
  • 6

4 Answers4

34

Here is some reading that might help explain: Please welcome ImmutableArray

Here's an excerpt:

Reasons to use immutable array:

  • Updating the data is rare or the number of elements is quite small (<16)
  • you need to be able to iterate over the data in performance critical sections
  • you have many instances of immutable collections and you can’t afford keeping the data in trees

Reasons to stick with immutable list:

  • Updating the data is common or the number of elements isn’t expected to be small
  • Updating the collection is more performance critical than iterating the contents
Lance U. Matthews
  • 15,725
  • 6
  • 48
  • 68
Adween
  • 2,792
  • 2
  • 18
  • 20
31

I think you are asking where to use each of them. Please welcome ImmutableArray will help. To summarize, use immutable array when:

  • Updating the data is rare or the number of elements is quite small (<16)
  • You need to be able to iterate over the data in performance critical sections
  • You have many instances of immutable collections and you can’t afford keeping the data in trees

Use immutable list when:

  • Updating the data is common or the number of elements isn't expected to be small
  • Updating the collection is more performance critical than iterating the contents
Pang
  • 9,564
  • 146
  • 81
  • 122
Rajeev Ranjan
  • 1,006
  • 8
  • 18
  • 25
    This answer appears to be copied from http://blogs.msdn.com/b/dotnet/archive/2013/06/24/please-welcome-immutablearray.aspx without proper attribution. -1 – William Gross Aug 21 '15 at 22:38
  • 9
    What does it even mean to "update the data" in an immutable structure? – M-Pixel Apr 06 '20 at 01:30
  • Usually I use `List` instead. – Vincent Jun 15 '20 at 01:55
  • 5
    @M-Pixel It means "create a new version with an element altered, added, or removed". The list does this efficiently, the array does not. – kqr Nov 17 '20 at 15:54
7

The main difference is that an ImmutableArray is just a wrapper around a normal array, which means that retrieving elements within the array is extremely quick.

An ImmutableArray is also a struct, meaning that it's a value type, so it takes up less space than an Immutable List which is a reference type.

For these reasons, an ImmutableArray is suitable to use if you rarely need to update its data, or the number of elements is small (less than 16), or if the performance of iterating over the collection is important.

If your needs do not match the reasons above, you should use an ImmutableList.

Look here for the documentation.

Pang
  • 9,564
  • 146
  • 81
  • 122
James
  • 2,195
  • 1
  • 19
  • 22
  • 4
    The link completely answers this question. But your remark on value-type and size is dodgy. – H H Mar 12 '14 at 11:55
  • According to [the docs](https://msdn.microsoft.com/en-us/library/system.collections.immutable.immutablearray%28v=vs.111%29.aspx), it’s a class, not a struct. Even primitive arrays are reference types—if they were structs the compiler would have to know the number of elements in the array ahead of time like how C supports inline packed arrays (not sure that’s the right terminology). – binki Jun 28 '16 at 14:36
  • https://msdn.microsoft.com/en-us/library/dn638264(v=vs.111).aspx suggests it is a struct? – mjwills Oct 19 '17 at 05:28
  • 2
    @binki: you are looking at the wrong doc page. The class `ImmutableArray` is simply a _static_ class with helper methods. The actual object itself is a `struct`. That said, I do agree that this post is making unwarranted statements about value types, the accuracy of the statement of what kind of type `ImmutableArray` is notwithstanding. – Peter Duniho Jul 16 '20 at 01:26
5

Going by the blog post "Please welcome ImmutableArray<T>" (the same blog post everyone else is referencing), the differences are...

ImmutableArray:

  • Simple implementation (just an array).
  • Not optimized for quickly updating large collections (the entire array needs to be copied).
  • More efficient for most use cases (anything that does not involve updating large collections).

ImmutableList:

  • More complicated implementation (something involving trees).
  • Is optimized for quickly updating large collections (it can be done in logarithmic time).
  • Less efficient for most use cases.

So if you're not updating much, or your collections are small, use ImmutableArray. If you're going to be frequently updating large collections, you'll need to use ImmutableList.

Tanner Swett
  • 3,241
  • 1
  • 26
  • 32