feat: FlatList module with the vocabulary of the FSharp.Core Array module

CHANGELOG.md

@@ -7,10 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+* `FlatList` has every function of the FSharp.Core `Array` module that applies to an immutable array, with its semantics
+  and exceptions, plus `add`, `asMemory`, `asSpan`, `binarySearch`, `binarySearchRange`, `binarySearchRangeWithComparer`,
+  `binarySearchWithComparer`, `indexOf`, `indexOfRange`, `indexOfRangeWith`, `indexOfWith`, `lastIndexOf`,
+  `lastIndexOfRange`, `lastIndexOfRangeWith`, `lastIndexOfWith`, `ofReadOnlySpan`, `ofSpan`, `remove`, `removeMany`,
+  `removeManyWith`, `removeWith`, `replace`, `replaceWith`, `skipLast` and `takeLast`. `remove` and `removeMany` remove by
+  value in `EqualityComparer<'T>.Default`, and the `With` variants take an equality comparer. The functions that wrap a
+  member of `ImmutableArray<'T>` throw what the member throws.
+* The `FSharp.Collections.Immutable.Option.FlatList` and `FSharp.Collections.Immutable.Tuple.FlatList` modules repeat the
+  functions that use value options or struct tuples with options and reference tuples.
+* The `FlatListBuilder` module works on the builder of a flat list: `add`, `addRange`, `blit`, `capacity`, `clear`,
+  `contains`, `drainToFlatList`, `indexOf`, `indexOfRange`, `indexOfRangeWith`, `insertAt`, `insertManyAt`, `item`,
+  `lastIndexOf`, `lastIndexOfRange`, `lastIndexOfRangeWith`, `length`, `remove`, `removeAll`, `removeAt`, `removeMany`,
+  `removeManyAt`, `removeManyWith`, `removeWith`, `replace`, `replaceWith`, `rev`, `setCapacity`, `sort`, `sortRange`,
+  `sortRangeWith`, `sortRangeWithComparer`, `sortWith`, `sortWithComparer`, `toArray` and `updateAt`. The functions that
+  change the builder return it. `replace` and `replaceWith` leave the builder as it is when no element equals the old
+  value, as `ImmutableArray<'T>.Builder.Replace` does, where `FlatList.replace` throws `ArgumentException`.
+* `flatList { }` builds a flat list.
+
 ### Changed
 
 * The package targets `net8.0` and `net10.0`.
 * The package requires FSharp.Core 10.1.301 or later, the first release with `partitionWith`.
+* `FlatList`: the `try*` functions return `voption`; `choose`, `pick` and `tryPick` take functions that return `voption`;
+  the functions that return tuples return struct tuples.
+* `FlatList`: every function throws what the FSharp.Core `Array` function of the same name throws. `take` and `splitAt`
+  throw `InvalidOperationException` for a count beyond the length, where they threw `ArgumentOutOfRangeException`. A
+  default `ImmutableArray` throws `ArgumentNullException`, where it threw `ArgumentException`, and also when it is given
+  as a sequence, where it threw `InvalidOperationException`.
+* `FlatList.sub` has the meaning of `Array.sub`: `sub array startIndex count` returns `count` elements from `startIndex`.
+  It was `sub start stop list`.
+* The nested `FlatList.Builder` module is now the `FlatListBuilder` module.
+
+### Removed
+
+* `FlatList.index`, `indexWith`, `lastIndex` and `lastIndexWith`: use `indexOf`, `indexOfWith`, `lastIndexOf` and
+  `lastIndexOfWith`. They compare in `EqualityComparer<'T>.Default`, where the removed functions compared in F# structural
+  equality: elements that are arrays, or types whose `Equals` differs from F# equality, compare differently.
+* `FlatList.indexRange`, `indexRangeWith`, `lastIndexRange` and `lastIndexRangeWith`: use `indexOfRange`,
+  `indexOfRangeWith`, `lastIndexOfRange` and `lastIndexOfRangeWith`, which take the same arguments and compare as
+  `indexOf` does.
+* `FlatList.indexFrom`, `indexFromWith`, `lastIndexFrom` and `lastIndexFromWith`: use `indexOfRange` and
+  `indexOfRangeWith` with the count `length - startIndex`, and `lastIndexOfRange` and `lastIndexOfRangeWith` with the
+  count `startIndex + 1`.
+* `FlatList.removeAll` and `removeAllWith`: use `removeMany` and `removeManyWith`. They remove one element for each of the
+  given values, as the removed functions did, and `removeMany` compares in `EqualityComparer<'T>.Default` where `removeAll`
+  compared in F# structural equality. The removed functions did not remove the elements that satisfy a predicate: use
+  `filter` with the negated predicate for that.
+* `FlatList.removeRange`: use `removeManyAt`.
 
 ## [1.0.0] - 2020-02-23
 

