# Package de.caff.generics.mda

Multi-dimensional array access.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  MultiDimensional | Basic interface for accessing indexable multi-dimensional items.
  MultiDimensionalAccess<T> | Multi-dimensional read-write access.
  MultiDimensionalReadAccess<T> | Multi-dimensional read access.
  MultiIndexLinearizer | Accessor for a linear indexed item which provides a multi-dimensional interface.
  MultiIndexLinearizer.Sequencer | A sequencer creates a multi-index from a linear index.
  OneDimensionalAccess<T> | A fixed-size one-dimensional array of items.
  OneDimensionalBooleanAccess | Read/write access for 1-dimensional boolean arrays.
  OneDimensionalBooleanReadAccess | Read access for 1-dimensional boolean arrays.
  OneDimensionalByteAccess | Read/write access for 1-dimensional byte arrays.
  OneDimensionalByteReadAccess | Read access for 1-dimensional byte arrays.
  OneDimensionalCharAccess | Read/write access for 1-dimensional char arrays.
  OneDimensionalCharReadAccess | Read access for 1-dimensional char arrays.
  OneDimensionalDoubleAccess | Read/write access for 1-dimensional double arrays.
  OneDimensionalDoubleReadAccess | Read access for 1-dimensional double arrays.
  OneDimensionalFloatAccess | Read/write access for 1-dimensional float arrays.
  OneDimensionalFloatReadAccess | Read access for 1-dimensional float arrays.
  OneDimensionalIntAccess | Read/write access for 1-dimensional int arrays.
  OneDimensionalIntReadAccess | Read access for 1-dimensional int arrays.
  OneDimensionalLongAccess | Read/write access for 1-dimensional long arrays.
  OneDimensionalLongReadAccess | Read access for 1-dimensional long arrays.
  OneDimensionalReadAccess<T> | A one-dimensional read-only interface.
  OneDimensionalShortAccess | Read/write access for 1-dimensional short arrays.
  OneDimensionalShortReadAccess | Read access for 1-dimensional short arrays.
  ThreeDimensionalAccess<T> | A 3-dimensional rectangular array of items.
  ThreeDimensionalBooleanAccess | Read/write access for 3-dimensional rectangular boolean arrays.
  ThreeDimensionalBooleanReadAccess | Read access for 3-dimensional rectangular boolean arrays.
  ThreeDimensionalByteAccess | Read/write access for 3-dimensional rectangular byte arrays.
  ThreeDimensionalByteReadAccess | Read access for 3-dimensional rectangular byte arrays.
  ThreeDimensionalCharAccess | Read/write access for 3-dimensional rectangular char arrays.
  ThreeDimensionalCharReadAccess | Read access for 3-dimensional rectangular char arrays.
  ThreeDimensionalDoubleAccess | Read/write access for 3-dimensional rectangular double arrays.
  ThreeDimensionalDoubleReadAccess | Read access for 3-dimensional rectangular double arrays.
  ThreeDimensionalFloatAccess | Read/write access for 3-dimensional rectangular float arrays.
  ThreeDimensionalFloatReadAccess | Read access for 3-dimensional rectangular float arrays.
  ThreeDimensionalIntAccess | Read/write access for 3-dimensional rectangular int arrays.
  ThreeDimensionalIntReadAccess | Read access for 3-dimensional rectangular int arrays.
  ThreeDimensionalLongAccess | Read/write access for 3-dimensional rectangular long arrays.
  ThreeDimensionalLongReadAccess | Read access for 3-dimensional rectangular long arrays.
  ThreeDimensionalReadAccess<T> | Read access for 3-dimensional rectangular arrays.
  ThreeDimensionalShortAccess | Read/write access for 3-dimensional rectangular short arrays.
  ThreeDimensionalShortReadAccess | Read access for 3-dimensional rectangular short arrays.
  TwoDimensionalAccess<T> | A two-dimensional rectangular array of items.
  TwoDimensionalBooleanAccess | Read/write access for 2-dimensional rectangular boolean arrays.
  TwoDimensionalBooleanReadAccess | Read access for 2-dimensional rectangular boolean arrays.
  TwoDimensionalByteAccess | Read/write access for 2-dimensional rectangular byte arrays.
  TwoDimensionalByteReadAccess | Read access for 2-dimensional rectangular byte arrays.
  TwoDimensionalCharAccess | Read/write access for 2-dimensional rectangular char arrays.
  TwoDimensionalCharReadAccess | Read access for 2-dimensional rectangular char arrays.
  TwoDimensionalDoubleAccess | Read/write access for 2-dimensional rectangular double arrays.
  TwoDimensionalDoubleReadAccess | Read access for 2-dimensional rectangular double arrays.
  TwoDimensionalFloatAccess | Read/write access for 2-dimensional rectangular float arrays.
  TwoDimensionalFloatReadAccess | Read access for 2-dimensional rectangular float arrays.
  TwoDimensionalIntAccess | Read/write access for 2-dimensional rectangular int arrays.
  TwoDimensionalIntReadAccess | Read access for 2-dimensional rectangular int arrays.
  TwoDimensionalLongAccess | Read/write access for 2-dimensional rectangular long arrays.
  TwoDimensionalLongReadAccess | Read access for 2-dimensional rectangular long arrays.
  TwoDimensionalReadAccess<T> | Read access for 2-dimensional rectangular arrays.
  TwoDimensionalShortAccess | Read/write access for 2-dimensional rectangular short arrays.
  TwoDimensionalShortReadAccess | Read access for 2-dimensional rectangular short arrays.

