core::iter::from_fn and core::iter::successors documentation does not explain callback function signature

[rick-de-water]

Location

core::iter::from_fn
core::iter::successors

Summary

Both of these functions take callback methods that return an Option<T>. However, nowhere is actually described that this Option<T> is used to detect the end of the iterator (i.e. return Some while there are items, return None when at the end). I was able to deduce how things worked eventually by looking at the examples, but I was definitely a bit confused at first.

There should be a clear description on what the callback is expected to return, not just when the callback is called.

[ranger-ross]

Yeah... core::iter::successors in particular is difficult to understand if you are not familar with the type signature of checked_mul

Perhaps,

---

core::iter::from_fn

Creates a new iterator where each iteration calls the provided closure F: FnMut() -> Option<T>. The iterator will yield the T's returned from the closure until it returns None.

[...]

---

core::iter::successors

Creates a new iterator where each successive item is computed based on the preceding one.

The iterator starts with the given first item (if any) and calls the given FnMut(&T) -> Option<T> closure to compute each item’s successor. The iterator will yield the T's returned from the closure until it returns None.

[...]

[Skgland]

core::iter::from_fn

Creates a new iterator where each iteration calls the provided closure F: FnMut() -> Option<T>. The iterator will yield the T's returned from the closure until it returns None.

[...]

Note that the iterator can resume after None depending on the function, until it returns `None` makes it sound like its a fused iterator.

E.g. this works

fn main() {
    let mut i = 0;
    let mut iter = std::iter::from_fn(move || {
        i += 1;
        if i % 3 == 0 {
            None
        } else {
            Some(i)  
        }
    });
    
    assert_eq!((&mut iter).collect::<Vec<_>>(), [1,2]);
    assert_eq!(iter.next(), Some(4));
    assert_eq!(iter.next(), Some(5));
    assert_eq!(iter.next(), None);
}

play-ground

[ranger-ross]

Note that the iterator can resume after None depending on the function, until it returns None makes it sound like its a fused iterator.

Yeah, that was brought up in #135118 here 👉 #135118 (comment)

I ended up dropping the "until it returns None." part

[hkBst]

@rick-de-water would it help to document that this function argument is essentially the returned iterators next function?

[rick-de-water]

@hkBst Yes, that would work for from_fn. successors is a bit more complicated because it's fused, so explaining that the function won't ever get called again after the first None is also important.