Implement flatten for Option<&Option<T>> and Option<&mut Option<T>>

[Coca162]

Adds .flatten_ref() to get a immutable reference of a nested option and .flatten_mut() for mutable references.

ACP: rust-lang/libs-team#186
Tracking Issue: #149221

[rustbot]

r? @cuviper

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[cuviper]

Please do create an API Change Proposal as linked above.

@rustbot label +T-libs-api -T-libs
r? libs-api

[joshtriplett]

r? libs-api

[bors]

☔ The latest upstream changes (presumably #130829) made this pull request unmergeable. Please resolve the merge conflicts.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[Coca162]

@rustbot label -S-waiting-on-ACP
@rustbot ready

[dtolnay]

Thanks!

View changes since this review

[dtolnay]

@bors r+

[bors]

📌 Commit 0e54845 has been approved by dtolnay

It is now in the queue for this repository.

[bors]

⌛ Testing commit 0e54845 with merge 123588a...

[bors]

☀️ Test successful - checks-actions
Approved by: dtolnay
Pushing 123588a to main...

[github-actions]

What is this?

This is an experimental post-merge analysis report that shows differences in test outcomes between the merged PR and its parent PR.

Comparing 7fefa09 (parent) -> 123588a (this PR)

Test differences

Show 14 test diffs

14 doctest diffs were found. These are ignored, as they are noisy.

Test dashboard

Run

cargo run --manifest-path src/ci/citool/Cargo.toml -- \
    test-dashboard 123588a5bf9250f214e1931a761f814660e69620 --output-dir test-dashboard

And then open test-dashboard/index.html in your browser to see an overview of all executed tests.

Job duration changes

1. dist-aarch64-apple: 6361.2s -> 7172.9s (+12.8%)
2. x86_64-gnu-llvm-20: 4437.7s -> 4987.0s (+12.4%)
3. x86_64-gnu-llvm-20-3: 7314.0s -> 6444.5s (-11.9%)
4. tidy: 184.8s -> 165.1s (-10.7%)
5. aarch64-msvc-2: 6524.4s -> 5851.9s (-10.3%)
6. x86_64-gnu-stable: 8749.0s -> 7956.7s (-9.1%)
7. dist-x86_64-msvc-alt: 9163.2s -> 9956.1s (+8.7%)
8. dist-aarch64-msvc: 6240.1s -> 5776.2s (-7.4%)
9. i686-gnu-1: 8561.7s -> 7935.8s (-7.3%)
10. dist-apple-various: 3973.9s -> 4260.9s (+7.2%)

How to interpret the job duration changes?

Job durations can vary a lot, based on the actual runner instance
that executed the job, system noise, invalidated caches, etc. The table above is provided
mostly for t-infra members, for simpler debugging of potential CI slow-downs.

[rust-timer]

Finished benchmarking commit (123588a): comparison URL.

Overall result: ❌ regressions - no action needed

@rustbot label: -perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	1.7%	[1.7%, 1.7%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-	-	0

Max RSS (memory usage)

This benchmark run did not return any relevant results for this metric.

Cycles

Results (secondary 0.3%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	3.6%	[3.6%, 3.6%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-3.0%	[-3.0%, -3.0%]	1
All ❌✅ (primary)	-	-	0

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 490.488s -> 483.839s (-1.36%)
Artifact size: 390.86 MiB -> 390.87 MiB (0.00%)