- Class Summary
  Class | Description
  --- | ---
  AbstractBasicMultiDimensionalArray<T> | Basic implementation of a multi-dimensional array.
  HighFastMultiIndexLinearizer | Simple highest-index fast implementation of a multi-index linearizer.
  LowFastMultiIndexLinearizer | Simple lowest-index fast implementation of a multi-index linearizer.
  MappingMultiIndexLinearizer | Multi-index linearizer which provides an arbitrary mapping.
  MultiDimensionalArray<T> | Implementation of a basic multi-dimensional array.
  MultiDimensionalBooleanArray | A multi-dimensional boolean array.
  MultiDimensionalByteArray | A multi-dimensional byte array.
  MultiDimensionalCharArray | A multi-dimensional char array.
  MultiDimensionalDoubleArray | A multi-dimensional double array.
  MultiDimensionalFloatArray | A multi-dimensional float array.
  MultiDimensionalIntArray | A multi-dimensional int array.
  MultiDimensionalLongArray | A multi-dimensional long array.
  MultiDimensionalShortArray | A multi-dimensional short array.
  MultiIndexLinearizer.BasicSequencer | Basic implementation of a Sequencer.
  OneDimensionalArray<T> | Standard implementation for a 1-dimensional access.
  OneDimensionalBooleanArray | A 1-dimensional array of boolean values.
  OneDimensionalBooleanReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalByteArray | A 1-dimensional array of byte values.
  OneDimensionalByteReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalCharArray | A 1-dimensional array of char values.
  OneDimensionalCharReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalDoubleArray | A 1-dimensional array of double values.
  OneDimensionalDoubleReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalFloatArray | A 1-dimensional array of float values.
  OneDimensionalFloatReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalIntArray | A 1-dimensional array of int values.
  OneDimensionalIntReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalLongArray | A 1-dimensional array of long values.
  OneDimensionalLongReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalReadAccess.Base<TT> | Abstract base class which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  OneDimensionalShortArray | A 1-dimensional array of short values.
  OneDimensionalShortReadAccess.Base | Abstract base class implementing this interface which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
  PartlyFixedMultiIndexLinearizer | A multi-index linearizer which keeps some indexes fix and only allows to set the remaining ones.
  SmallTwoDimensionalArray<T> | Two-dimensional array of objkects values optimized for small sizes.
  SmallTwoDimensionalBitArray | Two-dimensional array of boolean values optimized for small sizes.
  SmallTwoDimensionalBooleanArray | Two-dimensional array of boolean values optimized for small sizes.
  SmallTwoDimensionalByteArray | Two-dimensional array of byte values optimized for small sizes.
  SmallTwoDimensionalCharArray | Two-dimensional array of char values optimized for small sizes.
  SmallTwoDimensionalDoubleArray | Two-dimensional array of double values optimized for small sizes.
  SmallTwoDimensionalFloatArray | Two-dimensional array of float values optimized for small sizes.
  SmallTwoDimensionalIntArray | Two-dimensional array of int values optimized for small sizes.
  SmallTwoDimensionalLongArray | Two-dimensional array of long values optimized for small sizes.
  SmallTwoDimensionalShortArray | Two-dimensional array of short values optimized for small sizes.
  ThreeDimensionalArray<T> | A 4-dimensional array.
  ThreeDimensionalBooleanArray | A 3-dimensional array of boolean values.
  ThreeDimensionalByteArray | A 3-dimensional array of byte values.
  ThreeDimensionalCharArray | A 3-dimensional array of char values.
  ThreeDimensionalDoubleArray | A 3-dimensional array of double values.
  ThreeDimensionalFloatArray | A 3-dimensional array of float values.
  ThreeDimensionalIntArray | A 3-dimensional array of int values.
  ThreeDimensionalLongArray | A 3-dimensional array of long values.
  ThreeDimensionalShortArray | A 3-dimensional array of short values.
  TwoDimensionalArray<T> |
  TwoDimensionalBooleanArray | A two-dimensional array of boolean values.
  TwoDimensionalBooleanReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalByteArray | A two-dimensional array of byte values.
  TwoDimensionalByteReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalCharArray | A two-dimensional array of char values.
  TwoDimensionalCharReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalDoubleArray | A two-dimensional array of double values.
  TwoDimensionalDoubleReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalFloatArray | A two-dimensional array of float values.
  TwoDimensionalFloatReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalIntArray | A two-dimensional array of int values.
  TwoDimensionalIntReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalLongArray | A two-dimensional array of long values.
  TwoDimensionalLongReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalReadAccess.Base<TT> | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.
  TwoDimensionalShortArray | A two-dimensional array of short values.
  TwoDimensionalShortReadAccess.Base | Base class implementing this interface which provides useful default methods for `Object.toString()`, `Object.equals(Object)`, and `Object.hashCode()`.

## Package de.caff.generics.mda Description

Multi-dimensional array access.

This package provides basic implementations for multi-dimensional arrays. Internally these arrays are handled as arrays (for primitive types) or as `ArrayList`s,

Normally you'll either use `MultiDimensionalArray` for standard Java objects or one of the dedicated implementations for primitive Java types:

- `MultiDimensionalBooleanArray`
- `MultiDimensionalByteArray`
- `MultiDimensionalCharArray`
- `MultiDimensionalDoubleArray`
- `MultiDimensionalFloatArray`
- `MultiDimensionalIntArray`
- `MultiDimensionalLongArray`
- `MultiDimensionalShortArray`

The main advantages compared to using multiple standard arrays like `int[][][]` are

- You can easily extract sub arrays with lower dimensionality and access these, even to manipulate the original array.
- The size of the single dimensions is clearly defined.
- The generic implementation is tyoe-safe.

The main disadvantages

- Access is some 10-30 times slower compared to raw arrays.
- You cannot have more that `Integer.MAX_VALUE` elements in the complete array, i.e. for all dimensions together..

If you only have 3 (or 2 or 1) dimensions you can avoid both disadvantages by using one of the dedicated classes for 1-, 2- or 3-dimensional access:

Dedicated fast multi-dimensional arrays.
1-dimensional | 2-dimensional | 3-dimensional | Usage
`OneDimensionalArray` | `TwoDimensionalArray` | `ThreeDimensionalArray` | for general types
`OneDimensionalBooleanArray` | `TwoDimensionalBooleanArray` | `ThreeDimensionalBooleanArray` | for `boolean`
`OneDimensionalCharArray` | `TwoDimensionalCharArray` | `ThreeDimensionalCharArray` | for `char`
`OneDimensionalDoubleArray` | `TwoDimensionalDoubleArray` | `ThreeDimensionalDoubleArray` | for `double`
`OneDimensionalFloatArray` | `TwoDimensionalFloatArray` | `ThreeDimensionalFloatArray` | for `float`
`OneDimensionalIntArray` | `TwoDimensionalIntArray` | `ThreeDimensionalIntArray` | for `int`
`OneDimensionalLongArray` | `TwoDimensionalLongArray` | `ThreeDimensionalLongArray` | for `long`
`OneDimensionalShortArray` | `TwoDimensionalShortArray` | `ThreeDimensionalShortArray` | for `short`

They provide access times comparable to raw arrays when using their `getValueAt()`/–`setValueAt()` methods, but also fulfill the general `MultiDimensionalAccess` contracts. E.g. the 2-dimensional classes allow access of rows or columns as 1-dimensional arrays without the need of copying data.

Examples:

        import static de.caff.generics.tensor.MultiIndexLinearizer.OPEN;
        // [...]
        MultiDimensionalIntArray arr = new MultiDimensionalIntArray(4, 3, 2); // 3D
        arr.setFrom(0,       // 0, 0, 0
                    1,       // 0. 0, 1
                    2,       // 0, 1, 0
                    3,       // 0, 1, 1
                    4,       // 0, 2, 9
                    5,       // 0, 2, 1
                    6,       // 1, 0, 0
                    7,       // 1, 0, 1
                    8,       // 1, 1, 0
                    9,       // 1, 1, 1
                    10,      // 1, 2, 0
                    11,      // 1, 2, 1
                    12,      // 2, 0, 0
                    13,      // 2, 0, 1
                    14,      // 2, 1, 0
                    15,      // 2, 1, 1
                    16,      // 2, 2, 0
                    17,      // 2, 2, 1
                    18,      // 3, 0, 0
                    19,      // 3, 0, 1
                    20,      // 3. 1, 0
                    21,      // 3, 1, 1
                    22,      // 3, 2, 0
                    23);     // 3, 2, 1
        int v = arr.get(2, 2, 1);  // v = 17
        MultiDimensionalIntArray sub1 = arr.sub(1); // sub1 is 2D (3x2) with the values 6,7, 8,9, 10,11
        MultiDimensionalIntArray sub2 = arr.sub(OPEN, 2); // sub2 is 2D (4x2) with 4,5, 10,11, 16,17, 22,23
        MultiDimensionalIntArray sub3 = arr.sub(OPEN, OPEN, 0); // sub3 is 2D (4x3) with all even values
        MultiDimensionalIntArray sub4 = arr.sub(3, 1); // sub4 is 1D (2) with 20, 21
        MultiDimensionalIntArray sub5 = arr.sub(3).sub(1); // sub5 is 1D (2) with 20. 21
        boolean test = sub4.equals(sub5);  // test is true
        MultiDimensionalIntArray sub6 = sub5.getCopy(); // sub6 is 1D (2) with 20, 21
        sub5.set(42, 1);  // In arrays arr, sub4, and sub5 the 21 changes to 42 because they are only views.
                          // In array sub6 the 21 stays untouched.