de.caff.generics

## Class Pythonesque

- java.lang.Object
- - de.caff.generics.Pythonesque

-     public final class Pythonesque
      extends java.lang.Object

  Helper class for pythionesque indexing. Python (the computer language) allows arrays and similar to be indexed with negative values with the meaning "count from the back". So the index `-1` will refer to the last element, `-2` to the one before it and so on.

  Note taht `UNMAPPABLE` (same value as `Integer.MIN_VALUE` is handled special. All methods here will throw an `IndexOutOfBoundsException` if the index to map has has is `UNMAPPABLE`. This allows to use this value as a special invalid index indicator even when Pythonesque indexing is used.

  Since:
    December 05, 2021
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ERROR_INDEX_OUT_OF_BOUNDS_FORMAT` Format used for index out of bounds exception.
    `static int` | `UNMAPPABLE` Unmappable index, same as `Integer.MAX_VALUE`.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `map(int index, int size)` Map a possibly negative index from an indexable of a given size to the standard Java index.
    `static int` | `map(int index, Sizeable indexable)` Map a possibly negative index from an indexable of a given size to the standard Java index.
    `static int` | `mapLB(int index, int size)` Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound.
    `static int` | `mapLB(int index, Sizeable indexable)` Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound.
    `static int` | `mapUB(int index, int size)` Map a possibly negative index from an indexable of a given size to the standard Java index, and keep an upper bound.
    `static int` | `mapUB(int index, Sizeable indexable)` Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound.
    `static int` | `mapX(int index, int size)` Map a possibly negative index from an indexable of a given size to the standard Java index.
    `static int` | `mapX(int index, Sizeable indexable)` Map a possibly negative index from an indexable of a given size to the standard Java index.

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

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

- - ### Field Detail

    - #### UNMAPPABLE

          public static final int UNMAPPABLE

      Unmappable index, same as `Integer.MAX_VALUE`. This index can be used as an impossible result even if Pythonesque indexing is used, as it is not mappable. The mapping methods here will all throw an `IndexOutOfBoundsException` if called with an index of `UNMAPPABLE`.
      See Also:
        Constant Field Values

    - #### ERROR_INDEX_OUT_OF_BOUNDS_FORMAT

          public static final java.lang.String ERROR_INDEX_OUT_OF_BOUNDS_FORMAT

      Format used for index out of bounds exception.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### map

          public static int map(int index,
                                int size)

      Map a possibly negative index from an indexable of a given size to the standard Java index. This method will not check the parameters for sanity.
      Parameters:
        `index` - index to be mapped, must not be `UNMAPPABLE`
        `size` - size of the indexable element for which the index is meant
      Returns:
        canonized index, possibly invalid if `index` is outside the range `[-size, size[`
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### map

          public static int map(int index,
                                @NotNull
                                Sizeable indexable)

      Map a possibly negative index from an indexable of a given size to the standard Java index. This method will not check the parameters for sanity.
      Parameters:
        `index` - index to be mapped, must not be `UNMAPPABLE`
        `indexable` - indexable which is inde
      Returns:
        canonized index, possibly invalid if `index` is outside the range `[-size, size[`
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### mapLB

          public static int mapLB(int index,
                                  int size)

      Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound. This method will take care that `0` is returned if a negative index has a magnitude larger than the size.
      Parameters:
        `index` - index to be mapped, must not be `UNMAPPABLE`
        `size` - size of the indexable element for which the index is meant
      Returns:
        canonized index, possibly invalid if `index` is too large
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### mapLB

          public static int mapLB(int index,
                                  @NotNull
                                  Sizeable indexable)

      Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound. This method will take care that `0` is returned if a negative index has a magnitude larger than the size.
      Parameters:
        `index` - index to be mapped, must not be `UNMAPPABLE`
        `indexable` - indexable which is inde
      Returns:
        canonized index, possibly invalid if `index` is too large
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### mapUB

          public static int mapUB(int index,
                                  int size)

      Map a possibly negative index from an indexable of a given size to the standard Java index, and keep an upper bound. This method will take care that `size - 1` is returned if a positive index is larger or queal to size
      Parameters:
        `index` - index to be mapped
        `size` - size of the indexable element for which the index is meant
      Returns:
        canonized index, possibly invalid if `index` is too large
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### mapUB

          public static int mapUB(int index,
                                  @NotNull
                                  Sizeable indexable)

      Map a possibly negative index from an indexable of a given size to the standard Java index, but keep a lower bound. This method will take care that `0` is returned if a negative index has a magnitude larger than the size.
      Parameters:
        `index` - index to be mapped, must not be `UNMAPPABLE`
        `indexable` - indexable which is inde
      Returns:
        canonized index, possibly invalid if `index` is too large
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is `UNMAPPABLE`

    - #### mapX

          public static int mapX(int index,
                                 int size)

      Map a possibly negative index from an indexable of a given size to the standard Java index. This method will throw an `IndexOutOfBoundsException` if `index` is negative and out of range. It will not check positive indices, as it is expected that the returned index is used in a way that it is checked anyway
      Parameters:
        `index` - index to be mapped
        `size` - size of the indexable element for which the index is meant
      Returns:
        canonized index in the range `[0, size[`
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is outside the range `[-size, size[`. Note that this is always true for `UNMAPPABLE`

    - #### mapX

          public static int mapX(int index,
                                 @NotNull
                                 Sizeable indexable)

      Map a possibly negative index from an indexable of a given size to the standard Java index. This method will throw an `IndexOutOfBoundsException` if `index` is negative and out of range. It will not check positive indices, as it is expected that the returned index is used in a way that it is checked anyway
      Parameters:
        `index` - index to be mapped
        `indexable` - indexable which is inde
      Returns:
        canonized index in the range `[0, size[`
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is negative and smaller than `-size`. Note that this is always true for `UNMAPPABLE`