net.algart.arrays
Class Arrays

java.lang.Object
  net.algart.arrays.Arrays

public class Arrays
extends java.lang.Object

A set of static methods useful for working with AlgART arrays.

This class cannot be instantiated.

AlgART Laboratory 2007-2013

Since:

JDK 1.5

Version:

1.2

Author:

Daniel Alievsky

SMM

public static final SimpleMemoryModel SMM

Contains SimpleMemoryModel.getInstance(). It is just a more compact alternative for the expression "SimpleMemoryModel.getInstance()".

BITS_PER_BIT

public static final int BITS_PER_BIT

The number of bits per every element of bit array: 1. This value is returned by PArray.bitsPerElement() method for instances of BitArray, UpdatableBitArray, MutableBitArray.

See Also:

Constant Field Values

BITS_PER_CHAR

public static final int BITS_PER_CHAR

The number of bits per every element of character array: 16. This value is returned by PArray.bitsPerElement() method for instances of CharArray, UpdatableCharArray, MutableCharArray.

See Also:

Constant Field Values

BITS_PER_BYTE

public static final int BITS_PER_BYTE

The number of bits per every element of byte array: 8. This value is returned by PArray.bitsPerElement() method for instances of ByteArray, UpdatableByteArray, MutableByteArray.

See Also:

Constant Field Values

BITS_PER_SHORT

public static final int BITS_PER_SHORT

The number of bits per every element of short array: 16. This value is returned by PArray.bitsPerElement() method for instances of ShortArray, UpdatableShortArray, MutableShortArray.

See Also:

Constant Field Values

BITS_PER_INT

public static final int BITS_PER_INT

The number of bits per every element of int array: 32. This value is returned by PArray.bitsPerElement() method for instances of IntArray, UpdatableIntArray, MutableIntArray.

See Also:

Constant Field Values

BITS_PER_LONG

public static final int BITS_PER_LONG

The number of bits per every element of long array: 64. This value is returned by PArray.bitsPerElement() method for instances of LongArray, UpdatableLongArray, MutableLongArray.

See Also:

Constant Field Values

BITS_PER_FLOAT

public static final int BITS_PER_FLOAT

The number of bits per every element of float array: 32. This value is returned by PArray.bitsPerElement() method for instances of FloatArray, UpdatableFloatArray, MutableFloatArray.

See Also:

Constant Field Values

BITS_PER_DOUBLE

public static final int BITS_PER_DOUBLE

The number of bits per every element of double array: 64. This value is returned by PArray.bitsPerElement() method for instances of DoubleArray, UpdatableDoubleArray, MutableDoubleArray.

See Also:

Constant Field Values

elementType

public static java.lang.Class<?> elementType(java.lang.Class<? extends PArray> arrayType)

Returns the type of elements corresponding to the passed class of primitive arrays. The passed class must be one of basic interfaces BitArray.class, CharArray.class, ByteArray.class, ShortArray.class, IntArray.class, LongArray.class, FloatArray.class, DoubleArray.class, or their subinterfaces (like UpdatableByteArray.class or MutableIntArray.class), or a class implementing one of these interfaces.

More precisely, this method returns:

• boolean.class for BitArray.class,
• char.class for CharArray.class,
• byte.class for ByteArray.class,
• short.class for ShortArray.class,
• int.class for IntArray).class,
• long.class for LongArray.class,
• float.class for FloatArray.class,
• double.class for DoubleArray.class.

Parameters:

arrayType - the type of some primitive array.

Returns:

the corresponding element type.

Throws:

java.lang.NullPointerException - if the passed argument is null.

java.lang.IllegalArgumentException - if the passed argument is not a class of primitive array.

See Also:

Array.elementType()

type

public static <T extends Array> java.lang.Class<T> type(java.lang.Class<T> arraySupertype,
                                                        java.lang.Class<?> elementType)

Returns the type of immutable, unresizable or resizable arrays, which is a subtype of (or same type as) arraySupertype and corresponds to the passed element type.

Namely, if arraySupertype is not UpdatableArray or its inheritor, returns:

• BitArray.class for boolean.class,
• CharArray.class for char.class,
• ByteArray.class for byte.class,
• ShortArray.class for short.class,
• IntArray.class for int.class,
• LongArray.class for long.class,
• FloatArray.class for float.class,
• DoubleArray.class for double.class,
• ObjectArray.class for all other classes.

If arraySupertype is UpdatableArray or its inheritor, returns:

• UpdatableBitArray.class for boolean.class,
• UpdatableCharArray.class for char.class,
• UpdatableByteArray.class for byte.class,
• UpdatableShortArray.class for short.class,
• UpdatableIntArray.class for int.class,
• UpdatableLongArray.class for long.class,
• UpdatableFloatArray.class for float.class,
• UpdatableDoubleArray.class for double.class,
• UpdatableObjectArray.class for all other classes.

If arraySupertype is MutableArray or its inheritor, returns:

• MutableBitArray.class for boolean.class,
• MutableCharArray.class for char.class,
• MutableByteArray.class for byte.class,
• MutableShortArray.class for short.class,
• MutableIntArray.class for int.class,
• MutableLongArray.class for long.class,
• MutableFloatArray.class for float.class,
• MutableDoubleArray.class for double.class,
• MutableObjectArray.class for all other classes.

Parameters:

arraySupertype - required array supertype.

elementType - required element type.

Returns:

the corresponding array type.

Throws:

java.lang.NullPointerException - if one of the passed arguments is null.

java.lang.ClassCastException - if arraySupertype does not allow storing the required element type (for example, it is PArray, but elementType is not a primitive type).

isBitType

public static boolean isBitType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is BitArray.class, UpdatableBitArray.class or MutableBitArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for bit arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART bit arrays.

isCharType

public static boolean isCharType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is CharArray.class, UpdatableCharArray.class or MutableCharArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for character arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART character arrays.

isByteType

public static boolean isByteType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is ByteArray.class, UpdatableByteArray.class or MutableByteArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for byte arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART byte arrays.

isShortType

public static boolean isShortType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is ShortArray.class, UpdatableShortArray.class or MutableShortArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for short arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART short arrays.

isIntType

public static boolean isIntType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is IntArray.class, UpdatableIntArray.class or MutableIntArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for int arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART int arrays.

isLongType

public static boolean isLongType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is LongArray.class, UpdatableLongArray.class or MutableLongArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for long arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART long arrays.

isFloatType

public static boolean isFloatType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is FloatArray.class, UpdatableFloatArray.class or MutableFloatArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for float arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART float arrays.

isDoubleType

public static boolean isDoubleType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is DoubleArray.class, UpdatableDoubleArray.class or MutableDoubleArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for double arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART double arrays.

isObjectType

public static boolean isObjectType(java.lang.Class<? extends Array> arrayType)

Return true if and only if the passed class is ObjectArray.class, UpdatableObjectArray.class or MutableObjectArray.class (but not some of their subinterfaces or subclasses). These 3 classes are named canonical AlgART array types for object arrays: see Array.type(), Array.updatableType(), Array.mutableType() methods. Returns false if the argument is null.

Parameters:

arrayType - the checked array class.

Returns:

whether the checked class is one of 3 canonical types of AlgART object arrays.

sizeOf

public static long sizeOf(Array array)

Estimates the size in bytes of the array.

More precisely:

1. For BitArray, returns 8*PackedBitArrays.packedLength(array.length()) (8 is the number of bytes in one long value).
2. For other variants of PArray, returns array.length()*sizeOfElement, where sizeOfElement=((PArray)array).bitsPerElement()/8.
3. For combined arrays, returns the sum of the results of this method, recursively called for all AlgART arrays contained in the underlying internal storage.
4. In all other cases, returns -1 ("unknown size"). Also returns -1 in the case #3, if the result of this method for some of arrays in the internal storage is -1.

