Implement `PeekingNext` transitively over mutable references.

[olson-sean-k]

This PR allows PeekingNext to be used as a trait object just like Iterator, allowing code to accept types like &mut dyn PeekingNext<Item = T> for some item type T. To accomplish this, generic methods now require that Self: Sized and PeekingNext now has a transitive implementation over mutable references to types that implement PeekingNext.

This mirrors the design of the Iterator trait (here and here, for example). See also this discussion on the Rust internals forum.

[olson-sean-k]

I've changed the commit message to emphasize the transitive implementation over mutable references, as this is the most important part of this change. Making PeekingNext object-safe is well and good, but has far less utility today, as it has no methods that can be invoked through such an object and its super-trait Iterator can be used for dynamic dispatch instead.

I think the most compelling reason to land this is that code like this can easily accept both owned and mutably borrowed iterators:

pub fn sprockets(widgets: impl PeekingNext<Item = Widget>) -> impl Iterator<Item = Sprocket> { ... }

Today, this only accepts PeekingNext types by value, but it is not uncommon to use such types through a mutable borrow. Note that PeekingNext enables the use of functions like Itertools::peeking_take_while, which may be important to both the caller of sprockets and the sprockets implementation.

[olson-sean-k]

See also #644, which implements PeekingNext for PeekingTakeWhile. In combination, these changes allow code to generically accept types implementing PeekingNext where Itertools::peeking_take_while can be used by the caller to prepare an iterator and subsequently by a function where restoring items in the originating iterator is important (i.e., the function cannot simply use Iterator::peekable etc., because Iterator::next would unconditionally be called on the originating iterator).

[bors[bot]]

Build succeeded!

The publicly hosted instance of bors-ng is deprecated and will go away soon.

If you want to self-host your own instance, instructions are here. For more help, visit the forum.

If you want to switch to GitHub's built-in merge queue, visit their help page.

• bors build finished