feat: add EquatableArray<'T> (step 1 of ADR 0002)

.github/copilot-instructions.md

@@ -37,6 +37,9 @@ module's `.fsi` and the `.fs` on its `.fs`, so that Visual Studio shows them as
 │   │   ├── FlatListTuple.fs / FlatListTuple.fsi        – Tuple namespace overrides
 │   │   ├── FlatListBuilder.fs / FlatListBuilder.fsi
 │   │   └── FlatListCE.fs / FlatListCE.fsi
+│   ├── EquatableArray/                                 – ImmutableArray with value semantics, JSON converter, patterns
+│   │   ├── EquatableArray.fs / EquatableArray.fsi
+│   │   └── EquatableArrayPatterns.fs / EquatableArrayPatterns.fsi
 │   ├── IndexedList/                                    – ImmutableList API surface and builders
 │   │   ├── IndexedListTypes.fs
 │   │   ├── IndexedList.fs / IndexedList.fsi
@@ -116,6 +119,7 @@ module's `.fsi` and the `.fs` on its `.fs`, so that Visual Studio shows them as
 │   │   ├── FrozenSetTuple.fs / FrozenSetTuple.fsi
 │   │   └── FrozenSetCE.fs / FrozenSetCE.fsi
 │   └── ComputationExpressions.fs / .fsi                – the computation expression instances
+├── tests/FSharp.Collections.Immutable.CSharp.Tests/     – MSTest project in C#: collection expressions, ranges, operators
 └── tests/FSharp.Collections.Immutable.Tests/            – MSTest test project
     ├── TestCategories.fs                               – centralized custom test category attributes
     ├── TestCategoriesTests.fs                          – enforces the test category rules
@@ -149,8 +153,10 @@ The modules follow ADR 0001 – Per-collection modules (`docsSrc/Explanations/AD
 
 * [`System.Collections.Immutable`](https://www.nuget.org/packages/System.Collections.Immutable/) – immutable collections foundation
 * [`FSharp.Core`](https://www.nuget.org/packages/FSharp.Core/) – F# language core library
+* [`System.Text.Json`](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/overview) – the JSON converter of `EquatableArray` (shared framework, no package)
 * [`MSTest`](https://github.com/microsoft/testfx) – test framework
 * [`Unquote`](https://github.com/SwensenSoftware/unquote) – expressive assertions for complex checks
+* [`FSharp.SystemTextJson`](https://github.com/Tarmil/FSharp.SystemTextJson) – JSON tests with F# records and unions
 * [`FAKE`](https://fake.build/) – build and release scripting
 * [`Argu`](https://github.com/fsprojects/Argu) – command-line parsing for build tooling
 

CHANGELOG.md

@@ -30,6 +30,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   semantics and exceptions. Its `tryFind`, `tryFindIndex` and `tryPick` return `voption`, `choose` and `tryPick` take
   functions that return `voption`, and `groupBy`, `partition`, `partitionWith` and `zip` return struct tuples; the
   `Parallel` modules of the `Option` and `Tuple` namespaces repeat them with options and reference tuples.
+* `EquatableArray<'T>`: a struct over one `ImmutableArray<'T>` with value semantics, for fields of records and unions,
+  dictionary and set keys and persisted documents (ADR 0002)
+  * Equality and the hash code use all elements; every caller gets them, C# `==` and `!=` included
+  * Comparison puts shorter arrays first, then orders by the first different element, in the order of F# comparison
+  * The default value is the empty array
+  * Conversion to and from `ImmutableArray<'T>` does not copy; C# collection expressions and ranges work
+  * A System.Text.Json converter that needs no registration
+  * The `EquatableArray` module: `empty`, `ofArray`, `ofImmutableArray`, `ofList`, `ofSeq`, `singleton`,
+    `unsafeOfArray`, `isEmpty`, `length`, `map`, `toImmutableArray`
+  * The struct partial active patterns `Arr0`, `Arr1`, `Arr2`, `Arr3` and `ArrN`
 
 ### Changed
 

Directory.Packages.props

@@ -24,6 +24,7 @@
     <PackageVersion Include="Fake.IO.FileSystem" Version="6.2.0" />
     <PackageVersion Include="Fake.Tools.Git" Version="6.2.0" />
     <PackageVersion Include="Fantomas.FCS" Version="8.0.10" />
+    <PackageVersion Include="FSharp.SystemTextJson" Version="1.4.36" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.11.0" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.402" />
     <PackageVersion Include="MSTest" Version="4.2.3" />

FSharp.Collections.Immutable.slnf

@@ -3,6 +3,7 @@
     "path": "FSharp.Collections.Immutable.slnx",
     "projects": [
       "src\\FSharp.Collections.Immutable\\FSharp.Collections.Immutable.fsproj",
+      "tests\\FSharp.Collections.Immutable.CSharp.Tests\\FSharp.Collections.Immutable.CSharp.Tests.csproj",
       "tests\\FSharp.Collections.Immutable.Tests\\FSharp.Collections.Immutable.Tests.fsproj"
     ]
   }

FSharp.Collections.Immutable.slnx

@@ -13,6 +13,7 @@
     <Project Path="src\FSharp.Collections.Immutable\FSharp.Collections.Immutable.fsproj" />
   </Folder>
   <Folder Name="/tests/">
+    <Project Path="tests\FSharp.Collections.Immutable.CSharp.Tests\FSharp.Collections.Immutable.CSharp.Tests.csproj" />
     <Project Path="tests\FSharp.Collections.Immutable.Tests\FSharp.Collections.Immutable.Tests.fsproj" />
   </Folder>
   <Project Path="build\build.fsproj" />

README.md

@@ -13,6 +13,7 @@ Please also join the [F# Open Source Group](http://fsharp.github.com)
 | Module | .NET type | Computation expression |
 |---|---|---|
 | `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
+| `EquatableArray` | `EquatableArray<'T>`, an `ImmutableArray<'T>` with value equality, comparison and an empty default value | – |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |

docsSrc/Explanations/Background.md

@@ -27,6 +27,7 @@ While F# has its own built-in immutable collections, System.Collections.Immutabl
 | Module | .NET type | Computation expression |
 |---|---|---|
 | `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
+| `EquatableArray` | `EquatableArray<'T>`, an `ImmutableArray<'T>` with value equality, comparison and an empty default value | – |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |

docsSrc/index.md

@@ -9,6 +9,7 @@ F# bindings for [System.Collections.Immutable](https://learn.microsoft.com/en-us
 | Module | .NET type | Computation expression |
 |---|---|---|
 | `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
+| `EquatableArray` | `EquatableArray<'T>`, an `ImmutableArray<'T>` with value equality, comparison and an empty default value | – |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |