Indexer behaviour when key does not exist should be explicit

[jez9999]

Type of issue

Missing information

Description

As per this issue on StackOverflow, I suspect the behaviour of the OrderedDictionary<TKey,TValue>'s indexer is to .TryInsert when the key does not exist, therefore meaning that setting a non-existent key is equivalent to adding a new value to the end of the list, guaranteeing that it will come last when the OrderedDictionary is enumerated. However this is not made explicit in the documentation and therefore could currently just be an implementation detail. I think the behaviour when setting a value that doesn't currently exist via an indexer should be made explicit in the documentation (and its behaviour should be able to be relied upon long-term).

For example, adding keys such that they are at indexes 0, 1, 2, and 3, then removing the key at index 1 and then setting a value to another non-existent key should be guaranteed to result in entries at (conceptually) indexes 0, 2, 3, and (4) rather than the new entry being inserted in the empty slot, resulting in entries at indexes 0, (1), 2, and 3.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.ordereddictionary-2.item?view=net-9.0#remarks

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Collections.Generic/OrderedDictionary`2.xml

Document Version Independent Id

fda90b9c-d6f5-e8a1-f381-46dd197f9890

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-collections