[CollinYuanjieRen]

Specialize KMergeBy::fold once only one input remains, while retaining the existing next path for multiple inputs. A pending element preserves advancing the tail before consuming the previous head.

Adds event-order regressions (including non-fused iterators and partial consumption) and single, skewed, and balanced benchmarks. In a Linux aarch64 / Rust 1.95.0 sample with 4096 elements, specialized vs. unspecialized means were approximately 0.534 vs. 6.919 µs (single), 0.608 vs. 6.946 µs (skewed), and 9.795 vs. 9.857 µs (balanced).

Part of #755.

Validated the kmerge specialization tests and Clippy for the affected tests/benchmark and the alloc-only library configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.66%. Comparing base (6814180) to head (2c510fb).
⚠️ Report is 223 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1133      +/-   ##
==========================================
- Coverage   94.38%   93.66%   -0.73%     
==========================================
  Files          48       52       +4     
  Lines        6665     6503     -162     
==========================================
- Hits         6291     6091     -200     
- Misses        374      412      +38     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[phimuemue]

I hope I don't miss the forest for the trees, but counldn't this

• first call f(acc, head),
• then call tail.fold(acc, f)?

[phimuemue]

Isn't this covered by our existing specialization tests? If not, then we should probably add it there and make it generic enough to work for all our specialized folds.

[phimuemue]

Hi there, thanks for this. If we touch this already, can we clean it up a little?

• Eliminate/inline HeadTail::next. It is used only in one place, and it hides that it modifies heap[0].head. Inlining it makes this clear and justifies the subsequent sift_down¹.
• Your specialized fold checks self.heap.len()>1 only to call next().unwrap() afterwards (next internally re-checks the heap's size). This can be made cleaner by e.g. introducing a function KMergeBy::next_on_non_empty_heap(&mut self) -> Self::Item. This function should assert that it is only called with a non-empty heap and should update heap[0] + sift_down. Then, this function could be called repeatedly in fold, avoiding the unwrap.
• folding the last element from heap is possibly simpler by calling f(acc, head), and then tail.fold(acc, f).

Footnotes

1. Preserving invariants, such as "heap's elements have a valid head and you're supposed to call tail.next on it in the next iteration", is often easier if not spread across separate functions. ↩