org.apache.commons.math3.util

## Class IntegerSequence.Incrementor

- java.lang.Object
- - org.apache.commons.math3.util.IntegerSequence.Incrementor

- All Implemented Interfaces:
    Iterator<Integer>
  Enclosing class:
    IntegerSequence

      public static class IntegerSequence.Incrementor
      extends Object
      implements Iterator<Integer>

  Utility that increments a counter until a maximum is reached, at which point, the instance will by default throw a `MaxCountExceededException`. However, the user is able to override this behaviour by defining a custom `callback`, in order to e.g. select which exception must be thrown.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `IntegerSequence.Incrementor.MaxCountExceededCallback` Defines a method to be called at counter exhaustion.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canIncrement()` Checks whether incrementing the counter `nTimes` is allowed.
    `boolean` | `canIncrement(int nTimes)` Checks whether incrementing the counter several times is allowed.
    `static IntegerSequence.Incrementor` | `create()` Factory method that creates a default instance.
    `int` | `getCount()` Gets the current count.
    `int` | `getMaximalCount()` Gets the upper limit of the counter.
    `boolean` | `hasNext()`
    `void` | `increment()` Adds the increment value to the current iteration count.
    `void` | `increment(int nTimes)` Performs multiple increments.
    `Integer` | `next()`
    `void` | `remove()` Not applicable.
    `IntegerSequence.Incrementor` | `withCallback(IntegerSequence.Incrementor.MaxCountExceededCallback cb)` Creates a new instance with a given callback.
    `IntegerSequence.Incrementor` | `withIncrement(int step)` Creates a new instance with a given increment.
    `IntegerSequence.Incrementor` | `withMaximalCount(int max)` Creates a new instance with a given maximal count.
    `IntegerSequence.Incrementor` | `withStart(int start)` Creates a new instance with a given initial value.

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

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

- - ### Method Detail

    - #### create

          public static IntegerSequence.Incrementor create()

      Factory method that creates a default instance. The initial and maximal values are set to 0. For the new instance to be useful, the maximal count must be set by calling `withMaximalCount`.
      Returns:
        an new instance.

    - #### withStart

          public IntegerSequence.Incrementor withStart(int start)

      Creates a new instance with a given initial value. The counter is reset to the initial value.
      Parameters:
        `start` - Initial value of the counter.
      Returns:
        a new instance.

    - #### withMaximalCount

          public IntegerSequence.Incrementor withMaximalCount(int max)

      Creates a new instance with a given maximal count. The counter is reset to the initial value.
      Parameters:
        `max` - Maximal count.
      Returns:
        a new instance.

    - #### withIncrement

          public IntegerSequence.Incrementor withIncrement(int step)

      Creates a new instance with a given increment. The counter is reset to the initial value.
      Parameters:
        `step` - Increment.
      Returns:
        a new instance.

    - #### withCallback

          public IntegerSequence.Incrementor withCallback(IntegerSequence.Incrementor.MaxCountExceededCallback cb)

      Creates a new instance with a given callback. The counter is reset to the initial value.
      Parameters:
        `cb` - Callback to be called at counter exhaustion.
      Returns:
        a new instance.

    - #### getMaximalCount

          public int getMaximalCount()

      Gets the upper limit of the counter.
      Returns:
        the counter upper limit.

    - #### getCount

          public int getCount()

      Gets the current count.
      Returns:
        the current count.

    - #### canIncrement

          public boolean canIncrement()

      Checks whether incrementing the counter `nTimes` is allowed.
      Returns:
        `false` if calling `increment()` will trigger a `MaxCountExceededException`, `true` otherwise.

    - #### canIncrement

          public boolean canIncrement(int nTimes)

      Checks whether incrementing the counter several times is allowed.
      Parameters:
        `nTimes` - Number of increments.
      Returns:
        `false` if calling `increment(nTimes)` would call the `callback` `true` otherwise.

    - #### increment

          public void increment(int nTimes)
                         throws MaxCountExceededException

      Performs multiple increments.
      Parameters:
        `nTimes` - Number of increments.
      Throws:
        `MaxCountExceededException` - at counter exhaustion.
        `NotStrictlyPositiveException` - if `nTimes <= 0`.
      See Also:
        `increment()`

    - #### increment

          public void increment()
                         throws MaxCountExceededException

      Adds the increment value to the current iteration count. At counter exhaustion, this method will call the `trigger` method of the callback object passed to the `withCallback(MaxCountExceededCallback)` method. If not explicitly set, a default callback is used that will throw a `MaxCountExceededException`.
      Throws:
        `MaxCountExceededException` - at counter exhaustion, unless a custom `callback` has been set.
      See Also:
        `increment(int)`

    - #### hasNext

          public boolean hasNext()

      Specified by:
        `hasNext` in interface `Iterator<Integer>`

    - #### next

          public Integer next()

      Specified by:
        `next` in interface `Iterator<Integer>`

    - #### remove

          public void remove()

      Not applicable.
      Specified by:
        `remove` in interface `Iterator<Integer>`
      Throws:
        `MathUnsupportedOperationException`

Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.