133

I am confused about which collection type that I should return from my public API methods and properties.

The collections that I have in mind are IList, ICollection and Collection.

Is returning one of these types always preferred over the others, or does it depend on the specific situation?

DavidRR
  • 18,291
  • 25
  • 109
  • 191
Rocky Singh
  • 15,128
  • 29
  • 99
  • 146
  • 4
    duplicate:http://stackoverflow.com/questions/271710/collectiont-versus-listt-what-should-you-use-on-your-interfaces – Robbie Mar 24 '12 at 21:21
  • also: http://stackoverflow.com/questions/4455428/difference-between-iqueryable-icollection-ilist-idictionary-interface – nathanchere Jun 25 '13 at 01:58

6 Answers6

152

ICollection<T> is an interface that exposes collection semantics such as Add(), Remove(), and Count.

Collection<T> is a concrete implementation of the ICollection<T> interface.

IList<T> is essentially an ICollection<T> with random order-based access.

In this case you should decide whether or not your results require list semantics such as order based indexing (then use IList<T>) or whether you just need to return an unordered "bag" of results (then use ICollection<T>).

cordialgerm
  • 8,403
  • 5
  • 31
  • 47
  • 2
    +1 for a good answer. However, I'd recommend adding a few notes about the general principle of abstraction, and why it favors returning interface types rather than concrete class types. – Adam Mihalcin Mar 24 '12 at 21:24
  • 6
    `Collection` implements `IList` and not only `ICollection`. – CodesInChaos Mar 24 '12 at 21:25
  • 65
    All collections in .Net are ordered, because `IEnumerable` is ordered. What distinguishes `IList` from `ICollection` is that it offers members to work with indexes. For example `list[5]` works, but `collection[5]` won't compile. – svick Mar 24 '12 at 21:26
  • 5
    I also disagree that ordered collections should implement `IList`. There are plenty of ordered collections that don't. `IList` is about fast indexed access. – CodesInChaos Mar 24 '12 at 21:28
  • 1
    It's worth noting that while `IList` is a generic equivalent to `IList`, `ICollection` and `ICollection` are very different. A generic `Foo` which implements `IList` should often not implement non-generic `IList`, but should still implement the non-generic `ICollection`. Otherwise, even though `Foo` would implement `IEnumerable` and `ICollection`, and the latter would expose a fast `Count` property, the `IEnumerable.Count()` extension method wouldn't be able to use the `ICollection.Count()` implementation. – supercat Apr 11 '13 at 16:33
  • 1
    @CodesInChaos points out that Collection implements IList -- this seems odd to me, anyone know why this was done this way? – yoyo May 07 '13 at 17:16
  • 5
    @yoyo The .net collection classes and interfaces are simply badly designed and badly named. I wouldn't think too much about why they named them like that. – CodesInChaos May 07 '13 at 17:21
  • @svick sorry, late to the party, but Collection[i] does compile. Am I missing something? – gbackmania Jul 18 '14 at 05:43
  • @GBackMania No it doesn't: `ICollection collection = new int[1]; Console.WriteLine(collection[0]);`. I assume you tried it with `Collection`, not `ICollection`, but that's not what I was talking about. – svick Jul 18 '14 at 09:08
  • @svick Yes you are right. I thought you meant Collection. Another question - What do you mean by IEnumerable is ordered? Isn't that an implementation detail? By the way, order might hold true for an in-memory list but not a list from db. – gbackmania Jul 18 '14 at 21:08
  • 7
    @svick: Are all collections ordered because `IEnumerable` is ordered? Take `HashSet` - it implements `IEnumerable` but is clearly not ordered. I.e. you have no influence on the order of the items and this order could change at any time, if the internal hash table is re-organized. – Olivier Jacot-Descombes Jan 02 '15 at 17:07
  • @svick What do you mean by **ordered** ? I'm a bit confused by this word, do you mean it is chained like a linked list? – Timeless Oct 17 '17 at 05:22
  • @Timeless I'm not talking about implementation, just about the fact that if you iterate a collection using `foreach`, you get the elements in some order, which is defined by the collection. – svick Oct 17 '17 at 09:19
  • 1
    @svick - your definition of the term *order* is not useful. *It is a tautology* that if you ask a bag of items to be given to you one at a time, that the resulting sequence is in *some* order. It would be *meaningless* to define *ordered* as the ability to iterate over a grouping of items - that is always possible. Therefore, that is *not* how "ordered" is defined. An "ordered" collection is one which provides some guarantee of sequence order that is seen, if enumerate multiple times - with other actions in-between (add/delete). Unfortunately the standard classes are vague re their contracts. – ToolmakerSteve Nov 19 '19 at 21:42
  • ... for example, we "know" (by convention; AFAIK it is not definitively specified) that if you add items to the end of a `List`, you can delete items in the middle of the list, without changing the order of the remaining items. You can do `Add(22); Add(11); Add(44); Remove(11); Add(33);` and know the result is `[22, 44, 33]` - the original order of Adds. No such guarantee is made for `HashSet`, or for the `Keys` of a `Dictionary`; as you add/delete items, nothing is guaranteed re enumeration order. `List` is referred to as "ordered"; `HashSet` or `Dictionary.KeyCollection` are not ordered. – ToolmakerSteve Nov 19 '19 at 21:55
  • ... Similarly, you can do `Insert` in a list, and know that this doesn't "scramble" the list. In my example above, if then do `Insert(1, 55)`, the result is `[22, 55, 44, 33]` - you can be confident that the pre-existing elements don't move around in some unpredictable way; the items are said to *maintain their order*. Another example of "maintaining order": Before each order-preserving operation (add/insert/remove), item `22` was somewhere before `33` - after that operation, `22` is still somewhere before `33`. The only change is that there may be more or fewer items between the two. – ToolmakerSteve Nov 19 '19 at 22:06
