feat: Add iterator size hints

[peter-jerry-ye]

Design

The goal is to provide a size hint for iterators, which can help reduce allocations. Rust's size_hint uses an always-present lower bound plus an optional upper bound which is rarely used. Here we take a different approach and introduce size_hint, an optional remaining-count hint. For example, map preserves the hint, while filter drops it because the output size is unknown.

The hint is intended to be exact for trusted collection iterators and iterator adapters that can preserve that information, but it is still only a performance hint. User-provided hints are not treated as correctness invariants: negative hints are clamped to zero, consuming an iterator never drives the hint below zero, and an iterator ending early simply updates the hint to Some(0).

Summary

• add remaining-size hint metadata to Iter and expose Iter::size_hint
• make Iter::new and Iter2::new accept size_hint? : Int
• propagate trusted hints through size-preserving iterator adapters and collection iterators, and drop them for filtering/range cases where the output size is unknown
• use hints for preallocation, while keeping iteration correctness independent from the hint value
• tolerate incorrect user-supplied hints by clamping negative and over-consumed hints to zero
• keep construction-time traversal bounds for deque, queue, and linked insertion-order iterators so their hints match the traversal created at iterator construction

Non-goal

Mutating a collection while consuming one of its iterators remains unsupported. Captured bounds and size_hint metadata are only for keeping performance hints aligned with the traversal created at iterator construction; they do not make concurrent mutation supported.

Validation

• moon check
• moon fmt
• moon info
• moon test
• git diff --check

[coveralls]

Coverage Report for CI Build 4245

Coverage increased (+0.02%) to 94.637%

Details

• Coverage increased (+0.02%) from the base build.
• Patch coverage: 293 of 293 lines across 17 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	15736
Covered Lines:	14892
Line Coverage:	94.64%
Coverage Strength:	218076.79 hits per line

---

💛 - Coveralls

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c53b2561f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0e021d96d0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a3d8c8abd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid advertising exact lengths for mutable hash maps

When a caller mutates the map after creating this iterator, the closure scans the current self.entries but the advertised length is the old self.size. For example, let it = map.iter(); map.clear(); leaves it.length() as the old nonzero size, and the first next() returns None with a positive exact length, tripping the new Iter::next debug assertion and misleading callers that use length() for preallocation; the same pattern applies to keys() and values().

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 99f8df93fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid exact hints on mutable sorted-map iterators

If a SortedMap is mutated after iter() is created but before it is consumed, set/remove update the AVL nodes in place, and this traversal starts from the captured root reference and can observe the changed tree. For example, creating an iterator over a one-entry map and then inserting a smaller key makes this iterator yield two entries while still advertising Some(1), so size_hint() underreports the remaining elements; the same pattern applies to the sibling key/value iterators that use self.size as an exact hint.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid exact hints on mutable sorted-set iterators

If a SortedSet is mutated after iter() is created but before it is consumed, add/remove mutate the captured node graph in place, so the iterator can traverse the changed tree while its exact hint remains the old self.size. For instance, creating an iterator over {2} and then adding 1 makes it yield both 1 and 2 while advertising Some(1), which makes size_hint() incorrect for callers that preallocate from it.

Useful? React with 👍 / 👎.