de.caff.generics.mda

## Class MultiDimensionalCharArray

- java.lang.Object
- - de.caff.generics.mda.AbstractBasicMultiDimensionalArray<java.lang.Character>
  - - de.caff.generics.mda.MultiDimensionalCharArray

- All Implemented Interfaces:
    MultiDimensional, MultiDimensionalAccess<java.lang.Character>, MultiDimensionalReadAccess<java.lang.Character>, java.lang.Iterable<java.lang.Character>

      public class MultiDimensionalCharArray
      extends AbstractBasicMultiDimensionalArray<java.lang.Character>

  A multi-dimensional char array.

  There is no enforced limit to the number of dimensions, but internally this is mapped to a standard Java array, which can only hold a limited number of elements.

  Please note that although this implements `MultiDimensionalReadAccess.getElement(int...)` and `MultiDimensionalAccess.setElement(Object, int...)` to be used in generic circumstances the recommended methods for getting and setting are `getValue(int...)` and `setValue(char, int...)` because they avoid unnecessary boxing.

  Since:
    November 01, 2019
  Author:
    Rammi

- - ### Field Summary

    - ### Fields inherited from class de.caff.generics.mda.AbstractBasicMultiDimensionalArray

      `indexLinearizer`

    - ### Fields inherited from interface de.caff.generics.mda.MultiDimensionalReadAccess

      `EMPTY0, EMPTY1, EMPTY2, EMPTY3, EMPTY4, EMPTY5, EMPTY6, EMPTY7`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiDimensionalCharArray(int... sizes)` Constructor.
    `MultiDimensionalCharArray(MultiDimensionalCharArray baseArray, Function1<int[],int[]> indexConverter, int... sizes)` Sub array constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Character` | `change(java.util.function.Function<? super java.lang.Character,? extends java.lang.Character> operator, int... indexes)` Change the value located at the given indexes.
    `char` | `changeValue(CharOperator1 operator, int... indexes)` Change the element at the given index combination.
    `boolean` | `equals(java.lang.Object o)`
    `MultiDimensionalCharArray` | `getCopy()` Get an independent copy.
    `java.lang.Character` | `getElement(int... indexes)` Get the element located at the given indexes.
    `char` | `getValue(int... indexes)` Get the element at the given index combination.
    `int` | `hashCode()`
    `void` | `setElement(java.lang.Character value, int... indexes)` Set the element located at the given indexes.
    `void` | `setValue(char elem, int... indexes)` Set the element at the given index combination.
    `void` | `setValuesFrom(char... values)` Set the elements of this array from the given values.
    `void` | `setValuesFrom(MultiIndexLinearizer.Sequencer sequencer, char... values)` Set the elements of this array from the given values using the defined order.
    `MultiDimensionalCharArray` | `sub(int... indexes)` Get access to a multi-dimensional sub array of this array.

    - ### Methods inherited from class de.caff.generics.mda.AbstractBasicMultiDimensionalArray

      `asLinearArray, asLinearArray, asLinearArray, asLinearArray, getIndexLinearizer, getNumDimensions, getNumElements, getSize, getSizes, iterator, iterator, setFrom, setFrom, setFrom, toLinear, toList, toList, toList, toList`

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

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

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

      `changeAll, changeAll, setAll, setFrom, setFrom`

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

      `empty, linearized, visitAll, visitAll`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### MultiDimensionalCharArray

          public MultiDimensionalCharArray(int... sizes)

      Constructor.
      Parameters:
        `sizes` - of the dimensions of this array, e.g. `(2, 3, 4`} will create an oblong array with size 2 in the first, size 3 in the second, and size 4 in the third dimension, containing `2*3*4 = 24` elements

    - #### MultiDimensionalCharArray

          public MultiDimensionalCharArray(@NotNull
                                           MultiDimensionalCharArray baseArray,
                                           @NotNull
                                           Function1<int[],int[]> indexConverter,
                                           int... sizes)

      Sub array constructor.

      This constructs a new read/write access to the given `baseArray` allowing you to do nearly everything. As this gives a lot of power be sure that the `indexConverter` does "the right thing", otherwise runtime exceptions will occur.

      Parameters:
        `baseArray` - basic array to which accesses to this array are mapped
        `indexConverter` - index converter which converts indexes into this array to indexes into the basic array. Failing to fulfill the restrictions (parameter length has to be the same length as the following `sizes`, and fit into their ranges, and the result indexes have to fit the restrictions of the `baseArray` will result in runtime errors
        `sizes` - sizes of the dimensions of this array

  - ### Method Detail

    - #### getElement

          @NotNull
          public java.lang.Character getElement(int... indexes)

      Description copied from interface: `MultiDimensionalReadAccess`
      Get the element located at the given indexes.
      Parameters:
        `indexes` - `MultiDimensional.getNumDimensions()` indexes inside the bounds defined by `MultiDimensional.getSizes()`
      Returns:
        element located at the given indexes

    - #### setElement

          public void setElement(@NotNull
                                 java.lang.Character value,
                                 int... indexes)

      Description copied from interface: `MultiDimensionalAccess`
      Set the element located at the given indexes.
      Parameters:
        `value` - value to set at the location defined by the given indexes
        `indexes` - `MultiDimensional.getNumDimensions()` indexes inside the bounds defined by `MultiDimensional.getSizes()`

    - #### change

          @NotNull
          public java.lang.Character change(@NotNull
                                                     java.util.function.Function<? super java.lang.Character,? extends java.lang.Character> operator,
                                                     int... indexes)

      Description copied from interface: `MultiDimensionalAccess`
      Change the value located at the given indexes.

      This default implementation is only slightly more efficient than a `get` and `set` sequence, but implementing classes are encouraged to provide better implementations (e.g. the index linearization has only to happen once).

      Parameters:
        `operator` - operator to apply to the value at the location defined by the given indexes. When used on a specialized primitive type array the operator will never receive `null`, and must not return `null`. In other cases this depends on usage.
        `indexes` - `MultiDimensional.getNumDimensions()` indexes inside the bounds defined by `MultiDimensional.getSizes()`
      Returns:
        changed value

    - #### setValuesFrom

          public void setValuesFrom(@NotNull
                                    char... values)

      Set the elements of this array from the given values.

      This uses `MultiIndexLinearizer.getHighFastSequencer()` the internal order to copy values.

      Parameters:
        `values` - values, at least `AbstractBasicMultiDimensionalArray.getNumElements()`

    - #### setValuesFrom

          public void setValuesFrom(@NotNull
                                    MultiIndexLinearizer.Sequencer sequencer,
                                    @NotNull
                                    char... values)

      Set the elements of this array from the given values using the defined order.
      Parameters:
        `sequencer` - sequencer defining the order
        `values` - values, at least

    - #### getValue

          public char getValue(int... indexes)

      Get the element at the given index combination.
      Parameters:
        `indexes` - indexes of the element
      Returns:
        element at the given index

    - #### setValue

          public void setValue(char elem,
                               int... indexes)

      Set the element at the given index combination.
      Parameters:
        `elem` - element to set
        `indexes` - indexes of the element

    - #### changeValue

          public char changeValue(@NotNull
                                  CharOperator1 operator,
                                  int... indexes)

      Change the element at the given index combination.
      Parameters:
        `operator` - operator to apply
        `indexes` - indexes of the element
      Returns:
        changed element value

    - #### sub

          @NotNull
          public MultiDimensionalCharArray sub(int... indexes)

      Get access to a multi-dimensional sub array of this array. The returned array will forward all operations including setting elements to this array.
      Parameters:
        `indexes` - indexes of sub array, negative for open indexes, `0` or positive for fixed indexes, if there are not enough indexes the missing ones are considered open
      Returns:
        multi-dimensional sub array, the number of dimensions is defined by the number of open indexes

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### getCopy

          @NotNull
          public MultiDimensionalCharArray getCopy()

      Get an independent copy.
      Returns:
        independent copy