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

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