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

CHANGELOG.md

@@ -7,10 +7,31 @@ 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`, `indexOf`, `indexOfWith`, `lastIndexOf`,
+  `lastIndexOfWith`, `ofReadOnlySpan`, `ofSpan`, `skipLast`, `sortWithComparer`, `takeLast` and `tryTail`.
+* 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, and `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`, `tryPick` and `unfold` 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 for a count beyond the length, and a default `ImmutableArray` throws `ArgumentNullException`.
+
+### Removed
+
+* `FlatList.index`, `indexWith`, `indexFrom`, `indexFromWith`, `indexRange`, `indexRangeWith` and their `lastIndex`
+  counterparts: use `indexOf`, `indexOfWith`, `lastIndexOf` and `lastIndexOfWith`.
+* `FlatList.removeAll`, `removeAllWith`, `removeRange`, `sortRange`, `sortRangeWith`, `sortRangeWithComparer` and `sub`,
+  and the `ImmutableArray` module alias of `FlatList`.
+* The `Seq` module of conversions between the collections.
 
 ## [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>