Skip to content

Correct exclusive reductions docs: the initial value is not emitted#423

Merged
FranzBusch merged 1 commit into
apple:mainfrom
adityasingh2400:fix-exclusive-reductions-doc-initial-value
May 27, 2026
Merged

Correct exclusive reductions docs: the initial value is not emitted#423
FranzBusch merged 1 commit into
apple:mainfrom
adityasingh2400:fix-exclusive-reductions-doc-initial-value

Conversation

@adityasingh2400
Copy link
Copy Markdown
Contributor

The documentation for the exclusive reductions overloads says the returned sequence is "the initial value followed by the reduced elements", but that is not what happens. AsyncExclusiveReductionsSequence.Iterator.next() pulls a base element before emitting anything, so the first emitted element is the result of combining the initial value with the first base element, and the initial value itself is never emitted. For an empty base sequence the result is empty rather than a single element containing the initial value.

This is the behavior the existing tests already encode (for example [1, 2, 3, 4].async.reductions("") { ... } is expected to produce ["1", "12", "123", "1234"], not ["", "1", "12", "123", "1234"]), and changing it would be source-breaking. This corrects the documentation to match the implementation instead, as suggested in the issue.

Changes:

  • Rewrite the description and Returns line for all four exclusive overloads (throwing and non-throwing, the value-returning and into: forms) to state that each emitted element is an accumulated result starting from the initial value, that the initial value is not emitted, and that an empty base produces an empty sequence.
  • Add test_reductions_empty and test_throwing_reductions_empty covering the empty-base case, which was previously untested and is the most surprising consequence of the corrected wording.

The inclusive reductions doc comments and the DocC Reductions guide already describe the actual behavior, so they are left unchanged.

Testing: swift build and swift test both pass locally (358 tests, including the two new cases). swift format lint --strict is clean on the changed files.

Resolves #386.

…alue

The doc comments for the exclusive reductions overloads stated that the
returned sequence is "the initial value followed by the reduced elements".
That does not match the behavior: the iterator pulls a base element before
emitting anything, so the first emitted element is the result of combining
the initial value with the first base element, and the initial value is
never emitted. For an empty base sequence the result is empty rather than a
single-element sequence containing the initial value.

This is the behavior the existing tests already pin down, and changing it
would be source-breaking, so this corrects the documentation to match.
Updates all four exclusive overloads (throwing and non-throwing, value and
into:) and adds empty-base tests covering the now-documented edge case.

The inclusive reductions and the DocC Reductions guide already describe the
actual behavior and are left unchanged.
@FranzBusch FranzBusch merged commit 268087d into apple:main May 27, 2026
61 of 62 checks passed
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.

reductions does not return initial value, contrary to documentation

2 participants