README.md

@@ -12,7 +12,7 @@ Please also join the [F# Open Source Group](http://fsharp.github.com)
 
 | Module | .NET type | Computation expression |
 |---|---|---|
-| `FlatList` | `ImmutableArray<'T>` | – |
+| `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |

docsSrc/Explanations/Background.md

@@ -26,7 +26,7 @@ While F# has its own built-in immutable collections, System.Collections.Immutabl
 
 | Module | .NET type | Computation expression |
 |---|---|---|
-| `FlatList` | `ImmutableArray<'T>` | – |
+| `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |

docsSrc/index.md

@@ -8,7 +8,7 @@ F# bindings for [System.Collections.Immutable](https://learn.microsoft.com/en-us
 
 | Module | .NET type | Computation expression |
 |---|---|---|
-| `FlatList` | `ImmutableArray<'T>` | – |
+| `FlatList` | `ImmutableArray<'T>` | `flatList { }` |
 | `ImmutableList` | `ImmutableList<'T>` | – |
 | `Stack` | `ImmutableStack<'T>` | – |
 | `Queue` | `ImmutableQueue<'T>` | – |

src/FSharp.Collections.Immutable/ComputationExpressions.fs

@@ -0,0 +1,6 @@
+[<AutoOpen>]
+module FSharp.Collections.Immutable.ComputationExpressions
+
+// ---- Creation ----
+
+let flatList = FlatListCE ()

src/FSharp.Collections.Immutable/ComputationExpressions.fsi

@@ -0,0 +1,21 @@
+/// <summary>
+/// The computation expressions of the collections (ADR 0001, D7).
+/// </summary>
+[<AutoOpen>]
+module FSharp.Collections.Immutable.ComputationExpressions
+
+// ---- Creation ----
+
+/// <summary>Builds a flat list.</summary>
+/// <example id="flatList-1">
+/// <code lang="fsharp">
+/// let squares = flatList {
+///     yield 0
+///     for i in 1..3 do
+///         yield i * i
+///     yield! [ 100; 200 ]
+/// }
+/// </code>
+/// Evaluates to a flat list of 0, 1, 4, 9, 100 and 200.
+/// </example>
+val flatList : FlatListCE

src/FSharp.Collections.Immutable/FSharp.Collections.Immutable.fsproj

@@ -21,14 +21,25 @@
   <ItemGroup>
     <Compile Include="AssemblyInfo.fs" />
     <Compile Include="Helper.fs" />
-    <Compile Include="FlatList.fs" />
+    <Compile Include="FlatList\FlatListTypes.fs" />
+    <Compile Include="FlatList\FlatList.fsi" />
+    <Compile Include="FlatList\FlatList.fs" />
+    <Compile Include="FlatList\FlatListOption.fsi" />
+    <Compile Include="FlatList\FlatListOption.fs" />
+    <Compile Include="FlatList\FlatListTuple.fsi" />
+    <Compile Include="FlatList\FlatListTuple.fs" />
+    <Compile Include="FlatList\FlatListBuilder.fsi" />
+    <Compile Include="FlatList\FlatListBuilder.fs" />
+    <Compile Include="FlatList\FlatListCE.fsi" />
+    <Compile Include="FlatList\FlatListCE.fs" />
     <Compile Include="Stack.fs" />
     <Compile Include="ImmutableList.fs" />
     <Compile Include="Queue.fs" />
     <Compile Include="IndexedSeq.fs" />
     <Compile Include="Maps.fs" />
     <Compile Include="Sets.fs" />
-    <Compile Include="Seq.fs" />
+    <Compile Include="ComputationExpressions.fsi" />
+    <Compile Include="ComputationExpressions.fs" />
   </ItemGroup>
 
   <ItemGroup>