Skip to content

feat: flatList { } loops over a flat list and an array without boxing - #52

Open
xperiandri wants to merge 1 commit into
mainfrom
feat/flat-list-ce-loops
Open

xperiandri wants to merge 1 commit into
mainfrom
feat/flat-list-ce-loops

Conversation

@xperiandri

Copy link
Copy Markdown
Collaborator

Proposed Changes

A for loop in flatList { } over a flat list boxed the struct and read it through an enumerator object, because the only overload of For took a sequence. FlatListCE gets two more overloads, for FlatList<'U> and for 'U array. The flat list overload reads the array under the flat list directly.

Allocated per call, .NET 10.0.15 Before After
for over a flat list of 10 560 B 504 B
for over an array of 10 536 B 480 B
for over a list of 10 544 B 544 B
nested for over 100 flat lists of 10 20 488 B 12 432 B

The overloads check their argument inside the function that they return. A statement before that function costs one more closure for each loop, so a loop inside a loop would allocate for each inner loop (14 832 B instead of 12 432 B in the last row).

The cost. The compiler chooses the overload by the type of the source, which must be known where the loop is written, as for yield! on main already:

  • let f items = flatList { for item in items do yield item } stops compiling (FS0041) and needs a type annotation;
  • a source of a flexible type such as #seq<string> needs an annotation when the body uses a member of the loop variable.

flatList { } is not in a release yet, so no released code is affected. The changelog and the documentation of the builder say so.

Also in this change:

  • the documentation of FlatList.toSeq states what the conversion costs: one box of 24 bytes whatever the length, and the interfaces that the box implements;
  • a new how-to page, How_Tos/Use_A_Flat_List_With_Sequences, explains when to use the functions of FlatList, Seq and LINQ on a flat list. Every code block was run against this build, and fsdocs build --strict --eval renders the page.

Types of changes

  • 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)

Checklist

  • 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

Eight tests are new, and the test of a default flat list is split into one for the flat list overload and one for a flat list given as a sequence. They cover the order of the elements for each kind of source, nested loops, the type of the loop variable in the body for each kind of source, the null and default checks with the name of the parameter, and which overload the compiler chose, which a test reads from a quotation of the expression, so that no test depends on a measurement.

Each new behaviour was broken once on purpose: renaming the flat list overload fails the test of the chosen overload, and removing the null check of the array overload fails its test.

All 2 789 tests pass on net8.0 and net10.0 in Debug and Release. fantomas --check and CheckOrder pass.

🤖 Generated with Claude Code

`for` gets overloads for `FlatList<'U>` and `'U array`. A loop over a flat list used to box the struct and read it
through an enumerator object, because the only overload took a sequence. The new overloads read the array under the flat
list directly. The check of the argument is in the function that the overload returns, because a statement before it
costs one more closure for each loop, which a loop inside a loop pays for each inner loop.

The compiler chooses the overload by the type of the source, which must be known where the loop is written, as for
`yield!`: a function parameter without a type annotation does not compile as the source of a loop. The changelog and the
documentation of the builder say so.

The documentation of `FlatList.toSeq` states what the conversion costs, and a new how-to page explains when to use the
functions of `FlatList`, `Seq` and LINQ on a flat list.

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

coderabbitai Bot commented Nov 18, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 39 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c79715f1-2ac3-481f-a51a-01dcb8fc196e
Commits

Reviewing files that changed from the base of the PR and between 6b106fc and 95c9739.

Files selected for processing: 6

  • CHANGELOG.md
  • docsSrc/How_Tos/Use_A_Flat_List_With_Sequences.md
  • src/FSharp.Collections.Immutable/FlatList/FlatList.fsi
  • src/FSharp.Collections.Immutable/FlatList/FlatListCE.fs
  • src/FSharp.Collections.Immutable/FlatList/FlatListCE.fsi
  • tests/FSharp.Collections.Immutable.Tests/FlatList/FlatListComputationExpressionTests.fs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The guide incorrectly describes parameterless Count() as a full traversal, although a boxed flat list uses the ICollection<T>.Count fast path in O(1) without creating an enumerator.

1 open issue
What changed in this PR

Reduces allocations in flatList { } loops by adding specialized For overloads for flat lists and arrays, while retaining sequence support.

Changes:

  • Iterates arrays and flat-list backing arrays directly, with validation inside the returned buffers.
  • Adds tests for ordering, nested loops, overload selection, type inference, and invalid sources.
  • Documents sequence-conversion costs, LINQ usage, and source-type annotation requirements.
File Description
FlatListComputationExpressionTests.fs Tests specialized loops and existing sequence behavior.
FlatListCE.fsi Declares the new overloads and documents type-inference requirements.
FlatListCE.fs Implements direct iteration over arrays and flat lists.
FlatList.fsi Explains toSeq boxing costs and collection interfaces.
Use_A_Flat_List_With_Sequences.md Adds guidance on FlatList, Seq, LINQ, and computation expressions.
CHANGELOG.md Records optimized loops and annotation requirements.

Review effort: Balanced

Comment on lines +65 to +67
such as `Sum`, `Count`, `Take` and `OrderBy`, are the methods of `System.Linq.Enumerable`: called on a flat list, they
box it and read it through an enumerator object. `Seq.sum` does the same, so `FlatList.sum` reads a flat list faster
than both.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants