de.caff.generics.mda

## Interface MultiIndexLinearizer

- All Superinterfaces:
    MultiDimensional
  All Known Implementing Classes:
    HighFastMultiIndexLinearizer, LowFastMultiIndexLinearizer, MappingMultiIndexLinearizer, PartlyFixedMultiIndexLinearizer

      public interface MultiIndexLinearizer
      extends MultiDimensional

  Accessor for a linear indexed item which provides a multi-dimensional interface.
  Since:
    November 01, 2019
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `MultiIndexLinearizer.BasicSequencer` Basic implementation of a Sequencer.
    `static interface` | `MultiIndexLinearizer.Sequencer` A sequencer creates a multi-index from a linear index.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `OPEN` Special index used for open indexes.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `checkIndex(int dim, int size, int index)` Check a single index.
    `static void` | `checkIndexes(int[] sizes, int... indexes)` Check indexes whether they fulfill the basic restrictions.
    `default MultiIndexLinearizer.Sequencer` | `getHighFastSequencer()` Get a sequencer will create a multi-index by changing the highest dimension most fast.
    `default MultiIndexLinearizer.Sequencer` | `getLowFastSequencer()` Get a sequencer will create a multi-index by changing the lowest dimension most fast.
    `default MultiIndexLinearizer` | `sub(int... fixedIndexes)` Get an indexer which indexes only a part of this linearizer which is defined by keeping some indexes fix.
    `int` | `toLinear(int... indexes)` Get the linear index which represents the given multi-dimensional index.

    - ### Methods inherited from interface de.caff.generics.mda.MultiDimensional

      `getNumDimensions, getNumElements, getSize, getSizes`

- - ### Field Detail

    - #### OPEN

          static final int OPEN

      Special index used for open indexes. This has to be used for `sub(int...)` parameters to define an open index.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### toLinear

          int toLinear(int... indexes)

      Get the linear index which represents the given multi-dimensional index. Please note that the returned values may fall outside of the range defined by `MultiDimensional.getNumElements()` when this linearizer only represents a part of a larger-dimensional multi-index.

      Good practice is to check the incoming index whether they fulfill their bounds. Use `checkIndexes(int[], int...)` for this.

      Parameters:
        `indexes` - `MultiDimensional.getNumDimensions()` indexes inside the ranges defined by `MultiDimensional.getSizes()`
      Returns:
        linearized index

    - #### sub

          default MultiIndexLinearizer sub(int... fixedIndexes)

      Get an indexer which indexes only a part of this linearizer which is defined by keeping some indexes fix.
      Parameters:
        `fixedIndexes` - non-negative values define fixed indexes of sub array, `OPEN` or other negative values are used for indexes which can still be evalutated by the returned linearizer
      Returns:
        tweaked linearizer which accesses only the defined regions

    - #### getHighFastSequencer

          @NotNull
          default MultiIndexLinearizer.Sequencer getHighFastSequencer()

      Get a sequencer will create a multi-index by changing the highest dimension most fast.

      For one-dimensional indexes it behaves the same as `getLowFastSequencer()`.

      Highest fast is the standard way in which multi-indexes are created, so using this sequencer on a non-sub indexer will iterate over the underlying sequence in its natural order allowing for caching effects.

      Returns:
        sequencer which changes the highest dimension fast, and the lowest dimension slow. It works on the same set of dimensions as this linear indexer.

    - #### getLowFastSequencer

          @NotNull
          default MultiIndexLinearizer.Sequencer getLowFastSequencer()

      Get a sequencer will create a multi-index by changing the lowest dimension most fast. For one-dimensional indexes it behaves the same as `getHighFastSequencer()`.
      Returns:
        sequencer which changes the highest dimension fast, and the lowest dimension slow. It works on the same set of dimensions as this linear indexer.

    - #### checkIndexes

          static void checkIndexes(int[] sizes,
                                   int... indexes)

      Check indexes whether they fulfill the basic restrictions. This checks
      - whether both arrays have the same size
      - whether each index falls into the bounds defined by the sizes, i.e. whether it is positive and less than the size of the given dimension.
      Parameters:
        `sizes` - sizes of the dimensions of an array
        `indexes` - indexes into the dimensions of an array
      Throws:
        `java.lang.IllegalArgumentException` - if the lengths of both array differ
        `java.lang.IndexOutOfBoundsException` - if the indexes don't fall into the bounds

    - #### checkIndex

          static void checkIndex(int dim,
                                 int size,
                                 int index)

      Check a single index.
      Parameters:
        `dim` - dimension of the index
        `size` - size of the dimension
        `index` - index
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the indexes don't fall into the bounds