Add FrozenDictionary specialization for integers / enums

[stephentoub]

This adds a specialized dictionary implementation for when TKey is an integer (some integer types) or an enum backed by an integer. It employs an array that can be indexed into directly, handling both the cases where the values are contiguous from zero and where they're either non-contiguous or not from zero. A density threshold is used to decide when to fallback to another implementation rather than expending more memory on unused array slots.

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using System.Collections.Frozen;
using System.Net;

BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args);

[MemoryDiagnoser(false)]
public class DayOfWeekTests : Tests<DayOfWeek> { }

[MemoryDiagnoser(false)]
public class HttpStatusCodeTests : Tests<HttpStatusCode> { }

[MemoryDiagnoser(false)]
public class ConsoleKeyTests : Tests<ConsoleKey> { }

public abstract class Tests<T> where T : struct, Enum
{
    private static readonly T[] s_values = Enum.GetValues<T>().Distinct().ToArray();
    private static readonly T s_lookup = s_values[s_values.Length / 2];

    private static readonly FrozenDictionary<T, string> s_hsc = s_values.ToFrozenDictionary(d => d, d => d.ToString());

    [Benchmark]
    public string Get() => s_hsc[s_lookup];

    [Benchmark]
    public FrozenDictionary<T, string> Create() => s_values.ToFrozenDictionary(d => d, d => d.ToString());
}

Type	Method	Toolchain	Mean	Ratio	RatioSD	Allocated
ConsoleKeyTests	Get	\main\corerun.exe	2.5985 ns	1.00	0.09	-
ConsoleKeyTests	Get	\pr\corerun.exe	1.9684 ns	0.76	0.05	-
DayOfWeekTests	Get	\main\corerun.exe	3.6290 ns	1.00	0.02	-
DayOfWeekTests	Get	\pr\corerun.exe	0.7337 ns	0.20	0.00	-
HttpStatusCodeTests	Get	\main\corerun.exe	2.8100 ns	1.00	0.02	-
HttpStatusCodeTests	Get	\pr\corerun.exe	1.9481 ns	0.69	0.02	-
ConsoleKeyTests	Create	\main\corerun.exe	11,878.1837 ns	1.02	0.20	18084 B
ConsoleKeyTests	Create	\pr\corerun.exe	9,649.4596 ns	0.83	0.11	-
DayOfWeekTests	Create	\main\corerun.exe	309.8565 ns	1.00	0.03	728 B
DayOfWeekTests	Create	\pr\corerun.exe	301.6182 ns	0.97	0.02	672 B
HttpStatusCodeTests	Create	\main\corerun.exe	3,819.6599 ns	1.00	0.02	8033 B
HttpStatusCodeTests	Create	\pr\corerun.exe	3,551.3032 ns	0.93	0.01	11042 B

(something is wrong with the allocation number for ConsoleKeyTests... it's not 0, but BDN keeps reporting that)

[dotnet-policy-service]

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

[adamsitnik]

LGTM, thank you @stephentoub !

This reminded me of a conversation I recently had on Twitter where another interesting scenario was mentioned: single item dictionaries / hash sets: https://x.com/STeplyakov/status/1872347499119423630

[skyoxZ]

What about type char?

[stephentoub]

Do you have concrete examples where TKey=char is helpful?

[skyoxZ]

For example, a frozen dictionary with keys from 'A' to 'Z'? I guess such case is fairly common.

[stephentoub]

I guess such case is fairly common.

Examples?

[skyoxZ]

A dictionary of something like:
'A' -> "Alpha"
'B' -> "Bravo"
'C' -> "Charlie"
...

Why not support char considering some rare (I thought) types such as sbyte have been included.

[skyoxZ]

Sorting is expensive. Is it necessary?

1. min == 0 && length == count is enough to get the result of isFull.
2. It seems no need to sort before creating WithOptionalValues. And similar implementation can be used when creating WithFullValues to skip sorting.

[stephentoub]

Is it necessary?

As noted in the comment, I wanted the keys/values in order, as we do for e.g. SmallValueTypeComparableFrozenDictionary.

[skyoxZ]

SmallValueTypeComparableFrozenDictionary must keep keys in order because its searching relies on this. DenseIntegralFrozenDictionary doesn't have such limit, so I don't think the order of the keys makes sense. And even if we need to order the keys of DenseIntegralFrozenDictionary , there's better way to implement that without sorting.

[stephentoub]

And even if we need to order the keys of DenseIntegralFrozenDictionary , there's better way to implement that without sorting.

?

[skyoxZ]

For WithOptionalValues, after setting the elements of optionalValues:

int keyIndex = 0;
for (i = 0; i < optionalValues.Length; i++)
{
    if (optionalValues[i].HasValue)
    {
        keys[keyIndex] = i + min;
        values[keyIndex] = optionalValues[i].Value;
        keyIndex++;
    }
}

And for WithFullValues, use similar way but Optional is not needed.

[skyoxZ]

But that's not the point. Users never expect FrozenDictionary.Keys are sorted.