`only` on iterators

[jdonszelmann]

Proposal

Problem statement

Getting the only item out of a collection isn't hard, but can't be concisely written on like a single line.
While, conceptually, it's quite a simple operation.
At a high level, it represents the conversion of Collection<T> -> Option<T>

Motivating examples or use cases

I ran into this just now when writing some code in the compiler for attributes:

    pub fn get_single_span(&self) -> Option<Span> {
        let mut spans /*: Vec<Span>*/ = self.get_all_spans();
        if spans.len() == 1 { return spans.pop() } else { None }
    }

or, written in terms of iterators (by @yoshuawuyts):

pub fn get_single_span(&self) -> Option<Span> {
    let mut iter = self.get_all_spans().into_iter();
    match iter.next() {
        Some(item) => match iter.next() {
            Some(_) => None,
            None => Some(item),
        None => None,
    }
}

There are various other ways to write the same pattern. If you're okay with references, matching against a 1-length slice for example

Solution sketch

it'd be much clearer in my opinion to have a method like this:

    pub fn get_single_span(&self) -> Option<Span> {
        self.get_all_spans().into_iter().only()
    }

We either implement this as calling .next() twice, returning None if the 2nd next call returns Some. Alternatively, we only implement this on ExactSizeIterator and measure its length first, or at least specialize the ExactSizeIterator case to do so.

Alternatives

I thought about adding this to individual collections first, Vec::single{_ref,_mut} or whatever.
After thinking about it some more however, that'd mean a lot of different methods, including possibly the ones for collections like HashMap which could get the only key/value/both. By making it part of Iterator, you can already express these variants, as well as {_ref_mut} cases using .iter(), .iter_mut() and .into_iter().
Finally, arbitrary iterable collections can enjoy this new api now, as opposed to only the ones we implement it for explicitly.

Another name for this operation could be single()

Links and related work

Discussed this with @WaffleLapkin who also liked the idea :3

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[jdonszelmann]

There seems to also be some precedent in itertools:
https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.at_most_one
and as a crate:
https://crates.io/crates/single

(thanks @JonathanBrouwer)

[JonathanBrouwer]

I love the idea and have had many situations in which I wanted this function, but I do think the name single is better than only:

• There is a semi-popular crate single which uses this name
• This is the name that other languages use:
  • C# single https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.single?view=netframework-4.7.2
  • Kotlin singleOrNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/single-or-null.html
  • Haskell singleListToJust https://hackage-content.haskell.org/package/polysemy-plugin-0.4.5.3/docs/Polysemy-Plugin-Fundep-Utils.html#v:singleListToJust
  • However, Java's guava uses getOnlyElement https://guava.dev/releases/22.0/api/docs/com/google/common/collect/Iterators.html#getOnlyElement-java.util.Iterator-
• EDIT: I think exactly_one (from itertools https://docs.rs/itertools/latest/itertools/trait.Itertools.html#method.exactly_one) would also be a great name, like shepmaster pointed out

[yoshuawuyts]

It took me a sec to realize what this is proposing since the motivating example makes use of a len method. Here is that same example written using only Iterator built-ins:

pub fn get_single_span(&self) -> Option<Span> {
    let mut iter = self.get_all_spans().into_iter();
    match iter.next() {
        Some(item) => match iter.next() {
            Some(_) => None,
            None => Some(item),
        None => None,
    }
}

Which this proposal would enable to instead be written as:

    pub fn get_single_span(&self) -> Option<Span> {
        self.get_all_spans().into_iter().only() // or `.single()`
    }

[shepmaster]

See also Itertools::exactly_one.

[jdonszelmann]

thanks @yoshuawuyts, that's a better expansion. I ran into it while extracting items from a vec, but your version is which is probably closer to the final implementation using iterators <3

[kennytm]

this is a generalization of #576 and a subset of #229 (= rust-lang/rust#81615).

(btw why is #229 marked as ACP-accepted API Change Proposal is accepted (seconded with no objections) ?)

[Amanieu]

We marked #229 as accepted because we are interested in having some API for collecting an iterator into an array. In the @rust-lang/libs-api meeting today we noticed that collect_array from itertools seems to be exactly what we want and we would be happy to have that in the standard library. Would this be good enough for your use case?

[programmerjake]

imo collect_array should instead return Result<[T; N], CollectArrayError<T, N>> where CollectArrayError<T, N> can be turned into an iterator over the items. if you don't want that then it's trivial to write collect_array().ok()

[Amanieu]

I would accept that only if you can show the generated assembly code is the same. I'm concerned about potentially having to copy of the array around multiple times in a way that the optimizer can't eliminate.

[kennytm]

@Amanieu

We marked #229 as accepted because we are interested in having some API for collecting an iterator into an array.

I see. I just find it strange that #229 is accepted and closed but it does not have any associated tracking issues (rust-lang/rust#81615 is not a tracking issue).

[ChrisDenton]

Back when #229 was accepted, ACPs were closed as soon as a libs-api decision was reached. The current policy is, as you say, to only close ACPs after a tracking issue is created.

[jdonszelmann]

@Amanieu

Would this be good enough for your use case?

maybe? I guess it can work for a similar usecase, but I still think exactly_one or single communicates intent quite well?

[Amanieu]

I prefer collect_array because an iterator represents a sequence of items and by collecting into a [x] you are clearly indicating that you expect a sequence of length 1.