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

A default flat list given as a sequence is rejected with `ArgumentNullException`, as it is
when it is given as a flat list (D6). It converts to a sequence without a check and fails
with `InvalidOperationException` when a function enumerates it, so every function that takes
a sequence calls the new `checkNotDefaultSeq` of `Helper.fs` next to its `null` check:

- `concat` and `transpose` for the outer sequence;
- `except` for the items to exclude, also when the input is empty, and before the input is
  checked, as FSharp.Core checks them;
- `insertManyAt` for the values, after the check of the index, because FSharp.Core
  enumerates the values only then;
- `FlatListBuilder.addRange`, and `for` of the `flatList` expression; `yield!` of a sequence
  uses the helper instead of its own copy of the check.

The signatures document the exceptions.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: xperiandri

src/FSharp.Collections.Immutable/FlatList/FlatList.fs

@@ -360,6 +360,7 @@ let collect (mapping : 'T -> FlatList<'U>) (array : FlatList<'T>) =
 [<CompiledName "Concat">]
 let concat (arrays : seq<FlatList<'T>>) =
     checkNotNull (nameof arrays) arrays
+    checkNotDefaultSeq (nameof arrays) arrays
 
     arrays
     |> Seq.map (fun array -> unwrapArray (nameof arrays) array)
@@ -383,8 +384,13 @@ let insertAt index (value : 'T) (source : FlatList<'T>) =
 
 [<CompiledName "InsertManyAt">]
 let insertManyAt index (values : seq<'T>) (source : FlatList<'T>) =
-    Array.insertManyAt index values (unwrapArray (nameof source) source)
-    |> wrapArray
+    let array = unwrapArray (nameof source) source
+
+    // Array.insertManyAt checks the index before it enumerates the values, so the check of the values comes after it
+    if index >= 0 && index <= array.Length then
+        checkNotDefaultSeq (nameof values) values
+
+    Array.insertManyAt index values array |> wrapArray
 
 [<CompiledName "Map">]
 let map (mapping : 'T -> 'U) (array : FlatList<'T>) =
@@ -441,6 +447,7 @@ let rev (array : FlatList<'T>) = Array.rev (unwrapArray (nameof array) array) |>
 [<CompiledName "Transpose">]
 let transpose (arrays : seq<FlatList<'T>>) =
     checkNotNull (nameof arrays) arrays
+    checkNotDefaultSeq (nameof arrays) arrays
 
     arrays
     |> Seq.map (fun array -> unwrapArray (nameof arrays) array)
@@ -643,6 +650,7 @@ let distinctBy (projection : 'T -> 'Key) (array : FlatList<'T>) =
 let except (itemsToExclude : seq<'T>) (array : FlatList<'T>) =
     // FSharp.Core checks the items to exclude first
     checkNotNull (nameof itemsToExclude) itemsToExclude
+    checkNotDefaultSeq (nameof itemsToExclude) itemsToExclude
     Array.except itemsToExclude (unwrapArray (nameof array) array)
     |> wrapArray
 

src/FSharp.Collections.Immutable/FlatList/FlatList.fsi

@@ -648,7 +648,7 @@ val collect : mapping : ('T -> FlatList<'U>) -> array : FlatList<'T> -> FlatList
 /// <summary>Concatenates a sequence of flat lists.</summary>
 /// <param name="arrays">The flat lists.</param>
 /// <returns>The concatenation.</returns>
-/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="arrays"/> is <see langword="null"/>.</exception>
+/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="arrays"/> is <see langword="null"/> or a default flat list, or contains a default flat list.</exception>
 /// <remarks>O(the total length).</remarks>
 [<CompiledName "Concat">]
 val concat : arrays : seq<FlatList<'T>> -> FlatList<'T>
@@ -683,6 +683,7 @@ val insertAt : index : int -> value : 'T -> source : FlatList<'T> -> FlatList<'T
 /// <param name="values">The values to insert.</param>
 /// <param name="source">The input flat list.</param>
 /// <returns>The flat list with the values.</returns>
+/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="values"/> is <see langword="null"/> or a default flat list.</exception>
 /// <exception cref="T:System.ArgumentException">Thrown when the index is negative or greater than the length.</exception>
 /// <remarks>O(n + m).</remarks>
 [<CompiledName "InsertManyAt">]
@@ -807,6 +808,7 @@ val rev : array : FlatList<'T> -> FlatList<'T>
 /// </summary>
 /// <param name="arrays">The flat lists.</param>
 /// <returns>A flat list whose element i holds the element i of every input flat list.</returns>
+/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="arrays"/> is <see langword="null"/> or a default flat list, or contains a default flat list.</exception>
 /// <exception cref="T:System.ArgumentException">Thrown when the flat lists have different lengths.</exception>
 /// <remarks>
 /// O(the total length).
@@ -1214,7 +1216,7 @@ val distinctBy : projection : ('T -> 'Key) -> array : FlatList<'T> -> FlatList<'
 /// <param name="itemsToExclude">The items to remove.</param>
 /// <param name="array">The input flat list.</param>
 /// <returns>The distinct remaining elements, in their order.</returns>
-/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="itemsToExclude"/> is <see langword="null"/>.</exception>
+/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="itemsToExclude"/> is <see langword="null"/> or a default flat list.</exception>
 /// <remarks>
 /// O(n + m).
 /// </remarks>

src/FSharp.Collections.Immutable/FlatList/FlatListBuilder.fs

@@ -38,6 +38,7 @@ let add (value : 'T) (builder : FlatList<'T>.Builder) =
 
 [<CompiledName "AddRange">]
 let addRange (values : seq<'T>) (builder : FlatList<'T>.Builder) =
+    checkNotDefaultSeq (nameof values) values
     builder.AddRange values
     builder
 

src/FSharp.Collections.Immutable/FlatList/FlatListBuilder.fsi

@@ -80,6 +80,7 @@ val add : value : 'T -> builder : FlatList<'T>.Builder -> FlatList<'T>.Builder
 /// <param name="values">The values to add.</param>
 /// <param name="builder">The builder.</param>
 /// <returns>The same builder.</returns>
+/// <exception cref="T:System.ArgumentNullException">Thrown when <paramref name="values"/> is <see langword="null"/> or a default flat list.</exception>
 [<CompiledName "AddRange">]
 val addRange : values : seq<'T> -> builder : FlatList<'T>.Builder -> FlatList<'T>.Builder
 

src/FSharp.Collections.Immutable/FlatList/FlatListCE.fs

@@ -14,10 +14,7 @@ type FlatListCE () =
 
     member inline _.YieldFrom (items : seq<'T>) : FlatListBuffer<'T> =
         // A default flat list given as a sequence is still a default flat list, as in FlatList.ofSeq (ADR 0001, D6)
-        match items with
-        | :? ImmutableArray<'T> as array -> checkNotDefault (nameof items) array
-        | _ -> ()
-
+        checkNotDefaultSeq (nameof items) items
         fun builder -> builder.AddRange items
 
     member inline _.YieldFrom (items : 'T array) : FlatListBuffer<'T> = fun builder -> builder.AddRange items
@@ -39,6 +36,9 @@ type FlatListCE () =
         fun builder -> delayed () builder
 
     member inline _.For (source : seq<'U>, [<InlineIfLambda>] body : 'U -> FlatListBuffer<'T>) : FlatListBuffer<'T> =
+        // A default flat list is a sequence that fails when it is enumerated; the expression rejects it as yield! does
+        checkNotDefaultSeq (nameof source) source
+
         fun builder ->
             for item in source do
                 body item builder

src/FSharp.Collections.Immutable/FlatList/FlatListCE.fsi

@@ -50,6 +50,7 @@ type FlatListCE =
     member inline Delay : [<InlineIfLambda>] delayed : (unit -> FlatListBuffer<'T>) -> FlatListBuffer<'T>
 
     /// <summary>Adds the elements of the body for each item of a sequence.</summary>
+    /// <exception cref="T:System.ArgumentNullException">Thrown when the sequence is a default flat list.</exception>
     member inline For : source : seq<'U> * [<InlineIfLambda>] body : ('U -> FlatListBuffer<'T>) -> FlatListBuffer<'T>
 
     /// <summary>Adds the elements of the body while the guard holds.</summary>

src/FSharp.Collections.Immutable/Helper.fs

@@ -32,6 +32,21 @@ module internal ImmutableCollectionUtil =
         if array.IsDefault then
             nullArg name
 
+    /// <summary>
+    /// Throws <see cref="T:System.ArgumentNullException"/> for a default <see cref="T:System.Collections.Immutable.ImmutableArray`1"/>
+    /// that is given as a sequence.
+    /// </summary>
+    /// <remarks>
+    /// A default immutable array converts to a sequence without a check, and the sequence fails with
+    /// <see cref="T:System.InvalidOperationException"/> when a function enumerates it, so a function that takes a sequence
+    /// calls this check next to its <see langword="null"/> check (ADR 0001, D6). Any other sequence passes, a
+    /// <see langword="null"/> sequence included.
+    /// </remarks>
+    let inline checkNotDefaultSeq name (source : seq<'T>) =
+        match source with
+        | :? ImmutableArray<'T> as array -> checkNotDefault name array
+        | _ -> ()
+
     /// <summary>
     /// The array under an immutable array, without a copy (ADR 0001, D5).
     /// </summary>