[xperiandri]

Proposed Changes

Rewrites FlatList (ImmutableArray<'T>) after ADR 0001 (#23), on top of the foundation merged in #25.

• FlatList/FlatList.fsi and FlatList.fs: the root module FSharp.Collections.Immutable.FlatList with 161 functions in the canonical category order, each documented in the signature file with its parameters, result, exceptions and complexity. The set is the FlatList column of ADR Appendix A. It has every function of the FSharp.Core Array module that applies to an immutable array. It has the BCL wrappers (add, asMemory, asSpan, binarySearch, binarySearchRange, binarySearchRangeWithComparer, binarySearchWithComparer, indexOf, indexOfRange, indexOfRangeWith, indexOfWith, lastIndexOf, lastIndexOfRange, lastIndexOfRangeWith, lastIndexOfWith, ofReadOnlySpan, ofSpan, remove, removeMany, removeManyWith, removeWith, replace, replaceWith, sortRange, sortRangeWith, sortRangeWithComparer, sortWithComparer, the builder functions, isDefault, isDefaultOrEmpty). It also has the extras skipLast, takeLast, tryTail, build and update.
• The flat list parameter is array, as in Array. insertAt, insertManyAt, removeAt, removeManyAt and updateAt call it source, as their FSharp.Core 10 counterparts do. So do the removals by value: remove, removeWith, removeMany and removeManyWith.
• sub array startIndex count has the meaning, the exceptions and the messages of Array.sub. It wraps ImmutableArray<'T>.Slice, so an empty or a whole range copies nothing. It compares the count with the length minus the start index. A huge count cannot overflow that check, as it does in Array.sub.
• remove item source and removeWith comparer item source wrap Remove. They remove the first element that equals the item. They return the input itself when no element equals it. removeMany items source and removeManyWith comparer items source wrap RemoveRange. Each value removes the first remaining element that equals it. A value without an equal element removes nothing. removeMany checks the flat list before the items, as RemoveRange does.
• remove and removeMany compare in EqualityComparer<'T>.Default, as indexOf does. The With variants take the equality comparer. contains compares in F# equality. The two differ for nan, which remove removes, and for arrays, which remove compares by reference.
• sortRange index count array, sortRangeWith comparison index count array and sortRangeWithComparer comparer index count array wrap Sort(index, count, comparer). The elements outside the range keep their places. The sort is not stable. sortRange compares in F# generic comparison, as sort does. A range of at most one element, or a range that is sorted, returns the input itself. A range out of range throws ArgumentOutOfRangeException for index or count, as the BCL does.
• indexOfRange startIndex count value array, indexOfRangeWith, lastIndexOfRange and lastIndexOfRangeWith wrap the overloads of IndexOf and LastIndexOf that take a range. They return an index of the flat list, not of the range, and -1 when no element is equal. A search from the back starts at startIndex and goes down over count elements. They throw what the BCL members throw. On .NET 8 and .NET 10 that includes an empty range at a start index that equals the length, and an empty flat list accepts only the range 0, 0. They replace the indexFrom and indexRange families of 1.0.0, which the changelog now says.
• replace oldValue newValue array and replaceWith comparer oldValue newValue array wrap Replace. They replace the first element that equals the old value. They throw ArgumentException when no element does, and they return a new flat list also when the new value equals the old one.
• binarySearchWithComparer comparer value array, binarySearchRange index count value array and binarySearchRangeWithComparer comparer index count value array wrap ImmutableArray.BinarySearch. binarySearchRange compares as binarySearch does, through the cached DefaultComparer<'T>. The other two take the comparer, and null stands for Comparer<'T>.Default. A comparer that throws gives InvalidOperationException with the exception inside. The BCL calls the count of a range length. The functions check index and count first, with the type and the message of the BCL, and name the parameter count. A range beyond the end stays with the BCL.
• FlatList/FlatListTypes.fs holds the FlatList<'T> abbreviation (D2): a root module cannot declare a type of the namespace, and a file of abbreviations needs no signature file (a signature file alone fails with FS0240). Every other file with public API has a signature file: FlatListBuilder.fsi, FlatListCE.fsi and ComputationExpressions.fsi included.
• Most functions unwrap the underlying array without a copy (ImmutableCollectionsMarshal), call the Array function and wrap its fresh result, so they keep the semantics and the exceptions of Array (D5, D6). The range functions repeat the checks of Array.take, skip and splitAt and slice, which copies nothing for an empty or a whole range.
• binarySearch and every sort use F# generic comparison through DefaultComparer<'T> in Helper.fs, one cached comparer per type: a comparer created per call breaks the same-comparer fast paths of the BCL for tuples.
• try* functions return voption, tuples are struct tuples (D3). The root modules Option.FlatList and Tuple.FlatList repeat those functions in the namespaces FSharp.Collections.Immutable.Option and .Tuple with options and reference tuples; opening both, Option last, gives the signatures of the Array module. Per-element tuple producers share one algorithm that takes the tuple constructor, so neither variant pays a second pass.
• FlatListBuilder works on ImmutableArray<'T>.Builder with 36 functions. The functions that change the builder return it. removeWith returns whether it removed an element, as remove does. flatList { } collects into a builder and drains it without a copy when it is full (D7).
• The builder has the searches of a range, insertManyAt, removeAll, removeMany, removeManyAt, removeManyWith, removeWith, replace, replaceWith, the range sorts sortRange, sortRangeWith and sortRangeWithComparer, and blit. They wrap the members of the builder with the same arguments as the functions of the flat list, in the same words. The range sorts are not stable. 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. removeManyAt and blit name the parameters count, target and targetIndex, where the BCL says length, destination and destinationIndex, and they check the ranges in the order and with the messages of the BCL.
• A seq<'T> parameter has one check, checkNotNullOrDefaultSeq. null and a default flat list given as a sequence throw ArgumentNullException for that parameter in concat, transpose, except, insertManyAt, ofSeq, removeMany, removeManyWith, addRange, yield! and for. A default flat list given as a sequence is a boxed value, not null. Without the check, it fails later with another exception.
• The check also finds a default flat list of a derived reference type that arrives as a sequence of a base type, by the covariance of seq: a default FlatList<string> as seq<obj> is an ImmutableArray<string>, which the type test for ImmutableArray<obj> does not see. The type test stays the first step and allocates nothing. For any other object, the check asks for the generic type and reads IsDefault through reflection. It is inline, because the public members of the computation expression call it, and an inline member cannot call an internal function.
• Helper.fs gets the FSharp.Core message texts, exact replicas of its DetailedExceptions helpers, the shared tuple-constructor algorithms, DefaultComparer<'T> and checkNotNullOrDefaultSeq.
• The legacy FlatList.fs and the Seq module of cross conversions are removed.
• Documentation: the changelog lists the new functions and names the replacement of every function of 1.0.0 that is gone. It was checked against the published package, so that Removed and Changed name only what 1.0.0 had: the Seq module and unfold were never released.

Tests (2447 per target framework, 2442 of them new): the shared contract bases of the sequence-like modules (SeqLike as a chain of abstract classes, one file per category, plus SeqCreation and Indexed) compute their expectations with FSharp.Core Array over the enumerated elements. They compare every exception with the mirrored FSharp.Core function. Every case is a data row: DynamicData over the shared Inputs and the sources of each contract, DataRow for constants, so each of the 703 cases of the former loops runs and reports as a test of its own. The tests compare arrays with CollectionAssert. FlatList derives one class per facet and adds tests for default values, shared storage, the extras, the builder, the computation expression and both namespaces. The categories are on the test classes only (D8).

• sub, the range sorts and the removals have 214 tests. They compare the results with Array.sub, with Array.sortWith on the range and with a first-occurrence oracle, in default and in case-insensitive equality. They also check the exceptions, the parameter names and the cases that return the input itself. The test of sub compares the second line of the message too, which names the arguments and the length.
• The 1122 tests of FlatListSearchTests cover the searches of a range of the flat list and of its builder, and the binary searches. Each search runs on every valid range of its inputs, against a search written by hand. The ranges that the BCL rejects run against the BCL member, with the parameter names of the functions. The searches with a comparer run with the comparer that ignores the case.
• The tests of replace, replaceWith and the functions of the builder compare the results with the oracles of FlatListOracles: the removal and the replacement of the first equal element, Array.insertManyAt, Array.removeManyAt and Array.blit. The ranges out of range run against the BCL member. The functions that change the builder are proved to return it.
• Rows pin the sequence check of each function and its parameter name. They also pin the order of the checks: the flat list before the items in removeMany, the items to exclude before the array in except, the index before the values in insertManyAt of the builder. A default FlatList<string> as seq<obj> runs through ofSeq, insertManyAt, except, removeMany, removeManyWith, addRange, yield! and for, and a flat list of strings that is not default must pass.

Types of changes

What types of changes does your code introduce to FSharp.Collections.Immutable?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

try* functions return voption, tuples are struct tuples, take and splitAt throw InvalidOperationException for a count beyond the length, a default flat list throws ArgumentNullException, sub takes the flat list first and has the meaning of Array.sub, and the functions listed under Removed in the changelog are gone. removeAll, removeAllWith and removeRange are among them: removeMany, removeManyWith and removeManyAt do their job, and filter with the negated predicate removes by a predicate. So are the index and lastIndex families: indexOf, indexOfRange and their counterparts replace them, and they compare in EqualityComparer<'T>.Default, where the removed functions compared in F# structural equality. The nested FlatList.Builder module is now FlatListBuilder.

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

Array.concat dereferences a null element array without a check; FlatList.concat and transpose throw ArgumentNullException for a default element, as D6 requires for a default FlatList.

F# ignores [<CompiledName>] on modules, so the modules compile under their F# names (FlatList, Option.FlatList), as the legacy 1.0.0 modules did.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Default-value exception handling is inconsistent, and countBy introduces avoidable linear auxiliary storage.

3 open issues

• ofSeq mishandles default FlatList and throws the wrong exception · New
• AddRange throws NullReferenceException for default mapped FlatList · New
• countBy uses O(n) storage by retaining every input element · New

What changed in this PR

Rewrites FlatList around FSharp.Core’s Array vocabulary, implementing ADR 0001 on the foundation from #25.

Changes:

• Adds expanded collection operations, Option/Tuple variants, builder helpers and flatList { }.
• Introduces shared contract tests and FlatList-specific coverage.
• Removes legacy APIs and documents breaking changes.

File	Description
tests/​FSharp.Collections.Immutable.Tests/​FSharp.Collections.Immutable.Tests.fsproj	Registers new tests and contracts.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListTupleTests.fs	Tests reference-tuple overrides.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListTests.fs	Tests defaults, storage sharing and extras.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListOptionTests.fs	Tests option overrides.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListOps.fs	Connects FlatList to shared contracts.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListContractTests.fs	Instantiates collection contracts.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListComputationExpressionTests.fs	Tests computation-expression behavior.
tests/​FSharp.Collections.Immutable.Tests/​FlatList/​FlatListBuilderTests.fs	Tests builder operations.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqOps.fs	Defines contract operation records.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeTransformationContract.fs	Tests transformations.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeSortingContract.fs	Tests sorting.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeSearchContract.fs	Tests searches.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeRandomContract.fs	Tests random operations.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikePartitioningContract.fs	Tests grouping and ranges.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeFoldingContract.fs	Tests folds and aggregation.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeContract.fs	Completes contracts with conversions.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqLike/​SeqLikeAccessContract.fs	Tests properties and access.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​SeqCreationContract.fs	Tests collection creation.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​IndexedContract.fs	Tests indexed operations.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​ContractBase.fs	Shares oracle and exception helpers.
src/​FSharp.Collections.Immutable/​Seq.fs	Removes cross-conversion module.
src/​FSharp.Collections.Immutable/​Helper.fs	Adds array algorithms and exception helpers.
src/​FSharp.Collections.Immutable/​FSharp.Collections.Immutable.fsproj	Registers replacement modules.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListTuple.fsi	Declares reference-tuple APIs.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListTuple.fs	Implements reference-tuple APIs.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListOption.fsi	Declares option APIs.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListOption.fs	Implements option APIs.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListCE.fs	Implements computation-expression builder.
src/​FSharp.Collections.Immutable/​FlatList/​FlatListBuilder.fs	Adds mutable-builder helpers.
src/​FSharp.Collections.Immutable/​FlatList.fs	Removes legacy implementation.
src/​FSharp.Collections.Immutable/​ComputationExpressions.fs	Exposes flatList.
README.md	Lists computation-expression support.
docsSrc/​index.md	Updates collection overview.
docsSrc/​Explanations/​Background.md	Updates collection support table.
CHANGELOG.md	Records additions and breaking changes.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Default-value handling in yield! and missing required public API signatures remain unresolved.

2 open issues

• Add missing signatures for public FlatList implementation APIs · New
• Default flat list causes NullReferenceException instead of ArgumentNullException · New

3 resolved since last review

• countBy uses O(n) storage by retaining every input element
• AddRange throws NullReferenceException for default mapped FlatList
• ofSeq mishandles default FlatList and throws the wrong exception

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The broad breaking API rewrite warrants human validation, and default-value handling remains inconsistent across sequence inputs.

1 open issue

• Validate default flat-list sequence inputs as null · New

2 resolved since last review

• Default flat list causes NullReferenceException instead of ArgumentNullException
• Add missing signatures for public FlatList implementation APIs

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Covariantly widened default flat lists bypass validation and violate the documented exception contract.

1 open issue

• Detect widened default immutable arrays before sequence enumeration · New

1 resolved since last review

• Validate default flat-list sequence inputs as null

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The broad breaking API rewrite needs human confirmation of compatibility and behavior across both target frameworks.

No open issues 🎉

1 resolved since last review

• Detect widened default immutable arrays before sequence enumeration

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The broad breaking API migration requires human validation of compatibility and shared-storage behavior across both target frameworks.

No open issues 🎉

_{Review effort: Balanced}