Stream
Date: 2017-02-08

com.github.zafarkhaja.semver.util

## Class Stream<E>

- java.lang.Object
- - com.github.zafarkhaja.semver.util.Stream<E>

- Type Parameters:
    `E` - the type of elements held in this stream
  All Implemented Interfaces:
    java.lang.Iterable<E>

      public class Stream<E>
      extends java.lang.Object
      implements java.lang.Iterable<E>

  A simple stream class used to represent a stream of characters or tokens.
  Since:
    0.7.0
  See Also:
    `VersionParser`, `Lexer`, `ExpressionParser`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Stream.ElementType<E>` The `ElementType` interface represents types of the elements held by this stream and can be used for stream filtering.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Stream(E[] elements)` Constructs a stream containing the specified elements.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `E` | `consume()` Consumes the next element in this stream.
    `<T extends Stream.ElementType<E>> E` | `consume(T... expected)` Consumes the next element in this stream only if it is of the expected types.
    `int` | `currentOffset()` Returns the current offset of this stream.
    `java.util.Iterator<E>` | `iterator()` Returns an iterator over elements that are left in this stream.
    `E` | `lookahead()` Returns the next element in this stream without consuming it.
    `E` | `lookahead(int position)` Returns the element at the specified position in this stream without consuming it.
    `<T extends Stream.ElementType<E>> boolean` | `positiveLookahead(T... expected)` Checks if the next element in this stream is of the expected types.
    `<T extends Stream.ElementType<E>> boolean` | `positiveLookaheadBefore(Stream.ElementType<E> before, T... expected)` Checks if there exists an element in this stream of the expected types before the specified type.
    `<T extends Stream.ElementType<E>> boolean` | `positiveLookaheadUntil(int until, T... expected)` Checks if there is an element in this stream of the expected types until the specified position.
    `void` | `pushBack()` Pushes back one element at a time.
    `E[]` | `toArray()` Returns an array containing all of the elements that are left in this stream.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Stream

          public Stream(E[] elements)

      Constructs a stream containing the specified elements. The stream does not store the real elements but the defensive copy.
      Parameters:
        `elements` - the elements to be streamed

  - ### Method Detail

    - #### consume

          public E consume()

      Consumes the next element in this stream.
      Returns:
        the next element in this stream or `null` if no more elements left

    - #### consume

          public <T extends Stream.ElementType<E>> E consume(T... expected)

      Consumes the next element in this stream only if it is of the expected types.
      Type Parameters:
        `T` - represents the element type of this stream, removes the "unchecked generic array creation for varargs parameter" warnings
      Parameters:
        `expected` - the types which are expected
      Returns:
        the next element in this stream
      Throws:
        `UnexpectedElementException` - if the next element is of an unexpected type

    - #### pushBack

          public void pushBack()

      Pushes back one element at a time.

    - #### lookahead

          public E lookahead()

      Returns the next element in this stream without consuming it.
      Returns:
        the next element in this stream

    - #### lookahead

          public E lookahead(int position)

      Returns the element at the specified position in this stream without consuming it.
      Parameters:
        `position` - the position of the element to return
      Returns:
        the element at the specified position or `null` if no more elements left

    - #### currentOffset

          public int currentOffset()

      Returns the current offset of this stream.
      Returns:
        the current offset of this stream

    - #### positiveLookahead

          public <T extends Stream.ElementType<E>> boolean positiveLookahead(T... expected)

      Checks if the next element in this stream is of the expected types.
      Type Parameters:
        `T` - represents the element type of this stream, removes the "unchecked generic array creation for varargs parameter" warnings
      Parameters:
        `expected` - the expected types
      Returns:
        `true` if the next element is of the expected types or `false` otherwise

    - #### positiveLookaheadBefore

          public <T extends Stream.ElementType<E>> boolean positiveLookaheadBefore(Stream.ElementType<E> before,
                                                                          T... expected)

      Checks if there exists an element in this stream of the expected types before the specified type.
      Type Parameters:
        `T` - represents the element type of this stream, removes the "unchecked generic array creation for varargs parameter" warnings
      Parameters:
        `before` - the type before which to search
        `expected` - the expected types
      Returns:
        `true` if there is an element of the expected types before the specified type or `false` otherwise

    - #### positiveLookaheadUntil

          public <T extends Stream.ElementType<E>> boolean positiveLookaheadUntil(int until,
                                                                         T... expected)

      Checks if there is an element in this stream of the expected types until the specified position.
      Type Parameters:
        `T` - represents the element type of this stream, removes the "unchecked generic array creation for varargs parameter" warnings
      Parameters:
        `until` - the position until which to search
        `expected` - the expected types
      Returns:
        `true` if there is an element of the expected types until the specified position or `false` otherwise

    - #### iterator

          public java.util.Iterator<E> iterator()

      Returns an iterator over elements that are left in this stream.
      Specified by:
        `iterator` in interface `java.lang.Iterable<E>`
      Returns:
        an iterator of the remaining elements in this stream

    - #### toArray

          public E[] toArray()

      Returns an array containing all of the elements that are left in this stream. The returned array is a safe copy.
      Returns:
        an array containing all of elements in this stream