75

Generally you should return a type that is as general as possible, i.e. one that knows just enough of the returned data that the consumer needs to use. That way you have greater freedom to change the implementation of the API, without breaking the code that is using it.

Consider also the IEnumerable<T> interface as return type. If the result is only going to be iterated, the consumer doesn't need more than that.

svick
  • 236,525
  • 50
  • 385
  • 514
Guffa
  • 687,336
  • 108
  • 737
  • 1,005
  • 30
    But also consider ICollection which extends IEnumerable to provide additional utilities including a Count property. This can be helpful because you can determine the length of the sequence without traversing the sequence multiple times. – retrodrone Feb 06 '13 at 15:32
  • 12
    @retrodrone: Actually the implementation of the `Count` method checks the actual type of the collection, so it will use the `Length` or `Count` properties for some known types like arrays and `ICollection` even when you supply it as an `IEnumerable`. – Guffa Feb 06 '13 at 16:39
  • 8
    @Guffa: It may be worthwhile to note that if a class `Thing` implements `IList` but not the non-generic `ICollection`, then calling `IEnumerable.Count()` on a `Thing` would be fast, but calling `IEnumerable.Count()` would be slow (since the extension method would look for, and not find, an implementation of `ICollection`). If the class implements the non-generic `ICollection`, however, `IEnumerable.Count` would find and use that. – supercat Apr 11 '13 at 16:26
  • 2
    [MSDN link to Enumerable.Count](http://msdn.microsoft.com/en-us/library/vstudio/bb338038(v=vs.90).aspx) – Kyle Sep 09 '14 at 10:38
  • 13
    I disagree. It's best to return the richest type that you have so that the client can use it directly if that's what they want. If you have a List<>, why return an IEnuerable<> only to force the caller to call ToList() unnecessarily ? – zumalifeguard May 17 '16 at 18:05
  • @zumalifeguard - IMHO, `IList<>` is a good compromise, when you desire to return a rich type, without locking to a *specific* type. – ToolmakerSteve Nov 19 '19 at 21:27
69

The main difference between the IList<T> and ICollection<T> interfaces is that IList<T> allows you to access elements via an index. IList<T> describes array-like types. Elements in an ICollection<T> can only be accessed through enumeration. Both allow the insertion and deletion of elements.

If you only need to enumerate a collection, then IEnumerable<T> is to be preferred. It has two advantages over the others:

  1. It disallows changes to the collection (but not to the elements, if they are of reference type).

  2. It allows the largest possible variety of sources, including enumerations that are generated algorithmically and are not collections at all.

  3. Allows lazy evaluation and can be queried with LINQ.

Collection<T> is a base class that is mainly useful to implementers of collections. If you expose it in interfaces (APIs), many useful collections not deriving from it will be excluded.

One disadvantage of IList<T> is that arrays implement it but do not allow you to add or remove items (i.e. you cannot change the array length). An exception will be thrown if you call IList<T>.Add(item) on an array. The situation is somewhat defused as IList<T> has a Boolean property IsReadOnly that you can check before attempting to do so. But in my eyes, this is still a design flaw in the library. Therefore, I use List<T> directly, when the possibility to add or remove items is required.

Which one should I choose? Let's consider just List<T> and IEnumerable<T> as examples for specialized / generalized types:

  • Method input parameter
    • IEnumerable<T> greatest flexibility for the caller. Restrictive for the implementer, read-only.
    • List<T> Restrictive for the caller. Gives flexibility to the implementer, can manipulate the collection.
  • Method ouput parameter or return value
    • IEnumerable<T> Restrictive for the caller, read-only. Greatest flexibility for the implementer. Allows to return about any collection or to implement an iterator (yield return).
    • List<T> Greatest flexibility for the caller, can manipulate the returned collection. Restrictive for the implementer.

Well, at this point you may be disappointed because I don't give you a simple answer. A statement like "always use this for input and that for output" would not be constructive. The reality is that it depends on use case. A method like void AddMissingEntries(TColl collection) will have to provide a collection type having an Add method or may even require a HashSet<T> for efficiency. A method void PrintItems(TColl collection) can happily live with an IEnumerable<T>.

Olivier Jacot-Descombes
  • 104,806
  • 13
  • 138
  • 188
  • [Code Analysis (and FxCop) advises](http://stackoverflow.com/q/271710/1497596) that when returning a concrete generic collection, one of the following should be returned: `Collection`, `ReadOnlyCollection` or `KeyedCollection`. And that `List` should not be returned. – DavidRR Dec 03 '15 at 14:47
  • @DavidRR: Often it is usefull to pass a list to a method that has to add or remove items. If you type the parameter as `IList`, there is no way to ensure that the method will not be called with an array as parameter. – Olivier Jacot-Descombes Aug 07 '17 at 12:11
9

IList<T> is the base interface for all generic lists. Since it is an ordered collection, the implementation can decide on the ordering, ranging from sorted order to insertion order. Moreover Ilist has Item property that allows methods to read and edit entries in the list based on their index. This makes it possible to insert, remove a value into/from the list at a position index.

Also since IList<T> : ICollection<T>, all the methods from ICollection<T> are also available here for implementation.

ICollection<T> is the base interface for all generic collections. It defines size, enumerators and synchronization methods. You can add or remove an item into a collection but you cannot choose at which position it happens due to the absence of index property.

Collection<T> provides an implementation for IList<T>, IList and IReadOnlyList<T>.

If you use a narrower interface type such as ICollection<T> instead of IList<T>, you protect your code against breaking changes. If you use a wider interface type such as IList<T>, you are more in danger of breaking code changes.

Quoting from a source,

ICollection, ICollection<T> : You want to modify the collection or you care about its size. IList, IList<T>: You want to modify the collection and you care about the ordering and / or positioning of the elements in the collection.

NullReference
  • 2,828
  • 2
  • 30
  • 33
5

Returning an interface type is more general, so (lacking further information on your specific use case) I'd lean towards that. If you want to expose indexing support, choose IList<T>, otherwise ICollection<T> will suffice. Finally, if you want to indicate that the returned types are read only, choose IEnumerable<T>.

And, in case you haven't read it before, Brad Abrams and Krzysztof Cwalina wrote a great book titled "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" (you can download a digest from here).

Alan
  • 6,501
  • 1
  • 28
  • 24
  • `IEnumerable` is read only? Sure but when retuning it in a context of repository, even after executing ToList is not thread safe. Problem is when the original data source gets GC then IEnumarble.ToList() does not work in a multi threaded context. It works on a linear one becasue GC gets called after you do the work but using `async` now a days in 4.5+ IEnumarbale is becoming a ball ache. – Piotr Kula Apr 11 '17 at 09:17
-4

There are some subjects that come from this question:

  • interfaces versus classes
  • which specific class, from several alike classes, collection, list, array ?
  • Common classes versus subitem ("generics") collections

You may want to highlight that its an Object Oriented A.P.I.

interfaces versus classes

If you don't have much experience with interfaces, I recommend stick to classes. I see a lot of times of developers jumping to interfaces, even if its not necesarilly.

And, end doing a poor interface design, instead of, a good class design, which, by the way, can eventually, be migrated to a good interface design ...

You'll see a lot of interfaces in A.P.I., but, don't rush to it, if you don't need it.

You will eventually learn how to apply interfaces, to your code.

which specific class, from several alike classes, collection, list, array ?

There are several classes in c# (dotnet) that can be interchanged. As already mention, if you need something from a more specific class, such as "CanBeSortedClass", then make it explicit in your A.P.I..

Does your A.P.I. user really needs to know, that your class can be sorted, or apply some format to the elements ? Then use "CanBeSortedClass" or "ElementsCanBePaintedClass", otherwise use "GenericBrandClass".

Otherwise, use a more general class.

Common collection classes versus subitem ("generics") collections

You'll find that there are classes that contains others elements, and you can specify that all elements should be of an specific type.

Generic Collections are those classes that you can use the same collection, for several code applications, without having to create a new collection, for each new subitem type, like this: Collection.

Does your A.P.I. user is going to need a very specific type, same for all elements ?

Use something like List<WashingtonApple> .

Does your A.P.I. user is going to need several related types ?

Expose List<Fruit> for your A.P.I., and use List<Orange> List<Banana>, List<Strawberry> internally, where Orange, Banana and Strawberry are descendants from Fruit .

Does your A.P.I. user is going to need a generic type collection ?

Use List, where all items are object (s).

Cheers.

umlcat
  • 4,091
  • 3
  • 19
  • 29
  • 7
    "If you don't have much experience with interfaces, I recommend stick to classes" This is not good advice. That's like saying if there is something you don't know, just stay away from it. Interfaces are extremely powerful and back up the concept of "Program to abstractions vs. concretions" They are also quite powerful for doing unit testing because of the ability to interchange types via mocks. There are a bunch of other great reasons to use Interfaces beyond these comments, so please by all means explore them. – atconway Feb 08 '13 at 16:07
  • @atconway I regulary use interfaces, but, as many concepts, its a powerful tool, it can be easy to mix-use. And, sometimes, developer may not need it. My suggestion wasn't "don't ever interfaces", my suggestion was "in this case, you may skip the interfaces. Learn about it, and you may get the best of them, later". Cheers. – umlcat Feb 08 '13 at 18:07
  • 1
    I recommend always programming to an interface. It helps keep code loosely coupled. – mac10688 Feb 27 '14 at 18:30
  • @mac10688 My previous answer (atconway) also applies to your comment. – umlcat Feb 27 '14 at 20:14