In a case of calculation overflow, this method returns Long.MAX_VALUE always. (For example, it's possible for an array generated by nDoubleCopies(Long.MAX_VALUE, someFiller) call.)

Parameters:

array - some AlgART array.

Returns:

the estimated size of this array in bytes.

Throws:

java.lang.NullPointerException - if the argument is null.

See Also:

sizeOf(Class, long), sizeOf(Class), Matrices.sizeOf(Matrix)

sizeOf

public static long sizeOf(java.lang.Class<?> elementType,
                          long arrayLength)

Estimates the size in bytes of the array with the given primitive element type and the given length.

More precisely:

• for boolean.class, returns 8*PackedBitArrays.packedLength(arrayLength) (8 is the number of bytes in one long value);
• for char.class, returns 2*arrayLength;
• for byte.class, returns arrayLength;
• for short.class, returns 2*arrayLength;
• for int.class, returns 4*arrayLength;
• for long.class, returns 8*arrayLength;
• for float.class, returns 4*arrayLength;
• for double.class, returns 8*arrayLength;
• for all other cases, returns -1 ("unknown size").

There are two exceptions from these rules:

1. in a case of calculation overflow, this method returns Long.MAX_VALUE always;
2. in a case of negative argument (arrayLength<0), this method returns -1 always.

This method never throws exceptions.

Parameters:

elementType - some primitive element type; may be null, then −1 is returned.

arrayLength - the desired length of the AlgART array.

Returns:

the estimated size of the AlgART array in bytes or −1 if it is unknown.

See Also:

sizeOf(Array)

sizeOf

public static double sizeOf(java.lang.Class<?> elementType)

Returns the size in bytes, required for each element of an array with the given primitive element type.

More precisely:

• for boolean.class, returns 0.125 (¹/₈);
• for char.class, returns 2;
• for byte.class, returns 1;
• for short.class, returns 2;
• for int.class, returns 4;
• for long.class, returns 8;
• for float.class, returns 4;
• for double.class, returns 8;
• for all other cases, returns -1 ("unknown size").

Parameters:

elementType - some primitive element type; may be null, then −1 is returned.

Returns:

the size of each element of the AlgART array in bytes or −1 if it is unknown.

See Also:

sizeOf(Array)

bitsPerElement

public static long bitsPerElement(java.lang.Class<?> elementType)

Returns the size in bits, required for each element of an array with the given primitive element type.

More precisely:

• for boolean.class, returns 1;
• for char.class, returns 16;
• for byte.class, returns 8;
• for short.class, returns 16;
• for int.class, returns 32;
• for long.class, returns 64;
• for float.class, returns 32;
• for double.class, returns 64;
• for all other cases, returns -1 ("unknown size").

Parameters:

elementType - some primitive element type; may be null, then −1 is returned.

Returns:

the size of each element of the AlgART array in bits or −1 if it is unknown.

See Also:

sizeOf(Array), PArray.bitsPerElement()

minPossibleIntegerValue

public static long minPossibleIntegerValue(java.lang.Class<? extends PFixedArray> arrayType)

Returns the minimal possible value, that can be stored in elements of the fixed-point primitive array (byte and short elements are interpreted as unsigned). Namely, returns:

• 0 for BitArray.class (and its inheritors),
• 0 for CharArray.class (and its inheritors),
• 0 for ByteArray.class (and its inheritors),
• 0 for ShortArray.class (and its inheritors),
• Integer.MIN_VALUE for IntArray.class (and its inheritors),
• Long.MIN_VALUE for LongArray.class (and its inheritors).

In all other cases, this method throws IllegalArgumentException.

Parameters:

arrayType - the type of some fixed-point primitive array.

Returns:

the minimal possible value, that can be stored in such arrays.

Throws:

java.lang.NullPointerException - if the passed argument is null.

java.lang.IllegalArgumentException - if the passed argument is not BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray or an inheritor / implementing class of some of these interfaces.

See Also:

PFixedArray.minPossibleValue()

maxPossibleIntegerValue

public static long maxPossibleIntegerValue(java.lang.Class<? extends PFixedArray> arrayType)

Returns the maximal possible value, that can be stored in elements of the fixed-point primitive array (byte and short elements are interpreted as unsigned). Namely, returns:

• 1 for BitArray.class (and its inheritors),
• 0xFFFF for CharArray.class (and its inheritors),
• 0xFF for ByteArray.class (and its inheritors),
• 0xFFFF for ShortArray.class (and its inheritors),
• Integer.MAX_VALUE for IntArray.class (and its inheritors),
• Long.MAX_VALUE for LongArray.class (and its inheritors).

In all other cases, this method throws IllegalArgumentException.

Parameters:

arrayType - the type of some fixed-point primitive array.

Returns:

the maximal possible value, that can be stored in such arrays.

Throws:

java.lang.NullPointerException - if the passed argument is null.

java.lang.IllegalArgumentException - if the passed argument is not BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray or an inheritor / implementing class of some of these interfaces.

See Also:

PFixedArray.maxPossibleValue()

minPossibleValue

public static double minPossibleValue(java.lang.Class<? extends Array> arrayType,
                                      double valueForFloatingPoint)

If arrayType is BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray or an inheritor / implementing class of some of these interfaces, this method is equivalent to (double)minPossibleIntegerValue(arrayType); if arrayType is FloatArray, DoubleArray, ObjectArray or an inheritor / implementing class of some of these interfaces, returns valueForFloatingPoint. In all other cases — for example, if the passed class is a common interface as PArray, that can have different minimal elements — this method throws IllegalArgumentException.

Parameters:

arrayType - the type of some AlgART array.

valueForFloatingPoint - the value returned for floating-point or object array type.

Returns:

the minimal possible value, that can be stored in such fixed-point primitive arrays, or valueForFloatingPoint for other array types.

Throws:

java.lang.NullPointerException - if the passed arrayType is null.

java.lang.IllegalArgumentException - if the passed arrayType is not BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray, ObjectArray or an inheritor / implementing class of some of these interfaces.

See Also:

PArray.minPossibleValue(double)

maxPossibleValue

public static double maxPossibleValue(java.lang.Class<? extends Array> arrayType,
                                      double valueForFloatingPoint)

If arrayType is BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray or an inheritor / implementing class of some of these interfaces, this method is equivalent to (double)maxPossibleIntegerValue(arrayType); if arrayType is FloatArray, DoubleArray, ObjectArray or an inheritor / implementing class of some of these interfaces, returns valueForFloatingPoint. In all other cases — for example, if the passed class is a common interface as PArray, that can have different maximal elements — this method throws IllegalArgumentException.

Parameters:

arrayType - the type of some AlgART array.

valueForFloatingPoint - the value returned for floating-point or object array type.

Returns:

the maximal possible value, that can be stored in such fixed-point primitive arrays, or valueForFloatingPoint for other array types.

Throws:

java.lang.NullPointerException - if the passed arrayType is null.

java.lang.IllegalArgumentException - if the passed arrayType is not BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray, ObjectArray or an inheritor / implementing class of some of these interfaces.

See Also:

PArray.maxPossibleValue(double)

nBitCopies

public static BitArray nBitCopies(long n,
                                  boolean element)

Constructs an immutable unresizable bit array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nCharCopies

public static CharArray nCharCopies(long n,
                                    char element)

Constructs an immutable unresizable char array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nByteCopies

public static ByteArray nByteCopies(long n,
                                    byte element)

Constructs an immutable unresizable byte array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nShortCopies

public static ShortArray nShortCopies(long n,
                                      short element)

Constructs an immutable unresizable short array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nIntCopies

public static IntArray nIntCopies(long n,
                                  int element)

Constructs an immutable unresizable int array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nLongCopies

public static LongArray nLongCopies(long n,
                                    long element)

Constructs an immutable unresizable long array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nFloatCopies

public static FloatArray nFloatCopies(long n,
                                      float element)

Constructs an immutable unresizable float array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nDoubleCopies

public static DoubleArray nDoubleCopies(long n,
                                        double element)

Constructs an immutable unresizable double array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nObjectCopies

public static <T> ObjectArray<T> nObjectCopies(long n,
                                               T element)

Constructs an immutable unresizable Object array consisting of n copies of the specified element. The newly allocated data object is tiny (it contains a single instance of the element).

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.IllegalArgumentException - if n < 0.

nPCopies

public static PArray nPCopies(long n,
                              java.lang.Class<?> elementType,
                              double element)

Constructs an immutable unresizable array consisting of n copies of the specified double element, cast to the specified element type. More precisely, this method returns:

• nBitCopies(n, element != 0) if elementType==boolean.class,
• nCharCopies(n, (char)element) if elementType==char.class,
• nByteCopies(n, (byte)element) if elementType==byte.class,
• nShortCopies(n, (short)element) if elementType==short.class,
• nIntCopies(n, (int)element) if elementType==int.class,
• nLongCopies(n, (long)element) if elementType==long.class,
• nFloatCopies(n, (float)element) if elementType==float.class or
• nDoubleCopies(n, element) if elementType==double.class.

Non-primitive element types are not allowed.

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

elementType - the element type (primitive) of the returned array.

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.NullPointerException - if elementType is null.

java.lang.IllegalArgumentException - if n < 0 or if elementType is not boolean.class, char.class, byte.class, short.class, int.class, long.class, float.class or double.class.

nPFixedCopies

public static PFixedArray nPFixedCopies(long n,
                                        java.lang.Class<?> elementType,
                                        long element)

Constructs an immutable unresizable array consisting of n copies of the specified integer element, cast to the specified element type. More precisely, this method returns:

• nBitCopies(n, element != 0) if elementType==boolean.class,
• nCharCopies(n, (char)element) if elementType==char.class,
• nByteCopies(n, (byte)element) if elementType==byte.class,
• nShortCopies(n, (short)element) if elementType==short.class,
• nIntCopies(n, (int)element) if elementType==int.class or
• nLongCopies(n, element) if elementType==long.class.

All other element types are not allowed.

In the returned array:

• capacity and length will be equal to the passed n argument;
• Array.isNew() method will return true;
• Array.isNewReadOnlyView() method will return false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will do nothing;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

n - the number of elements in the returned array.

elementType - the element type of the returned array (boolean.class, char.class, byte.class, short.class, int.class or long.class).

element - the element to appear repeatedly in the returned array.

Returns:

an immutable unresizable array consisting of n copies of the specified element.

Throws:

java.lang.NullPointerException - if elementType is null.

java.lang.IllegalArgumentException - if n < 0 or if elementType is not boolean.class, char.class, byte.class, short.class, int.class or long.class.

nNullCopies

public static <T> ObjectArray<T> nNullCopies(long n,
                                             java.lang.Class<T> elementType)

The version of nObjectCopies(n, element) method with element=null that allows to specify the element type of the returned array. (For that method, the element type will be element.getClass(), but if element is null, the element type is always Object.class, that leads to problems while copying the created array to another object arrays.)

Parameters:

n - the number of null elements in the returned array.

elementType - the element type of the returned array.

Returns:

an immutable unresizable array consisting of n null elements.

Throws:

java.lang.IllegalArgumentException - if n < 0.

isNCopies

public static boolean isNCopies(Array array)

Returns true if the passed array is not null and was created by one of nXxxCopies methods of this class and, so, all array elements have the same constant value. This fact can be used for optimize loops where some elements are loaded from an array many times, for example:

 for (long disp = 0; disp < a.length(); disp += 1024) {
     if (!(disp > 0 && Arrays.isNCopies(a))) {
         // there is no sense to read data more than 1 time in a case of a constant array
         a.getData(disp, buffer);
     }
     // processing "buffer" Java array
 }
 

Such optimization is performed automatically while accessing a constant array via a data buffer.

Parameters:

array - the checked AlgART array (may be null, than the method returns false).

Returns:

true if the passed array was created by one of nXxxCopies methods of this class.

asIndexFuncArray

public static <T extends PArray> T asIndexFuncArray(Func f,
                                                    java.lang.Class<? extends T> requiredType,
                                                    long length)

Equivalent to asIndexFuncArray(true, f, requiredType, length).

Parameters:

f - the mathematical function used for calculating all result array elements.

requiredType - desired type of the returned array.

length - the length of the returned array.

Returns:

the array, defined by the passed function.

Throws:

java.lang.NullPointerException - if f or requiredType argument is null or if one of x arrays is null.

java.lang.IllegalArgumentException - in the same situations as asIndexFuncArray(boolean, Func, Class, long) method.

asIndexFuncArray

public static <T extends PArray> T asIndexFuncArray(boolean truncateOverflows,
                                                    Func f,
                                                    java.lang.Class<? extends T> requiredType,
                                                    long length)

An analog of the asFuncArray(boolean, Func, Class, PArray...) method, where the passed function is applied not to the elements of some source array, but to the index of the resulting array. In other words, each element #k of the returned array is a result of calling f.get(k). So, this method does not require any source arrays.

The typical example is using ConstantFunc, when this method works alike nXxxCopies methods.

Please read comments to asFuncArray(boolean, Func, Class, PArray...) method about precise details of forming the elements of the returned array on the base of the real result of calling Func.get(double...) method.

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function used for calculating all result array elements.

requiredType - desired type of the returned array.

length - the length of the returned array.

Returns:

the array, defined by the passed function.

Throws:

java.lang.NullPointerException - if f or requiredType argument is null.

java.lang.IllegalArgumentException - if length is negative, or if requiredType is an inheritor of UpdatableArray (returned array must be immutable), or if requiredType is not one of classes BitArray.class, CharArray.class, ByteArray.class, ShortArray.class, IntArray.class, LongArray.class, FloatArray.class or DoubleArray.class. (Also IndexOutOfBoundsException is possible while further attempts to read elements from the returned AlgART array, if the passed function requires some arguments.)

asFuncArray

public static <T extends PArray> T asFuncArray(Func f,
                                               java.lang.Class<? extends T> requiredType,
                                               PArray... x)

Equivalent to asFuncArray(true, f, requiredType, x).

Parameters:

f - the mathematical function applied to all passed AlgART arrays.

requiredType - desired type of the returned array.

x - several AlgART arrays; at least one array must be passed.

Returns:

a view of the passed x arrays, defined by the passed function.

Throws:

java.lang.NullPointerException - if f or requiredType argument is null or if one of x arrays is null.

java.lang.IllegalArgumentException - in the same situations as asFuncArray(boolean, Func, Class, PArray...) method.

SizeMismatchException - if x.length>1 and some of passed arrays have different lengths.

asFuncArray

public static <T extends PArray> T asFuncArray(boolean truncateOverflows,
                                               Func f,
                                               java.lang.Class<? extends T> requiredType,
                                               PArray... x)

Returns an immutable view of the passed x AlgART arrays (with primitive element type), where each element #k is a result of calling f.get(x[0].getDouble(k), x[1].getDouble(k), ...), i.e. the result of the passed function for arguments, equal to the corresponding elements #k in all passed arrays.

The array, returned by this method, is immutable, and its class implements one of the basic interfaces BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray or DoubleArray. The class of desired interface (one of 8 possible classes) must be passed as requiredType argument. For example, if requiredType=ByteArray.class, the returned array implements ByteArray.

If the required result type is not a DoubleArray, then some results of the calculated mathematical function f may not be directly interpreted as elements of the returned array: typecasting is necessary. This method performs necessary typecasting by the following algorithm.

Let's suppose that the source double value (result of calling f function) is v, and the necessary cast value (result of specific getXxx method in the returned array, for example, ByteArray.getByte(long)) is w.

• The simplest case is when the required type is DoubleArray: then w=v.
• If the required type is FloatArray, then w=(float)v.
• If the required type is IntArray, ShortArray, ByteArray or CharArray, then the behavior depends on the truncateOverflows argument.
  • If truncateOverflows is false:
    • w=(int)(long)v for IntArray,
    • w=(short)(long)v&0xFFFF for ShortArray,
    • w=(byte)(long)v&0xFF for ByteArray,
    • w=(char)(long)v for CharArray.
    (ByteArray and ShortArray are considered to be unsigned.) In other words, v is cast to the maximally "wide" long type and then the low 32, 16 or 8 bits of this long value are extracted.
  • If truncateOverflows is true:
    • w=(int)v for IntArray,
    • w=(int)v<0?0:(int)v>0xFFFF?0xFFFF:(int)v for ShortArray,
    • w=(int)v<0?0:(int)v>0xFF?0xFF:(int)v for ByteArray,
    • w=(int)v<0?0:(int)v>0xFFFF?0xFFFF:(char)(int)v for CharArray.
    In other words, v is truncated to the allowed range and then cast to the required integer type.
• If the required type is LongArray, then w=(long)v. According the Java specification, it means v, truncated to long value, if Long.MIN_VALUE<=v<=Long.MAX_VALUE, or the nearest from Long.MIN_VALUE / Long.MAX_VALUE if v is out of this range. In comparison with other integer types, it's possible to say that the truncateOverflows argument is always supposed to be true.
• If the required type is BitArray, then w=true if v!=0.0 or w=false if v==0.0 (C-like agreement).

The x argument is "vararg"; so you may pass a Java array as this argument. In this case, no references to the passed Java array are maintained by the result: it is cloned by this method.

The lengths of all passed x arrays must be equal; in other case, an exception is thrown.

In the returned array:

• capacity and length will be equal to the length of the passed x arrays;
• Array.isNew() method returns false;
• Array.isNewReadOnlyView() method returns false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will call the same methods for all x arrays;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Important note. All calculations in the returned view are performed in the correct left-to-right order. More precisely, it means that any method, accessing the data in the returned array, works in the following (or strictly equivalent) way:

• every data block (sequence of elements) is first fully calculated (on the base the underlying arrays, via the passed function);
• then it is returned to the client (loaded into Java array, copied into another AlgART array, etc.): the result of accessing method is never modified before the data block is completely calculated;
• if there are several calculated data blocks, then the blocks with less indexes of elements are always processed before blocks with greater indexes.

This behavior allows using this method for performing "in-place" algorithms, when the result of this method is copied into one of its x arguments (usually built by SimpleMemoryModel). Moreover, such algorithms will work correctly even if the arguments and the destination array are overlapping subarrays of a single AlgART array, if the starting offset of the destination array is not greater than the starting offsets of the arguments.

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see above).

