Skip to content

Add net10 ImmutableDictionary.CreateRangeWithOverwrite - #608

Merged
SimonCropp merged 1 commit into
mainfrom
immutabledictionary-createrangewithoverwrite
Sep 10, 2026
Merged

Add net10 ImmutableDictionary.CreateRangeWithOverwrite#608
SimonCropp merged 1 commit into
mainfrom
immutabledictionary-createrangewithoverwrite

Conversation

@SimonCropp

Copy link
Copy Markdown
Owner

Two overloads, with and without a key comparer, both net10. Scanning the whole System.Collections.Immutable namespace confirmed these are the only WithOverwrite members anywhere in it, so this is the complete addition rather than one corner of a family.

Scope: netcoreapp2.1 through net9.0

ImmutableDictionary is in the shared framework from netcoreapp2.1; below that it is a separate NuGet package. Extending it on net461, net47x, net48, netstandard2.0 or netstandard2.1 would mean taking a dependency Polyfill does not have today and introducing a new feature constant — plus the Polyfill.targets, Identifiers.sharedIdentifiers and per-framework-count wiring that goes with one — for the sake of two members. The guard is NETCOREAPP2_1_OR_GREATER && !NET10_0_OR_GREATER, and both members carry a //Note: saying so, since #### ImmutableDictionary gives no hint of a floor.

Implemented over a builder, and checked against the BCL rather than assumed

The natural implementation is a builder with indexer assignment, since the indexer already has last-wins semantics. Verified on net11 that it is indistinguishable from the real thing:

  • later entries overwrite earlier ones — a=1, b=2, a=3, c=4, b=5 yields three entries with a=3 and b=5
  • an empty range returns the shared Empty instance, by reference, not a fresh dictionary
  • a supplied comparer is honoured and preserved by reference, including for an empty range
  • a null comparer means EqualityComparer<TKey>.Default

There was exactly one difference, and it is the kind that is invisible until someone catches the exception: for a null key the builder indexer reports paramName as key, where the BCL overload reports the KeyValuePair member as Key. The key is now checked before the assignment so the two match, and there is a test pinning it.

Why the API exists

Worth stating, because it is the whole point: ImmutableDictionary.CreateRange throws ArgumentException on the same input that CreateRangeWithOverwrite accepts. One of the tests asserts both halves of that, so the distinction is not just described in a doc comment.

Verification

Solution clean in Release, Consume clean across all 22 TFMs, tests green on net11.0 (1755), net10.0 (1755), net9.0 (1755), net8.0 (1752), net462 (1695), plus PublicTests, EmbeddedTests, UnsafeTests, NoRefsTests and NoExtrasTests. The six new tests were also run on netcoreapp3.1 via roll-forward, since that is the bottom of the polyfill's window and its runtime is not installed here.

API count 1170 → 1172.

Two overloads, with and without a key comparer. Scanning the whole
System.Collections.Immutable namespace confirmed these are the only WithOverwrite
members, so this is the complete addition rather than one of a family.

Scoped to netcoreapp2.1 through net9.0. ImmutableDictionary is in the shared framework
from netcoreapp2.1 and is a separate package below that, so extending it on net461,
net47x, net48 or netstandard would mean taking a dependency Polyfill does not have and
adding a feature constant for one member. Noted on both.

Implemented over a builder with indexer assignment, which was verified against net11 to
be indistinguishable: later entries overwrite earlier ones, an empty range returns the
shared Empty instance, a supplied comparer is honoured and preserved by reference, and
a null comparer means the default. The one difference was the paramName for a null key,
where the builder indexer reports "key" and the BCL reports the KeyValuePair member as
"Key", so the key is checked before the assignment to match.

API count 1170 -> 1172.
@SimonCropp SimonCropp added this to the 11.3.0 milestone Sep 10, 2026
@SimonCropp
SimonCropp merged commit 968eb34 into main Sep 10, 2026
4 of 6 checks passed
@SimonCropp
SimonCropp deleted the immutabledictionary-createrangewithoverwrite branch September 10, 2026 10:53
This was referenced Sep 10, 2026
This was referenced Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant