ValueCollections.Block
0.0.6-alpha
dotnet add package ValueCollections.Block --version 0.0.6-alpha
NuGet\Install-Package ValueCollections.Block -Version 0.0.6-alpha
<PackageReference Include="ValueCollections.Block" Version="0.0.6-alpha" />
paket add ValueCollections.Block --version 0.0.6-alpha
#r "nuget: ValueCollections.Block, 0.0.6-alpha"
// Install ValueCollections.Block as a Cake Addin
#addin nuget:?package=ValueCollections.Block&version=0.0.6-alpha&prerelease
// Install ValueCollections.Block as a Cake Tool
#tool nuget:?package=ValueCollections.Block&version=0.0.6-alpha&prerelease
Block
is an immutable array with value equality, that is, two arrays are equal if they have the same contents.
To install the nuget package:
dotnet add package ValueCollections.Block --prerelease
Example usage:
using ValueCollections;
// Equality based on contents, not references
Block.Create(1, 2, 3) == Block.Create(1, 2, 3); // true
// This holds whether it is stored in a record, a tuple,
// or anything else that compares using default equality comparers.
record DataBlock(Block<string> Entries);
var db0 = new DataBlock(Block.Create("a", "b"));
var db1 = new DataBlock(Block.Create("a", "b"));
db0 == db1 // true
// Works as a key in Dictionary, HashMap or anything that uses GetHashCode.
var dict = new Dictionary<Block<int>, string>
{
[Block.Create(1, 2, 3)] = "Entry1"
};
dict[Block.Create(1, 2, 3)]; // "Entry1"
// Nice, structural "ToString()" recursively prints nested data,
// making it a joy to use in scripting, logging and debugging.
Block.Create(new[] { 1, 2, 3 }, new[] { 4, 5, 6 }).ToString()
"Block(2) { Array(3) { 1, 2, 3 }, Array(3) { 4, 5, 6 } }"
// Supports C# 8 slices and ranges:
var slice = block[1..^1];
// Seamless interop to and from LINQ:
Block<int> items = Block.Create(1, 2, 3);
Block<int> oddsSquared = items.Where(i => i % 2 == 1).Select(i => i * i).ToBlock();
"Block(2) { 1, 9 }"
// Update operations are non-destructive:
var newBlock = block.Append(item); // does not modify the original
var newBlock = block.SetItem(2, item); // use this instead of block[2] = item;
Block
is highly unstable and experimental at this stage.
Not every method is yet covered by unit tests. The design might still change.
Why do we need this?
Arrays
, Lists
, Dictionaries
and even collections from System.Collections.Immutable
compare by reference.
The introduction of records and tuples in C#, which compare by value, mean that there's a need for a collection
type that compares by value too.
People
regularly
ask
for
this.
Why the name Block
?
It's short and it's consistent with the equivalent planned F# feature also based on ImmutableArray
.
Why should it be immutable?
Anything that supports equality should be immutable, since it can be used as keys in dictionaries and maps. In a DDD sense, this type represents a value, not an entity.
Why is this a reference type when ImmutableArray
is a value type?
Value types support default
initialization, which would be an invalid state for this type
(it would throw NullReferenceException
when you'd' try to do anything with it).
This is easy to run into and the compiler wouldn't be able to help you spot it.
ImmutableArray
seems to cater to experts writing low-allocation code (e.g. Roslyn); Block
tries to be more general-purpose.
Won't this be slow compared to T[]
?
It leverages optimizations in ImmutableArray
to make for
and foreach
as fast as or faster than any other collection.
It tries to leverage available optimizations in LINQ as well.
Equality is as fast or faster than SequenceEquals
, except for arrays of blittable types, which .NET optimizes to a memcmp.
GetHashCode
is fast but O(n) since it considers all elements.
ToString
strongly optimizes for usefulness over speed. It should be fine for logging, but if squeezing every bit of performance matters,
you might want to implement your own.
How can I customize equality?
Derive from the type, implement IEquatable<T>.Equals
and override GetHashCode
so that two instances that compare equal also return the same hash code.
Alternatively, the IImutableList
interface provides some methods that allow you to pass an EqualityComparer
.
I'm aware that this is not great, but that's also how records and tuples work.
Allowing you to pass an EqualityComparer
at creation would significantly alter and complicate the design of this type, I think.
Can I use this on .NET Framework?
Yes, provided you are using a .NET Standard 2.0 compatible version (4.6.2 and above, I believe.) Side note: you can use records on .NET Framework.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Bcl.HashCode (>= 1.1.1)
- System.Collections.Immutable (>= 6.0.0)
- System.Text.Json (>= 6.0.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.0.6-alpha | 151 | 4/18/2022 |
0.0.5-alpha | 116 | 4/17/2022 |
0.0.4-alpha | 107 | 4/7/2022 |
0.0.3-alpha | 112 | 4/7/2022 |
0.0.2-alpha | 122 | 4/7/2022 |
0.0.1-alpha | 116 | 3/30/2022 |
Prerelease experimental version