Package com.complexible.common.collect

# Interface SkippingIterator<T>

All Superinterfaces:
  `AutoCloseable`, `CloseableIterator<T>`, `Iterator<T>`, `ResettableIterator<T>`

All Known Subinterfaces:
  `PeekingSkippingIterator<T>`

All Known Implementing Classes:
  `AbstractSkippingIterator`, `DelegatingSkippingIterator`, `MarkResetSkippingIterator`

public interface SkippingIterator<T> extends ResettableIterator<T>

Iterator over an ordered data source that is able to jump to a specific element (or the next greater after that). Iterator might return duplicate objects in which case skipping to an element might skip some occurrences of that element.

Since:
  0.6.1
Author:
  Pavel Klinov

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface com.complexible.common.base.CloseableIterator

  `CloseableIterator.AbstractCloseableIterator<T>, CloseableIterator.DelegatingCloseableIterator<T>, CloseableIterator.EmptyCloseableIterator<T>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `UNKNOWN_SIZE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Comparator<T>`
  `comparator()`
  Returns the comparator for this iterator that specifies the order in which the elements are returned.
  `long`
  `estimatedSize()`
  Returns the estimated size of this iterator without advancing the iterator or `UNKNOWN_SIZE` if the estimate is not known.
  `boolean`
  `skipTo(T theElement)`
  Moves the iterators position to the next element which is greater than or equal to `theElement`.
  `default boolean`
  `skipTo(T theElement, T theBound)`
  Same contract as `skipTo(Object)` but skipping is bounded: if the implementation can determine that the next element after target is greater than the bound, it can return false.

  ### Methods inherited from interface com.complexible.common.base.CloseableIterator

  `close`

  ### Methods inherited from interface java.util.Iterator

  `forEachRemaining, hasNext, next, remove`

  ### Methods inherited from interface com.complexible.common.collect.ResettableIterator

  `reset`

- ## Field Details

  - ### UNKNOWN_SIZE

    static final long UNKNOWN_SIZE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### skipTo

    boolean skipTo(T theElement)
    Moves the iterators position to the next element which is greater than or equal to `theElement`.
    Returns:
      true, if such an element exists (in which case the `Iterator.next()` call will return it), false otherwise

  - ### skipTo

    default boolean skipTo(T theElement, T theBound)
    Same contract as `skipTo(Object)` but skipping is bounded: if the implementation can determine that the next element after target is greater than the bound, it can return false. In other words, if the method returns false, no element between the target (incl.) and the bound (incl.) exists. If the method returns true, the next element is definitely greater or equal than the target, but may exceed the bound. If the method returns false, there's no guarantee on the state of the iterator. If it needs to be reused, it must be first reset.
    Parameters:
      `theElement` - the target
      `theBound` - the bound. null means no upper bound.
    Returns:
      true, if an element that is greater than or equal to `theElement` but less than or equal to `theBound` exists.

  - ### comparator

    Comparator<T> comparator()
    Returns the comparator for this iterator that specifies the order in which the elements are returned.

  - ### estimatedSize

    long estimatedSize()
    Returns the estimated size of this iterator without advancing the iterator or `UNKNOWN_SIZE` if the estimate is not known. The estimate is for the whole iterator and will not change after the iterator is advanced. There is no guarantee about the accuracy of the estimate.