f - the mathematical function applied to all passed AlgART arrays.

requiredType - desired type of the returned array.

x - several AlgART arrays; at least one array must be passed.

Returns:

a view of the passed x arrays, defined by the passed function.

Throws:

java.lang.NullPointerException - if f or requiredType argument is null or if one of x arrays is null.

java.lang.IllegalArgumentException - if x.length==0 (no arrays passed), or if requiredType is an inheritor of UpdatableArray (returned array must be immutable), or if requiredType is not one of classes BitArray.class, CharArray.class, ByteArray.class, ShortArray.class, IntArray.class, LongArray.class, FloatArray.class or DoubleArray.class, or if the number of passed x arrays is insufficient for calculating the passed f function. (In the last situation, IllegalArgumentException may not occur immediately, but IndexOutOfBoundsException may occur instead of while further attempts to read elements from the returned AlgART array.)

SizeMismatchException - if x.length>1 and some of passed arrays have different lengths.

See Also:

asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...)

asUpdatableFuncArray

public static <T extends UpdatablePArray> T asUpdatableFuncArray(Func.Updatable f,
                                                                 java.lang.Class<? extends T> requiredType,
                                                                 UpdatablePArray... x)

Equivalent to asUpdatableFuncArray(true, f, requiredType, x).

Parameters:

f - the mathematical function applied to all passed AlgART arrays.

requiredType - desired type of the returned array.

x - several AlgART arrays; at least one array must be passed.

Returns:

an updatable view of the passed arrays, defined by the passed function.

Throws:

java.lang.NullPointerException - if requiredType or x argument is null or if one of x arrays is null.

java.lang.IllegalArgumentException - in the same situations as asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...) method.

asUpdatableFuncArray

public static <T extends UpdatablePArray> T asUpdatableFuncArray(boolean truncateOverflows,
                                                                 Func.Updatable f,
                                                                 java.lang.Class<? extends T> requiredType,
                                                                 UpdatablePArray... x)

An extended analog of the asFuncArray(boolean, Func, Class, PArray...) method allowing to create updatable view of the source array.

The asFuncArray(boolean, Func, Class, PArray...) method allows creating immutable views only: you cannot change the original arrays via the returned view. Unlike that, this method returns a mutable (updatable) view. Any changes of the elements in the returned array lead to corresponding changes of the elements of the original (underlying) array. Namely, setting some element #k of the returned view to the value w is equivalent to the following operations:

1. getting the elements #k of the original arrays x by x[0].getDouble(k), x[1].getDouble(k), ... x[n-1].getDouble(k) calls into a temporary array double args[n];
2. calling f.set(args, w) — this call should correct args elements (usually the first element);
3. back saving the elements #k into the original arrays x by x[0].setDouble(k), x[1].setDouble(k), ... x[n-1].setDouble(k) calls.

The stage #1 may be skipped if the number of x arrays is 1. In this case, this method supposes that the f.set(args, w) has enough information to calculate args[0]: the result of the inverse function for w value.

As in the asFuncArray(boolean, Func, Class, PArray...) method, typecasting is required sometimes while setting elements. The rules of typecasting are the same as in that method; in particular, the truncateOverflows is used in the same manner.

The array, returned by this method, is unresizable, and its class implements one of the basic interfaces UpdatableBitArray, UpdatableCharArray, UpdatableByteArray, UpdatableShortArray, UpdatableIntArray, UpdatableLongArray, UpdatableFloatArray or UpdatableDoubleArray. The class of desired interface (one of 8 possible classes) must be passed as requiredType argument. For example, if requiredType=UpdatableByteArray.class or requiredType is some class implementing UpdatableByteArray, the returned array implements UpdatableByteArray.

In the returned array:

• capacity and length will be equal to the length of the passed x arrays;
• Array.isNew() method returns false;
• Array.isNewReadOnlyView() method returns false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will call the same methods for all x arrays;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to all passed AlgART arrays.

requiredType - desired type of the returned array.

x - several AlgART arrays; at least one array must be passed.

Returns:

an updatable view of the passed arrays, defined by the passed function.

Throws:

java.lang.NullPointerException - if f or requiredType argument is null or if one of x arrays is null.

java.lang.IllegalArgumentException - if x.length==0 (no arrays passed), or if requiredType is an inheritor of MutableArray (returned array must be immutable), or if requiredType is not one of classes UpdatableBitArray.class / BitArray.class, UpdatableCharArray.class / CharArray.class, UpdatableByteArray.class / ByteArray.class, UpdatableShortArray.class / ShortArray.class, UpdatableIntArray.class / IntArray.class, UpdatableLongArray.class / LongArray.class, UpdatableFloatArray.class / FloatArray.class or UpdatableDoubleArray.class / DoubleArray.class, or if the number of passed x arrays is insufficient for calculating the passed f function. (In the last situation, IllegalArgumentException may not occur immediately, but IndexOutOfBoundsException may occur instead of while further attempts to read or write elements from / to the returned AlgART array.)

SizeMismatchException - if x.length>1 and some of passed arrays have different lengths.

See Also:

asFuncArray(boolean, Func, Class, PArray...)

applyFunc

public static void applyFunc(ArrayContext context,
                             Func f,
                             UpdatablePArray result,
                             PArray... x)

Equivalent to applyFunc(context, f, true, result, x).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART arrays.

result - the destination array.

x - the source arrays; may be empty; may include result array to provide "in-place" operations.

Throws:

java.lang.NullPointerException - if f, result, x or one of x arrays is null.

java.lang.IllegalArgumentException - if x.length==0 (no arrays passed), or if the number of passed x arrays is insufficient for calculating the passed f function. (In the last situation, IndexOutOfBoundsException may occur instead of while copying data to the result.)

SizeMismatchException - if x.length>1 and some of passed arrays have different lengths.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
                             boolean truncateOverflows,
                             Func f,
                             UpdatablePArray result,
                             PArray... x)

Equivalent to applyFunc(context, f, truncateOverflows, 0, true, result, x).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - the behavior of typecasting: see asFuncArray(boolean, Func, Class, PArray...).

f - the mathematical function applied to the source AlgART arrays.

result - the destination array.

x - the source arrays; may be empty; may include result array to provide "in-place" operations.

Throws:

java.lang.NullPointerException - if f, result, x or one of x arrays is null.

java.lang.IllegalArgumentException - if the number of passed x arrays is insufficient for calculating the passed f function. (In the last situation, IndexOutOfBoundsException may occur instead of while copying data to the result.)

SizeMismatchException - if some of passed arrays (result and some of x arrays) have different lengths.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
                             boolean truncateOverflows,
                             int numberOfTasks,
                             boolean strictMode,
                             Func f,
                             UpdatablePArray result,
                             PArray... x)

Creates a "lazy" array by lazy = asFuncArray(truncateOverflows, f, result.type(), x) call and copies it into the result argument by copy(context, result, lazy, numberOfTasks, strictMode) call.

In addition, this method checks, whether all passed arrays have the same length as result one, and throws an exception in other case.

If no source arrays are passed (x.length==0), the "lazy" array is created by another way: lazy = asIndexFuncArray(truncateOverflows, f, result.type(), result.length()).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - the behavior of typecasting: see asFuncArray(boolean, Func, Class, PArray...).

numberOfTasks - the desired number of parallel tasks; may be 0, then it will be chosen automatically.

strictMode - if false, optimization is allowed even if it can lead to little differences between the lazy and copied elements.

f - the mathematical function applied to the source AlgART arrays.

result - the destination array.

x - the source arrays; may be empty; may include result array to provide "in-place" operations.

Throws:

java.lang.NullPointerException - if f, result, x or one of x arrays is null.

java.lang.IllegalArgumentException - if the number of passed x arrays is insufficient for calculating the passed f function. (In the last situation, IndexOutOfBoundsException may occur instead of while copying data to the result.)

SizeMismatchException - if some of passed arrays (result and some of x arrays) have different lengths.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

isFuncArray

public static boolean isFuncArray(Array array)

Returns true if the passed array is not null functional array, created by this package. More precisely, if returns true if and only if the array is a result of one of the following methods:

• asIndexFuncArray(Func, Class, long),
• asIndexFuncArray(boolean, Func, Class, long),
• asFuncArray(Func, Class, PArray...),
• asFuncArray(boolean, Func, Class, PArray...),
• asUpdatableFuncArray(net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...),
• asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...),

or if the array is the built-in array of some matrix, created by analogous methods in Matrices class:

• asCoordFuncMatrix,
• asFuncMatrix,
• asUpdatableFuncMatrix.

In a case of asFuncArray, asUpdatableFuncArray, asFuncMatrix, asUpdatableFuncMatrix methods, you may get the underlying arrays, passed to those methods in the last argument (or built-in arrays of underlying matrices in a case of Matrices methods) by getUnderlyingArrays(array) call, and get the used mathematical function by getFunc(Array) call.

If the array is an immutable view of another array, created by asUpdatableFuncArray(net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...) or asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...), this method also returns true, and getFunc(Array) also allows to get the used mathematical function. However, if the array is a Array.subArray(long, long) subarray} of some functional array, this method returns false.

Parameters:

array - the checked AlgART array (may be null, than the method returns false).

Returns:

true if the passed array a functional one.

See Also:

isIndexFuncArray(Array)

isIndexFuncArray

public static boolean isIndexFuncArray(Array array)

Returns true if the passed array is not null functional array, created by this package, calculated on the base of array indexes only, not depending on another arrays/matrices. More precisely, it returns true if and only if the array is a result of one of the following calls:

• asIndexFuncArray(Func, Class, long),
• asIndexFuncArray(boolean, Func, Class, long),
• Matrices.asCoordFuncMatrix(Func, Class, long...).array(),
• Matrices.asCoordFuncMatrix(boolean, Func, Class, long...).array()

or by equivalent methods like Matrices.asResized(Matrices.ResizingMethod, Matrix, long...), based on these calls.

Parameters:

array - the checked AlgART array (may be null, than the method returns false).

Returns:

true if the passed array a functional one, calculated on the base of array indexes only.

See Also:

isFuncArray(Array), Matrices.isCoordFuncMatrix(Matrix)

getFunc

public static Func getFunc(Array array)

Returns the mathematical function, used for creating the passed functional array, or throws an exception if this array is not functional. The returned function is the same function that was passed to the method, called to created the passed array:

• asIndexFuncArray(Func, Class, long),
• asIndexFuncArray(boolean, Func, Class, long),
• asFuncArray(Func, Class, PArray...),
• asFuncArray(boolean, Func, Class, PArray...),
• asUpdatableFuncArray(net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...),
• asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...),
• or one of analogous Matrices methods asCoordFuncMatrix, asFuncMatrix, asUpdatableFuncMatrix.

Parameters:

array - the functional AlgART array.

Returns:

the mathematical function, used for creating it.

Throws:

java.lang.NullPointerException - if the argument is null.

java.lang.IllegalArgumentException - if the passed array is not functional, i.e. if isFuncArray(Array) returns false for it.

See Also:

isFuncArray(Array)

getTruncationMode

public static boolean getTruncationMode(Array array)

Returns the value of truncateOverflows argument of asFuncArray(boolean, Func, Class, PArray...) method (or one of its overloaded versions), used for creating the passed functional array, or throws an exception if this array is not functional.

Parameters:

array - the functional AlgART array.

Returns:

the truncation mode, used for creating it.

Throws:

java.lang.NullPointerException - if the argument is null.

java.lang.IllegalArgumentException - if the passed array is not functional, i.e. if isFuncArray(Array) returns false for it.

See Also:

isFuncArray(Array)

getIndexDimensions

public static long[] getIndexDimensions(Array array)

Returns the dimensions of the matrix, coordinates of which are used as arguments of the underlying function in the passed index-based functional array, or throws an exception if this array is not a functional array, calculated on the base of indexes. More precisely, if the passed array is created by the methods

• asIndexFuncArray(Func, Class, long) or
• asIndexFuncArray(boolean, Func, Class, long),

this method returns a Java array with the only element {array.length()}; if the passed array is an underlying array of some matrix m, created by the methods

• Matrices.asCoordFuncMatrix(Func, Class, long...) or
• Matrices.asCoordFuncMatrix(boolean, Func, Class, long...),

this method returns the matrix dimensions m.dimensions(); in other cases this method throws IllegalArgumentException.

Parameters:

array - the index-based functional array.

Returns:

the dimensions of the matrix, coordinates of which are used as arguments of the underlying function.

Throws:

java.lang.NullPointerException - if the argument is null.

java.lang.IllegalArgumentException - if the passed array is not index-based functional, i.e. if isIndexFuncArray(Array) returns false for it.

See Also:

isIndexFuncArray(Array)

asConcatenation

public static Array asConcatenation(Array... arrays)

Returns an immutable view of the passed sequence of AlgART arrays as their concatenation. More precisely, the returned array has the length, equal to the sum of lengths l₀, l₁, ..., l_n−1 of all passed arrays, and the element #k of the returned array is the element #k-(l₀+l₁+...+l_i) in arrays[i], where i is the last index, for which k>=l₀+l₁+...+l_i. Query operations on the returned array "read through" to corresponding source arrays.

All passed arrays must be unresizable and have the same element type; in other case, an exception is thrown.

The array, returned by this method, is immutable. Its class implements the same basic interface BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray or ObjectArray as all passed arrays. The element type of the returned array is the same as the element type of the passed ones.

In the returned array:

• capacity and length will be equal to the sum of lengths of the passed arrays;
• subArray and subArr will create new concatenation for the corresponding subsequence of the arrays, passed to this method, or, maybe, will return an immutable view of a subarray of one the passed arrays, when it is possible (i.e. when all elements of the subarray belong to a single array from the sequence);
• Array.isNew() method returns false;
• Array.isNewReadOnlyView() method returns false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will call the same methods for the concatenated arrays;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

arrays - the sequence of AlgART arrays.

Returns:

the concatenation of these arrays.

Throws:

java.lang.NullPointerException - if arrays argument is null.

java.lang.IllegalArgumentException - if arrays.length==0 (no arrays passed), of if some of the passed arrays are not unresizable, or if they have different element types.

TooLargeArrayException - if the sum of lengths of the passed arrays is greater than Long.MAX_VALUE=2⁶³−1.

isConcatenation

public static boolean isConcatenation(Array array)

Returns true if the passed array is a concatenation view, i.e. is a result of asConcatenation(Array...) method. In this case, you may get the underlying array, passed to those methods in the last argument, by getUnderlyingArrays(array) call.

Please note: if the array is a subarray of some concatenation view, this method usually returns true, but may return false if the subarray does not intersect bounds between concatenated arrays.

Parameters:

array - the checked AlgART array (may be null, than the method returns false).

Returns:

true if the passed array a concatenation view of other arrays.

asShifted

public static Array asShifted(Array array,
                              long shift)

Returns an immutable view of the passed AlgART array, cyclically shifted to the right by the specified number of elements. More precisely, the returned array has the same length, and the element #k of the returned array is the element #((k-shift) mod length) of the passed array, where a mod b (b>=0) is a "positive remainder": a%b if a>=0 or b+a%b if a<0. (If the array length=0, the shift argument is ignored and the returned array contains no elements.)

The passed array must be unresizable; in other case, an exception is thrown.

The array, returned by this method, is immutable. Its class implements the same basic interface BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray or ObjectArray as the passed array. The element type of the returned array is the same as the element type of the passed one.

In the returned array:

• capacity and length will be equal to the length of the passed array;
• subArray and subArr may return return an immutable view of a subarray of the passed array, when it is possible (i.e. when the subarray corresponds to a single subarray of the original array);
• Array.isNew() method returns false;
• Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods will call the same methods for the passed array;
• UpdatableArray, MutableArray, DirectAccessible interfaces are not implemented.

Parameters:

array - the source AlgART array.

shift - the shift (to the right) of the index in the returned view.

Returns:

a shifted view of the passed array.

Throws:

java.lang.NullPointerException - if array argument is null.

java.lang.IllegalArgumentException - if the passed array is not unresizable.

isShifted

public static boolean isShifted(Array array)

Returns true if the passed array is not null shifted array, i.e. is a result of asShifted(Array, long) method. In this case, you may get the underlying array, passed to those methods in the last argument, by getUnderlyingArrays(array)[0] call, and get the used shift by getShift(Array) call.

Please note: if the array is a Array.subArray(long, long) subarray} of some shifted array, this method returns false.

Please note: if the array is a subarray of some shifted array, this method may return both true and false, depending on bounds of the subarray.

Parameters:

array - the checked AlgART array (may be null, than the method returns false).

Returns:

true if the passed array a shifted array.

getShift

public static long getShift(Array array)

Returns the shift, used for creating the passed shited array, or throws an exception if this array is not shifted. The returned shift is equal to the corresponding argument that was passed to asShifted(Array, long) method, which was called to create the passed array.

Parameters:

array - the functional AlgART array.

Returns:

the mathematical function, used for creating it.

Throws:

java.lang.NullPointerException - if the argument is null.

java.lang.IllegalArgumentException - if the passed array is not shifted, i.e. if isShifted(Array) returns false for it.

See Also:

isShifted(Array)

copy

public static Arrays.CopyStatus copy(ArrayContext context,
                                     UpdatableArray dest,
                                     Array src)

Copies min(dest.length(), src.length()) elements of src array, starting from index 0, to dest array, starting from index 0.

This method works alike UpdatableArray.copy(Array) with two important differences.

1. This method performs copying in several threads. It may be very important on multiprocessor or multi-core computers for the case, when the source array is a "lazy" view of another arrays, that is when reading data from it means performing complex algorithm calculating the data. The good example is an array returned by asFuncArray(Func, Class, PArray...), when the result of this method is calculated on the base of tens or hundreds source arrays passed in the last argument. In this situation, performing this method really means actual execution of the algorithm, and several threads allow to use all system processors for this purpose.
   Multithread copying is performed by a thread pool: java.util.concurrent.ExecutorService. The full copying procedure is split into several tasks, where each task copies some set of regions of src array to the corresponding regions of dest array. All tasks are submitted to the thread pool, and then this method waits until all tasks will be completed. The thread pool, performing the multithread copying, and the number of copying tasks are gotten by the methods of context.getThreadPoolFactory() object; if context argument is null, the DefaultThreadPoolFactory instance is created and used.
   Note: if this method may suppose that the passed array is not "lazy", namely, if !src.isLazy(), it uses only 1 task and ignores result of ThreadPoolFactory.recommendedNumberOfTasks(Array) method. In this situation, it's very probable that copying is simple transferring data between memory and/or disk; such operations are not optimized usually by multithreading technique.
   Note: if the number of parallel tasks is 1, this method performs copying in the current thread and does not use the thread pool at all.
    
2. If the context argument is not null, this method periodically calls its updateProgress and checkInterruption methods. More precisely, this method periodically calls ArrayContext.checkInterruption() method, catching any possible RuntimeException thrown by it, and, immediately after this, calls ArrayContext.updateProgress(net.algart.arrays.ArrayContext.Event) with correctly filled ArrayContext.Event instance. If ArrayContext.checkInterruption() has thrown some RuntimeException, all running threads are interrupted as soon as possible, and, when they will be finished, the same exception is thrown by this method. This technique allows to show the progress of execution to the end user and to interrupt the copying by some UI command if this method works for too long time.

Usually this method performs copying by a sequence of calls dest.subArr(p, len).copy(array.subArr(p, len)), where p is the position inside arrays and len is the length of the copied portion, usually several tens of thousands elements. But in some special cases this method uses more complex algorithms of copying.

In addition to calling ArrayContext.checkInterruption(), this method also interrupts all running threads, if the current thread, that calls this method, is interrupted by the standard Thread.interrupt() call. In this (and only this) case, this method throws java.io.IOError. Usually, you should avoid interrupting the threads, processing AlgART arrays, via Thread.interrupt() technique: see the package description about runtime exceptions issue.

Alike UpdatableArray.copy(Array) method, some elements may be copied incorrectly if this array and src are views of the same data, and the swapped data areas overlap. Unlike UpdatableArray.copy(Array), this problem occurs even for arrays, created by SimpleMemoryModel. But if the copied areas of the underlying data are the same (for example, if src if some view of this array generated by asFuncArray, but not asShifted method), this method works correctly: any elements will be read before they will be updated.

This method works only if the element types of this and src arrays (returned by Array.elementType()) are the same, or (for non-primitive elements) if this element type is a superclass of the source element type.

For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), this method may copy only references to elements, but also may copy the content of elements: it depends on implementation.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination array.

src - the source array.

Returns:

the information about copying.

Throws:

java.lang.NullPointerException - if src or dest argument is null.

java.lang.IllegalArgumentException - if the source and destination element types do not match.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

See Also:

copy(ArrayContext, UpdatableArray, Array, int), copy(ArrayContext, UpdatableArray, Array, int, boolean), Arrays.ParallelExecutor, Arrays.Copier

copy

public static Arrays.CopyStatus copy(ArrayContext context,
                                     UpdatableArray dest,
                                     Array src,
                                     int numberOfTasks)

This method is an analog of copy(ArrayContext, UpdatableArray, Array), allowing to specify the number of parallel tasks. More precisely, if numberOfTasks argument is positive, then the number of tasks submitted to the thread pool will be equal to this argument, regardless of the result of ThreadPoolFactory.recommendedNumberOfTasks(Array) method and of the "lazy" or "new" status of the source array. If numberOfTasks==0, this method is strictly equivalent to copy(ArrayContext, UpdatableArray, Array).

This method can be convenient, for example, if you are sure that multithreading is not useful in a concrete algorithm and the number of tasks should be 1.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination array.

src - the source array.

numberOfTasks - the desired number of parallel tasks; may be 0, then it will be chosen automatically.

Returns:

the information about copying.

Throws:

java.lang.NullPointerException - if src or dest argument is null.

java.lang.IllegalArgumentException - if the source and destination element types do not match, or if the numberOfThreads argument is negative.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

See Also:

copy(ArrayContext, UpdatableArray, Array), copy(ArrayContext, UpdatableArray, Array, int, boolean), Arrays.ParallelExecutor, Arrays.Copier

copy

public static Arrays.CopyStatus copy(ArrayContext context,
                                     UpdatableArray dest,
                                     Array src,
                                     int numberOfTasks,
                                     boolean strictMode)

This method is an analog of copy(ArrayContext, UpdatableArray, Array) and copy(ArrayContext, UpdatableArray, Array, int) providing a special "non-strict" copying mode.

Namely, if strictMode argument is false, then in some cases this method may copy elements with little errors (distortions). The probability and numeric value of errors is very low. The only reason of possible errors is limited precision of floating-point calculations.

The purpose of the non-strict mode is optimization: copying of some "lazy" arrays is performed much faster in this mode. For example, the result of Matrices.asResized (its built-in array) is copied faster in 10 and more times, when the source (non-resized) matrix is not created by SimpleMemoryModel.

If strictMode=true, this method is equivalent to copy(ArrayContext context, UpdatableArray dest, Array src, int numberOfTasks).

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination array.

src - the source array.

numberOfTasks - the desired number of parallel tasks; may be 0, then it will be chosen automatically.

strictMode - if false, optimization is allowed even if it can lead to little differences between the source and copied elements.

Returns:

the information about copying.

Throws:

java.lang.NullPointerException - if src or dest argument is null.

java.lang.IllegalArgumentException - if the source and destination element types do not match, or if the numberOfThreads argument is negative.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

See Also:

copy(ArrayContext, UpdatableArray, Array)

compareAndCopy

public static Arrays.ComparingCopyStatus compareAndCopy(ArrayContext context,
                                                        UpdatableArray dest,
                                                        Array src)

This method is an analog of copy(ArrayContext, UpdatableArray, Array) allowing to know, whether the destination array was really modified while copying. Namely, this method performs the same things as copy(ArrayContext context, UpdatableArray dest, Array src) and returns the status, where Arrays.ComparingCopyStatus.changed() method returns true if and only if at least one element of the dest array was changed as a result of copying from src array, in terms of the Array.equals(Object) method.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination array.

src - the source array.

Returns:

the information about copying.

Throws:

java.lang.NullPointerException - if src or dest argument is null.

java.lang.IllegalArgumentException - if the source and destination element types do not match.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

rangeOf

public static Range rangeOf(PArray array,
                            Arrays.MinMaxInfo minMaxInfo)

Equivalent to rangeOf(null, array, minMaxInfo).

Parameters:

array - some primitive array.

minMaxInfo - the object where to store the indexes and values of found minimum and maximum; may be null if you need only the values of the minimum and maximum.

Returns:

the values of the found minimal and maximal elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

rangeOf

public static Range rangeOf(ArrayContext context,
                            PArray array,
                            Arrays.MinMaxInfo minMaxInfo)

Returns a Range.valueOf(min, max), where min is equal to the minimal array element and min is equal to the maximal array element. The elements are extracted by array.getDouble(k) method (or by an equivalent technique).

Please remember that ByteArray and ShortArray are interpreted as unsigned.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

If the minMaxInfo argument is not null, the indexes of the found minimum / maximum, as well as the returned range, are stored in this object, and this object becomes initialized. In future, this information may be retrieved by the corresponding methods of Arrays.MinMaxInfo class. If there are several elements equal to the minimum, the index of minimum, stored in this object, may contain an index of any such element. If there are several elements equal to the maximum, the index of maximum, stored in this object, may contain an index of any such element.

If the passed array is empty (its length is 0), the method returns 0..0 range (Range.valueOf(0.0, 0.0)). In this case, if the minMaxInfo argument is not null, the indexes of the minimum / maximum, stored in this object, will be equal to -1.

Please note that the Arrays.MinMaxInfo class is internally synchronized and, so, thread-safe. It can be useful if you call this method in a separate thread and need to use the calculated information after finishing this method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

minMaxInfo - the object where to store the indexes and values of found minimum and maximum; may be null if you need only the values of the minimum and maximum.

Returns:

the values of the found minimal and maximal elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

rangeOf

public static Range rangeOf(PArray array)

Equivalent to rangeOf(null, array, null).

Parameters:

array - some primitive array.

Returns:

the values of the found minimal and maximal elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

rangeOf

public static Range rangeOf(ArrayContext context,
                            PArray array)

Equivalent to rangeOf(context, array, null).

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

Returns:

the values of the found minimal and maximal elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

sumOf

public static double sumOf(PArray array)

Equivalent to sumOf(null, array).

Parameters:

array - some primitive array.

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

sumOf

public static double sumOf(ArrayContext context,
                           PArray array)

Returns the sum of all array elements: the results of array.getDouble(k) for all k==0,1,...,array.length()-1.

This method works in strictfp mode: the result will be absolutely same on all platforms.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. However, unlike that method, this method is always performed in a single thread and does not use multithreading for optimization. It is necessary to provide absolutely identical results while different calls (because the floating-point sum can depend on the order of summing).

Please remember that ByteArray and ShortArray are interpreted as unsigned.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

preciseSumOf

public static long preciseSumOf(PFixedArray array,
                                boolean checkOverflow)
                         throws java.lang.ArithmeticException

Equivalent to preciseSumOf(null, array, checkOverflow).

Parameters:

array - some primitive array, excluding floating point arrays.

checkOverflow - whether overflow should lead to ArithmeticException

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.lang.ArithmeticException - if checkOverflow is true and the result or some partial sum cannot be represented by long value.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

preciseSumOf

public static long preciseSumOf(ArrayContext context,
                                PFixedArray array,
                                boolean checkOverflow)
                         throws java.lang.ArithmeticException

Returns the integer sum of all array elements: the results of array.getLong(k) for all k==0,1,...,array.length()-1.

The result is the same as the sum calculated by the following loop:

 long sum = 0;
 for (long k = 0; k < array.length(); k++)
     sum += array.getLong(k);
 

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

In a case of overflow (when 64 bits are not enough to represent the result or some partial sum), the behavior depends on checkOverflow argument. If it is false, the result will be incorrect: it will contain 64 lowest bits of the precise sum. If checkOverflow is true, the ArithmeticException will be thrown; in this situation, if the exception is not thrown, you can be sure that this method returns the correct result.

Please remember that ByteArray and ShortArray are interpreted as unsigned.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array, excluding floating point arrays.

checkOverflow - whether overflow should lead to ArithmeticException

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.lang.ArithmeticException - if checkOverflow is true and the result or some partial sum cannot be represented by long value.

preciseSumOf

public static long preciseSumOf(PFixedArray array)

Equivalent to preciseSumOf(null, array, false).

Parameters:

array - some primitive array, excluding floating point arrays.

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

preciseSumOf

public static long preciseSumOf(ArrayContext context,
                                PFixedArray array)

Equivalent to preciseSumOf(context, array, false).

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array, excluding floating point arrays.

Returns:

the sum of all array elements.

Throws:

java.lang.NullPointerException - if array argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

cardinality

public static long cardinality(ArrayContext context,
                               BitArray bitArray)

Returns the number of bits set to true in this array. Equivalent to preciseSumOf(context, bitArray).

Parameters:

context - the context of calculations; may be null, then it will be ignored.

bitArray - the bit array.

Returns:

the number of bits set to true in this array.

Throws:

java.lang.NullPointerException - if bitArray argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

cardinality

public static long cardinality(BitArray bitArray)

Returns the number of bits set to true in this array. Equivalent to preciseSumOf(bitArray).

Parameters:

bitArray - the bit array.

Returns:

the number of bits set to true in this array.

Throws:

java.lang.NullPointerException - if bitArray argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

histogramOf

public static boolean histogramOf(PArray array,
                                  long[] histogram,
                                  double from,
                                  double to)

Equivalent to histogramOf(null, array, histogram, from, to).

Parameters:

array - some primitive array.

histogram - the histogram to be incremented: histogram.length columns between from and to.

from - the low boundary for the counted values, inclusive.

to - the high boundary for the counted values, exclusive.

Returns:

whether all elements of the array are inside the range from..to.

Throws:

java.lang.NullPointerException - if array or histogram argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

histogramOf

public static boolean histogramOf(ArrayContext context,
                                  PArray array,
                                  long[] histogram,
                                  double from,
                                  double to)

Increments the histogram of frequency of values in the passed array. The histogram corresponds to values in the range from <= v < to.

More precisely, if from < to, then for every element #k of the passed AlgART array this method:

1. gets its real value v = array.getDouble(k);
2. calculates the index of the column in the histogram: m = (int)StrictMath.floor((v - from) * multiplier), where multiplier = histogram.length / (to - from);
3. if this index lies in the range 0 <= m < histogram.length, increments the corresponding element of the passed histogram Java array: histogram[m]++

The result of this method will be true if the index m at the step 3 always fulfilled the condition 0 <= m < histogram.length, or false if this index was out of range at least for one element. If from >= to, this method does nothing and returns false. If the passed array is empty (array.length()==0), this method returns true if from < to and false if from >= to.

Please draw attention to the formula at the step 2. It differs from the more obvious formula (int)((v-from)/(to-from)*histogram.length) and theoretically can lead to little other results.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

This method works in strictfp mode: the results will be absolutely same on all platforms.

Please remember that ByteArray and ShortArray are interpreted as unsigned.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

histogram - the histogram to be incremented: histogram.length columns between from and to.

from - the low boundary for the counted values, inclusive.

to - the high boundary for the counted values, exclusive.

Returns:

whether all elements of the array are inside the range from..to.

Throws:

java.lang.NullPointerException - if array or histogram argument is null.

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call (this technique may be not supported in some cases).

packBitsGreater

public static void packBitsGreater(UpdatableBitArray bits,
                                   PArray array,
                                   double threshold)

Equivalent to packBitsGreater(null, bits, array, threshold).

Parameters:

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

packBitsGreater

public static void packBitsGreater(ArrayContext context,
                                   UpdatableBitArray bits,
                                   PArray array,
                                   double threshold)

Sets every bit #k of the passed updatable bit array to the boolean value array.getDouble(k) >= threshold. Works much faster than the simple loop of such checks.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

packBitsLess(ArrayContext, UpdatableBitArray, PArray, double)

packBitsLess

public static void packBitsLess(UpdatableBitArray bits,
                                PArray array,
                                double threshold)

Equivalent to packBitsLess(null, bits, array, threshold).

Parameters:

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

packBitsLess

public static void packBitsLess(ArrayContext context,
                                UpdatableBitArray bits,
                                PArray array,
                                double threshold)

Sets every bit #k of the passed updatable bit array to the boolean value array.getDouble(k) <= threshold. Works much faster than the simple loop of such checks.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

packBitsGreater(ArrayContext, UpdatableBitArray, PArray, double)

packBitsGreaterOrEqual

public static void packBitsGreaterOrEqual(UpdatableBitArray bits,
                                          PArray array,
                                          double threshold)

Equivalent to packBitsGreaterOrEqual(null, bits, array, threshold).

Parameters:

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

packBitsGreaterOrEqual

public static void packBitsGreaterOrEqual(ArrayContext context,
                                          UpdatableBitArray bits,
                                          PArray array,
                                          double threshold)

Sets every bit #k of the passed updatable bit array to the boolean value array.getDouble(k) >= threshold. Works much faster than the simple loop of such checks.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

packBitsLessOrEqual(ArrayContext, UpdatableBitArray, PArray, double)

packBitsLessOrEqual

public static void packBitsLessOrEqual(UpdatableBitArray bits,
                                       PArray array,
                                       double threshold)

Equivalent to packBitsLessOrEqual(null, bits, array, threshold).

Parameters:

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

packBitsLessOrEqual

public static void packBitsLessOrEqual(ArrayContext context,
                                       UpdatableBitArray bits,
                                       PArray array,
                                       double threshold)

Sets every bit #k of the passed updatable bit array to the boolean value array.getDouble(k) <= threshold. Works much faster than the simple loop of such checks.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

bits - the bit array that will contain results of comparison of the passed array with the threshold.

array - some primitive array that should be compared with the threshold.

threshold - the threshold that will be compared with all elements of array.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

packBitsGreaterOrEqual(ArrayContext, UpdatableBitArray, PArray, double)

unpackBits

public static void unpackBits(UpdatablePArray array,
                              BitArray bits,
                              double filler0,
                              double filler1)

Equivalent to unpackBits(null, array, bits, filler0, filler1).

Parameters:

array - some primitive array.

bits - the bit array that should be "unpacked" to array.

filler0 - the value that will be set in array for zero bits.

filler1 - the value that will be set in array for unit bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

unpackBits

public static void unpackBits(ArrayContext context,
                              UpdatablePArray array,
                              BitArray bits,
                              double filler0,
                              double filler1)

Sets every element #k of the passed updatable array to filler0 value, if the corresponding element #k of bits array is false (0), or to filler1, if this bit is true (1). Equivalent to the loop of the operators

 array.setDouble(k, bits.getBit(k) ? filler1 : filler0)
 

for all indexes k, but works much faster than the simple loop.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

This method is also equivalent to the following code:

 Class et = array.elementType();
 if (et == byte.class || et == short.class || et == int.class || et == char.class) {
     filler0 = (int)filler0;
     filler1 = (int)filler1;
 }
 Arrays.applyFunc(context, false,
     SelectConstantFunc.getInstance(filler0, filler1), array, bits);
 

(Additional casting to int is necessary here due to different type cast rules in UpdatablePArray.setDouble(long, double) and asFuncArray methods.)

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

bits - the bit array that should be "unpacked" to array.

filler0 - the value that will be set in array for zero bits.

filler1 - the value that will be set in array for unit bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

unpackUnitBits(ArrayContext, UpdatablePArray, BitArray, double), unpackZeroBits(ArrayContext, UpdatablePArray, BitArray, double)

unpackUnitBits

public static void unpackUnitBits(UpdatablePArray array,
                                  BitArray bits,
                                  double filler1)

Equivalent to unpackUnitBits(null, array, bits, filler1).

Parameters:

array - some primitive array.

bits - the bit array, the unit elements of which should be "unpacked" to array.

filler1 - the value that will be set in array for unit bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

unpackUnitBits

public static void unpackUnitBits(ArrayContext context,
                                  UpdatablePArray array,
                                  BitArray bits,
                                  double filler1)

Sets every element #k of the passed updatable array to filler1 value, if the corresponding element #k of bits array is true (1), or doesn't change it, if this bit is false (0). Equivalent to the loop of the operators

 if (bits.getBit(k))
     array.setDouble(k, filler1)
 

for all indexes k, but works much faster than the simple loop.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

bits - the bit array, the unit elements of which should be "unpacked" to array.

filler1 - the value that will be set in array for unit bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

unpackBits(ArrayContext, UpdatablePArray, BitArray, double, double), unpackZeroBits(ArrayContext, UpdatablePArray, BitArray, double)

unpackZeroBits

public static void unpackZeroBits(UpdatablePArray array,
                                  BitArray bits,
                                  double filler0)

Equivalent to unpackZeroBits(null, array, bits, filler0).

Parameters:

array - some primitive array.

bits - the bit array, the zero elements of which should be "unpacked" to array.

filler0 - the value that will be set in array for zero bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

unpackZeroBits

public static void unpackZeroBits(ArrayContext context,
                                  UpdatablePArray array,
                                  BitArray bits,
                                  double filler0)

Sets every element #k of the passed updatable array to filler0 value, if the corresponding element #k of bits array is false (0), or doesn't change it, if this bit is true (1). Equivalent to the loop of the operators

 if (!bits.getBit(k))
     array.setDouble(k, filler0)
 

for all indexes k, but works much faster than the simple loop.

The context argument is used in the same manner as in copy(ArrayContext, UpdatableArray, Array) method. Namely, the context allows to specify the desired number of parallel tasks, provide the pool factory, interrupt this method and show its progress. If the context argument is null, then this method still may use several threads, if DefaultThreadPoolFactory instance recommends it, and may be interruptable by Thread.interrupt(), alike copy(ArrayContext, UpdatableArray, Array) method.

Parameters:

context - the context of calculations; may be null, then it will be ignored.

array - some primitive array.

bits - the bit array, the zero elements of which should be "unpacked" to array.

filler0 - the value that will be set in array for zero bits.

Throws:

java.lang.NullPointerException - if array or bits argument is null.

SizeMismatchException - if array.length()!=bits.length().

java.io.IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

See Also:

unpackBits(ArrayContext, UpdatablePArray, BitArray, double, double), unpackUnitBits(ArrayContext, UpdatablePArray, BitArray, double)

zeroFill

public static void zeroFill(UpdatableArray array)

Fills all elements of the array by zero (0 for numbers, false for boolean values, null or some "empty" objects for non-primitive elements).

Parameters:

array - the filled array.

Throws:

java.lang.NullPointerException - if array argument is null.

See Also:

UpdatablePArray.fill(double), UpdatablePArray.fill(long)

toJavaArray

public static java.lang.Object toJavaArray(Array array)

Returns a Java array containing all of the elements in this AlgART array in proper sequence, if the length of this array is not too high (not greater than Integer.MAX_VALUE). In other case, throws TooLargeArrayException. The length of returned Java array will be equal to current array.length(), and array elements will be stored in elements #0..#length()-1} of the returned array.

The returned Java array will be "safe" in that no references to it are maintained by this array. (In other words, this method must always allocate a new Java array). The caller is thus free to modify the returned array.

The type of returned array is always one of the following:

• boolean[] for BitArray,
• char[] for CharArray,
• byte[] for ByteArray,
• short[] for ShortArray,
• int[] for IntArray,
• long[] for LongArray,
• float[] for FloatArray,
• double[] for DoubleArray,
• type[], where type is the result of Array.elementType() method, in all other cases.

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

Array.getData(long, Object)

toJavaArray

public static boolean[] toJavaArray(BitArray array)

Equivalent to (boolean[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static char[] toJavaArray(CharArray array)

Equivalent to (char[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static byte[] toJavaArray(ByteArray array)

Equivalent to (byte[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static short[] toJavaArray(ShortArray array)

Equivalent to (short[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static int[] toJavaArray(IntArray array)

Equivalent to (int[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static long[] toJavaArray(LongArray array)

Equivalent to (long[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static float[] toJavaArray(FloatArray array)

Equivalent to (float[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)

toJavaArray

public static double[] toJavaArray(DoubleArray array)

Equivalent to (double[])toJavaArray((Array)array).

Parameters:

array - the source AlgART array.

Returns:

Java array containing all of the elements in this array.

Throws:

java.lang.NullPointerException - if array argument is null.

TooLargeArrayException - if the array length is greater than Integer.MAX_VALUE.

See Also:

toJavaArray(Array), Array.getData(long, Object)