Drop unstable Option::contains, Result::contains, Result::contains_err

[soc]

This is a proposal to drop the three functions Option::contains, Result::contains and Result::contains_err.

The discovery of Option::is_some_with/Result::is_ok_with/Result::is_err_with in #93051 obviates the need for these methods (non-stabilization tracked in #62358).

An additional benefit of change is that it avoids spurious error messages in IDEs, when contains is supplied by a third-party library:

[rustbot]

r? @Mark-Simulacrum

(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

[soc]

@Mark-Simulacrum does this require an API Change Proposal, or is the tracking issue enough?

[scottmcm]

Tagging as T-libs-api, because even if it's unstable, this is that domain not T-libs.

[Mark-Simulacrum]

r? libs-api

[Amanieu]

I started an FCP to close #62358.

[soc]

@Amanieu thanks for having a look! I'd say my motivation is less about

has a better name

as many people found the original ticket in the first place because they intuitively assumed that contains worked (and, let's be real, nobody is going to intuitively discover is_some_with).

It's more about freeing up the name again such that it can be used without getting pestered by rustc/IDEs.

[AaronKutch]

Could we keep just 'Option::contains'? In #62358 which I think closed prematurely, I noted that 'Result::contains' has a ambiguity problem when the type is 'Result<T, T>', but I see no problem with 'Option::contains'. Additionally, we might have 'Result::ok_contains' (instead of the current 'Result::contains') and 'Result::err_contains'. I see no reason why we can't have both these functions and the closure based functions, and get the best of both worlds.

[Amanieu]

The problem with contains is that its use cases are very limited: it's only useful when you are dealing with types that implement PartialEq but not Eq, which is very rare in practice. The more general is_some_and can be used for such rare cases when encountered.

For types that implemented Eq you can just use x == Some(y) instead of x.contains(&y).

[Amanieu]

Actually, my mistake, I misread #20063. It seems that contains is still useful when dealing with checking whether an Option<String> contains a &str. However contains is still fundamentally quite controversial and unlikely to be stabilized: the tracking issue has been opened since 2019. I think it would make more sense to focus on less controversial alternatives such as is_some_and instead.

[soc]

@Amanieu is_some_and(|x| x == y) is not substantially better than the existing map_or(false, |x| x == y). It's neither more intuitive nor does it document intent better than the latter, it's just yet-another variation of the same thing.

I'm not interested in re-litigating contains.

I just want it gone so I can use contains from a third-party crate without getting hassled by IDEs.

[AaronKutch]

I can't believe I forgot about x == Some(y). That and matching for various edge cases should be the preferred method. I saw that an issue was being closed, noticed a subissue, didn't read over the discussion thoroughly. I wish that summary of why contains wasn't worth it had been included in the closing comment

[soc]

I can't believe I forgot about 'x == Some(y)', that and matching for various edge cases should be the preferred method.

y gets moved if does not implement Copy, so it's either the above or x.as_ref() == Some(&y) sometimes. It's been discussed in the old issue.

summary of why 'contains' wasn't worth it

Semantics weren't the issue, to be honest. Option::contains had a very specific value proposition of ...

• ... doing exactly one specific thing ...
• ... better than existing alternatives ...
• ... using the name many people intuitively expected

Take any of that away, and interest crumbles; I'd expect that Option::is_some_with/Result::is_ok_with/Result::is_err_with will go through comparatively unopposed because of this; it's just another combinator whose meaning is only established by the lambda it receives.

[Amanieu]

@bors r+

[bors]

📌 Commit 3aa9f76 has been approved by Amanieu

It is now in the queue for this repository.

[bors]

⌛ Testing commit 3aa9f76 with merge cdbbce0...

[bors]

☀️ Test successful - checks-actions
Approved by: Amanieu
Pushing cdbbce0 to master...

[rust-timer]

Finished benchmarking commit (cdbbce0): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

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

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	0.1%	[0.1%, 0.1%]	1
Regressions ❌ (secondary)	3.0%	[2.7%, 3.4%]	2
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-2.8%	[-3.6%, -1.9%]	2
All ❌✅ (primary)	0.1%	[0.1%, 0.1%]	1

Cycles

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

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