[API Proposal]: ImmutableDictionary.SetItems(params ValueTuple<TKey, TValue>[] Values)

[TonyValenti]

Background and motivation

It would be really nice if the SetItems API allowed me to use params and value tuples to easily specify items that need to be updated.

API Proposal

namespace System.Collections.Generic;

public class ImmutableDictionary<TKey, TValue>
{
    public ImmutableDictionary<TKey, TValue> SetItems(params ValueTuple<TKey, TValue>[] Values);
}

API Usage

var NewValues = OldValues.SetItems(
                    (DateFieldName.Path_CreatedAt, NewCreatedAt),
                    (DateFieldName.Path_UpdatedAt, NewUpdatedAt),
                    (Type_CreatedAt, NewCreatedAt),
                    (Type_UpdatedAt, NewUpdatedAt)
                );

Alternative Designs

This could be made an extension method or left out altogether.

Risks

None that I can think of.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-collections
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

It would be really nice if the SetItems API allowed me to use params and value tuples to easily specify items that need to be updated.

API Proposal

namespace System.Collections.Generic;

public class ImmutableDictionary<TKey, TValue>
{
    public ImmutableDictionary<TKey, TValue> SetItems(params ValueTuple<TKey, TValue>[] Values);
}

API Usage

var NewValues = OldValues.SetItems(
                    (DateFieldName.Path_CreatedAt, NewCreatedAt),
                    (DateFieldName.Path_UpdatedAt, NewUpdatedAt),
                    (Type_CreatedAt, NewCreatedAt),
                    (Type_UpdatedAt, NewUpdatedAt)
                );

Alternative Designs

This could be made an extension method or left out altogether.

Risks

None that I can think of.

Author:	TonyValenti
Assignees:	-
Labels:	api-suggestion, area-System.Collections, untriaged
Milestone:	-

[TonyValenti]

@jeffhandley

[danmoseley]

Have you thought about how often this would be used? Eg perhaps some looking in https://Grep.app ... as you know, there needs to be sufficient need to add a new API, particularly when it can be a simple extension method. Is there a reason this would be particularly valuable on ImmutableDictionary (eg perf) - it does not exist on Dictionary<K,V> which has far more usage.

[TonyValenti]

Hi @danmoseley -
With ImmutableDictionary, whenever the dictionary is modified, there is overhead. By adding multiple items at once, you only have to pay the tax once. (At least that is my assumption about how it works. I could be wrong!)

With dictionary, the overhead is constant regardless of how many items are added.

[svick]

@TonyValenti You can largely achieve the same effect yourself by writing an extension method that uses the dictionary's builder:

public static ImmutableDictionary<TKey, TValue> SetItems<TKey, TValue>(
    this ImmutableDictionary<TKey, TValue> dictionary, params ValueTuple<TKey, TValue>[] values)
{
    var builder = dictionary.ToBuilder();
    
    foreach (var (key, value) in values)
    {
        builder[key] = value;
    }

    return builder.ToImmutable();
}

When I compare this using a simple benchmark based on your example code, the results I get are:

Method	Mean	Error	StdDev	Gen 0	Allocated
OneByOne	1.318 us	0.0098 us	0.0092 us	0.2136	672 B
SetItems	1.058 us	0.0105 us	0.0093 us	0.1316	416 B
ExtensionSetItems	1.128 us	0.0104 us	0.0092 us	0.1392	440 B

I.e. setting the items one by one is indeed relatively bad, especially when it comes to allocations. But an extension SetItems using Builder is comparable with the existing overload of SetItems.

[krwq]

@TonyValenti does @svick sound like a reasonable solution? If so can this issue be closed? I'm also personally not a fan of adding helper methods for every possible use case

[ghost]

This issue has been marked needs-author-action and may be missing some important information.