peeking
Returns a PeekingIterator backed by the given iterator.
Calls to the peek method with no intervening calls to Iterator.next do not affect the iteration, and hence return the same object each time. A subsequent call to Iterator.next is guaranteed to return the same object again. For example:
val peekingIterator = Iterators.peekingIterator(Iterators.forArray("a", "b"));
val a1 = peekingIterator.peek() // returns "a"
val a2 = peekingIterator.peek() // also returns "a"
val a3 = peekingIterator.next() // also returns "a"
val a4 = peekingIterator.next() // returns "b"Any structural changes to the underlying iteration (aside from those performed by the iterator's own PeekingIterator.remove method) will leave the iterator in an undefined state.
The returned iterator does not support removal after peeking, as explained by PeekingIterator.remove.
Note: If the given iterator is already a PeekingIterator, it might be returned to the caller, although this is neither guaranteed to occur nor required to be consistent. For example, this method might choose to pass through recognized implementations of PeekingIterator when the behavior of the implementation is known to meet the contract guaranteed by this method.
There is no Iterable equivalent to this method, so use this method to wrap each individual iterator as it is generated.
Receiver
The backing iterator. The PeekingIterator assumes ownership of this iterator, so users should cease making direct calls to it after calling this method.
Return
a peeking iterator backed by that iterator. Apart from the additional PeekingIterator.peek method, this iterator behaves exactly the same as this.