Package net.algart.arrays

Interface LongArray

All Superinterfaces:

Array, PArray, PFixedArray, PIntegerArray, PNumberArray

All Known Subinterfaces:

MutableLongArray, UpdatableLongArray

All Known Implementing Classes:

AbstractLongArray, AbstractUpdatableLongArray

public interface LongArray
extends PIntegerArray

AlgART array of long values, read-only access.

Author:

Daniel Alievsky

Method Summary

Modifier and Type	Method	Description
static UpdatableLongArray	as(long[] array)	Equivalent to SimpleMemoryModel.asUpdatableLongArray(array).
LongArray	asImmutable()	Returns an immutable view of this array.
LongArray	asTrustedImmutable()	Returns a trusted immutable view of this array.
DataLongBuffer	buffer()	Equivalent to buffer(suitableMode, someCapacity), where both suitableMode and someCapacity arguments are chosen automatically.
DataLongBuffer	buffer(long capacity)	Equivalent to buffer(suitableMode, capacity), where capacity is the argument of this method and suitableMode is chosen automatically.
DataLongBuffer	buffer(DataBuffer.AccessMode mode)	Equivalent to buffer(mode, someCapacity), where mode is the argument of this method and someCapacity is chosen automatically to provide good performance in typical situations.
DataLongBuffer	buffer(DataBuffer.AccessMode mode, long capacity)	Returns a data buffer allowing block access to this array with the specified access mode and buffer capacity.
int	getInt(long index)	Returns the element #index, truncated to the range Integer.MIN_VALUE..Integer.MAX_VALUE: min(max(value, Integer.MIN_VALUE), Integer.MAX_VALUE).
long	getLong(long index)	Returns the element #index.
long	indexOf(long lowIndex, long highIndex, long value)	Returns the minimal index k, so that lowIndex<=k<min(highIndex,thisArray.length()) and getLong(k)==value, or -1 if there is no such array element.
long[]	ja()	Returns the underlying Java array ja, if this AlgART array is its wrapper (see Arrays.isJavaArrayWrapper(Array)); otherwise returns Arrays.toJavaArray(thisObject) in other case.
default long[]	jaLong()	Equivalent to the following expression: thisObject instanceof LongArray a ? a.ja() : Arrays.toLongJavaArray(thisObject).
long	lastIndexOf(long lowIndex, long highIndex, long value)	Returns the maximal index k, so that highIndex>k>=max(lowIndex,0) and getLong(k)==value, or -1 if there is no such array element.
default Matrix<? extends LongArray>	matrix(long... dim)	Equivalent to matrix(thisArray, dim).
MutableLongArray	mutableClone(MemoryModel memoryModel)	Returns a mutable resizable copy of this array.
Class<? extends MutableLongArray>	mutableType()	Returns the canonical resizable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of resizable AlgART arrays for 8 primitive and any non-primitive element types.
Class<? extends LongArray>	type()	Returns the canonical AlgART type of this array: the class of one of 9 basic interfaces, describing all kinds of AlgART arrays for 8 primitive and any non-primitive element types.
UpdatableLongArray	updatableClone(MemoryModel memoryModel)	Returns an unresizable updatable copy of this array.
Class<? extends UpdatableLongArray>	updatableType()	Returns the canonical updatable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of updatable AlgART arrays for 8 primitive and any non-primitive element types.

Methods inherited from interface net.algart.arrays.Array

asCopyOnNextWrite, byteOrder, capacity, checkUnallowedMutation, elementType, equals, flushResources, flushResources, freeResources, freeResources, getData, getData, getElement, hashCode, isCopyOnNextWrite, isEmpty, isImmutable, isLazy, isNew, isNewReadOnlyView, isUnresizable, length, length32, loadResources, newJavaArray, shallowClone, subArr, subArray, toString

Methods inherited from interface net.algart.arrays.PArray

bitsPerElement, getDouble, indexOf, isZeroFilled, jaByte, jaDouble, jaFloat, jaInt, jaShort, lastIndexOf, maxPossibleValue, minPossibleValue

Methods inherited from interface net.algart.arrays.PFixedArray

maxPossibleValue, minPossibleValue

Method Details

type

Class<? extends LongArray> type()

Description copied from interface: Array

Returns the canonical AlgART type of this array: the class of one of 9 basic interfaces, describing all kinds of AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

• BitArray.class, if this object is an instance of BitArray,
• CharArray.class, if this object is an instance of CharArray,
• ByteArray.class, if this object is an instance of ByteArray,
• ShortArray.class, if this object is an instance of ShortArray,
• IntArray.class, if this object is an instance of IntArray,
• LongArray.class, if this object is an instance of LongArray,
• FloatArray.class, if this object is an instance of FloatArray,
• DoubleArray.class, if this object is an instance of DoubleArray,
• ObjectArray.class, if this object is an instance of ObjectArray.

There is a guarantee that this method works very quickly (usually it just returns a constant value).

Specified by:

type in interface Array

Specified by:

type in interface PArray

Specified by:

type in interface PIntegerArray

Specified by:

type in interface PNumberArray

Returns:

canonical AlgART type of this array.

updatableType

Class<? extends UpdatableLongArray> updatableType()

Description copied from interface: Array

Returns the canonical updatable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of updatable AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

• UpdatableBitArray.class, if this object is an instance of BitArray,
• UpdatableCharArray.class, if this object is an instance of CharArray,
• UpdatableByteArray.class, if this object is an instance of ByteArray,
• UpdatableShortArray.class, if this object is an instance of ShortArray,
• UpdatableIntArray.class, if this object is an instance of IntArray,
• UpdatableLongArray.class, if this object is an instance of LongArray,
• UpdatableFloatArray.class, if this object is an instance of FloatArray,
• UpdatableDoubleArray.class, if this object is an instance of DoubleArray,
• UpdatableObjectArray.class, if this object is an instance of ObjectArray.

There is a guarantee that this method works very quickly (usually it just returns a constant value).

Specified by:

updatableType in interface Array

Specified by:

updatableType in interface PArray

Specified by:

updatableType in interface PIntegerArray

Specified by:

updatableType in interface PNumberArray

Returns:

canonical AlgART type of an updatable array of the same kind.

mutableType

Class<? extends MutableLongArray> mutableType()

Description copied from interface: Array

Returns the canonical resizable AlgART type of arrays with the same element types: the class of one of 9 basic interfaces, describing all kinds of resizable AlgART arrays for 8 primitive and any non-primitive element types. More precisely, returns:

• MutableBitArray.class, if this object is an instance of BitArray,
• MutableCharArray.class, if this object is an instance of CharArray,
• MutableByteArray.class, if this object is an instance of ByteArray,
• MutableShortArray.class, if this object is an instance of ShortArray,
• MutableIntArray.class, if this object is an instance of IntArray,
• MutableLongArray.class, if this object is an instance of LongArray,
• MutableFloatArray.class, if this object is an instance of FloatArray,
• MutableDoubleArray.class, if this object is an instance of DoubleArray,
• MutableObjectArray.class, if this object is an instance of ObjectArray.

There is a guarantee that this method works very quickly (usually it just returns a constant value).

Specified by:

mutableType in interface Array

Specified by:

mutableType in interface PArray

Specified by:

mutableType in interface PIntegerArray

Specified by:

mutableType in interface PNumberArray

Returns:

canonical AlgART type of a resizable array of the same kind.

getLong

long getLong(long index)

Returns the element #index.

Specified by:

getLong in interface PFixedArray

Parameters:

index - index of element to get.

Returns:

the element at the specified position in this array.

Throws:

IndexOutOfBoundsException - if index is out of range 0..length()-1.

See Also:

• UpdatablePArray.setLong(long, long)

indexOf

long indexOf(long lowIndex,
 long highIndex,
 long value)

Returns the minimal index k, so that lowIndex<=k<min(highIndex,thisArray.length()) and getLong(k)==value, or -1 if there is no such array element.

In particular, if lowIndex>=thisArray.length()} or lowIndex>=highIndex, this method returns -1, and if lowIndex<0, the result is the same as if lowIndex==0.

You may specify lowIndex=0 and highIndex=Long.MAX_VALUE to search through all array elements.

Specified by:

indexOf in interface PFixedArray

Parameters:

lowIndex - the low index in the array for search (inclusive).

highIndex - the high index in the array for search (exclusive).

value - the value to be found.

Returns:

the index of the first occurrence of this value in this array in range lowIndex<=index<highIndex, or -1 if this value does not occur in this range.

lastIndexOf

long lastIndexOf(long lowIndex,
 long highIndex,
 long value)

Returns the maximal index k, so that highIndex>k>=max(lowIndex,0) and getLong(k)==value, or -1 if there is no such array element.

In particular, if highIndex<=0 or highIndex<=lowIndex, this method returns -1, and if highIndex>=thisArray.length(), the result is the same as if highIndex==thisArray.length().

You may specify lowIndex=0 and highIndex=Long.MAX_VALUE to search through all array elements.

Specified by:

lastIndexOf in interface PFixedArray

Parameters:

lowIndex - the low index in the array for search (inclusive).

highIndex - the high index in the array for search (exclusive).

value - the value to be found.

Returns:

the index of the last occurrence of this value in this array in range lowIndex<=index<highIndex, or -1 if this value does not occur in this range.

buffer

DataLongBuffer buffer(DataBuffer.AccessMode mode,
 long capacity)

Description copied from interface: Array

Returns a data buffer allowing block access to this array with the specified access mode and buffer capacity.

If this array does not implement UpdatableArray interface (so, it is probably immutable or trusted immutable), the mode argument must be DataBuffer.AccessMode.READ.

The capacity argument must be in range 0..2³⁷-1 for bit arrays or 0..2³¹-1 for all other element types.

If the capacity argument is greater than this array Array.length(), it is truncated to this length.

Specified by:

buffer in interface Array

Parameters:

mode - the access mode for new buffer.

capacity - the capacity of the buffer.

Returns:

new data buffer for accessing this array.

See Also:

• Array.buffer(net.algart.arrays.DataBuffer.AccessMode)
• Array.buffer(long)
• Array.buffer()

buffer

DataLongBuffer buffer(DataBuffer.AccessMode mode)

Description copied from interface: Array

Equivalent to buffer(mode, someCapacity), where mode is the argument of this method and someCapacity is chosen automatically to provide good performance in typical situations. Usually, the capacity is chosen to get a buffer occupying several kilobytes, that can fit in an internal cache of most processors.

In any case, you can be sure that the chosen capacity will not be greater than Integer.MAX_VALUE-64.

Specified by:

buffer in interface Array

Parameters:

mode - the access mode for new buffer.

Returns:

new data buffer for accessing this array.

buffer

DataLongBuffer buffer(long capacity)

Description copied from interface: Array

Equivalent to buffer(suitableMode, capacity), where capacity is the argument of this method and suitableMode is chosen automatically. Namely, suitableMode is:

• DataBuffer.AccessMode.READ_WRITE if this array implements UpdatableArray interface (i.e., is modifiable and, maybe, resizable);
• DataBuffer.AccessMode.READ if this array does not implements this interface (i.e., probably, immutable or trusted immutable).

Specified by:

buffer in interface Array

Parameters:

capacity - the capacity of the buffer.

Returns:

new data buffer for accessing this array.

buffer

DataLongBuffer buffer()

Description copied from interface: Array

Equivalent to buffer(suitableMode, someCapacity), where both suitableMode and someCapacity arguments are chosen automatically. The algorithm of choosing these arguments is the same as for Array.buffer(net.algart.arrays.DataBuffer.AccessMode) and Array.buffer(long) methods.

In any case, you can be sure that the chosen capacity will not be greater than Integer.MAX_VALUE-64.

Specified by:

buffer in interface Array

Returns:

new data buffer for accessing this array.

asImmutable

LongArray asImmutable()

Description copied from interface: Array

Returns an immutable view of this array. If this array is already immutable (i.e. Array.isImmutable() is true), returns a reference to this object.

A array is considered to be immutable, if there are no ways to modify its content or state with help of this instance. In particular, immutable arrays never implement UpdatableArray or DirectAccessible interfaces. Moreover, any third-party implementation of Array interface must return an instance of a class, which has no methods or fields allowing to change this instance.

Query operations on the returned array "read through" to this array. The returned view is also unresizable (see UpdatableArray.asUnresizable()).

The returned view (when it is not a reference to this object) contains the same elements as this array, but independent length, start offset, capacity, copy-on-next-write and possible other information about array characteristics besides its elements, as for Array.shallowClone() method. If modifications of this array characteristics lead to reallocation of the internal storage, then the returned array ceases to be a view of this array. The only possible reasons for reallocation are the following: calling MutableArray.length(long), MutableArray.ensureCapacity(long) or MutableArray.trim() methods for this array, or any modification of this or returned array in a case when this array is copy-on-next-write.

By default, the array factories (memory models) create mutable arrays, but they can be converted to immutable by this method.

Note: Array.isNew() method, called for the result of this method, always returns false — because it does not implement UpdatableArray.

Also note: Array.isNewReadOnlyView() method, called for the result of this method, always returns the same value as Array.isNewReadOnlyView() for this object. Really,

• it this object is immutable (Array.isImmutable()==true), then it is obvious (this method just returns a reference to this array);
• it this object is not immutable (Array.isImmutable()==false), then, according to the contract to Array.isNewReadOnlyView() method, Array.isNewReadOnlyView() must return false for this array (in other case Array.isImmutable() would return true) and it also must return false for the returned array (because it is a view of another array and not an original view of external data — see the beginning of the comment to Array.isNewReadOnlyView()).

Specified by:

asImmutable in interface Array

Specified by:

asImmutable in interface PArray

Specified by:

asImmutable in interface PFixedArray

Specified by:

asImmutable in interface PIntegerArray

Returns:

an immutable view of this array (or a reference to this array if it is already immutable).

See Also:

• Array.isImmutable()
• Array.asTrustedImmutable()
• Array.mutableClone(MemoryModel)
• Array.updatableClone(MemoryModel)
• UpdatableArray.asUnresizable()

asTrustedImmutable

LongArray asTrustedImmutable()

Description copied from interface: Array

Returns a trusted immutable view of this array. If this array is already trusted immutable, returns a reference to this object.

A array is considered to be "trusted" immutable, if it potentially can change its elements, but the Java code working with this array promises that it will not change them. The returned instance never implements UpdatableArray, but may implement DirectAccessible, that allow quick access to its elements. As for usual immutable view, query operations on the returned array "read through" to this array.

The only standard way allowing to change elements of returned array is using DirectAccessible.javaArray() method, in a case when the array is backed by an accessible array. But the Java code, processing the trusted immutable array, must use this method only for quick reading elements and not try to change them. If, despite the promise, the elements of the trusted immutable array will be changed, the UnallowedMutationError may be thrown by the call of Array.checkUnallowedMutation() method.

In some implementations — for example, if DirectAccessible interface is not supported by this array — this method may return the same result as Array.asImmutable().

The returned view is always unresizable.

The returned view (when it is not a reference to this object) contains the same elements as this array, but independent length, start offset, capacity, copy-on-next-write and possible other information about array characteristics besides its elements, as for Array.shallowClone() method. If modifications of this array characteristics lead to reallocation of the internal storage, then the returned array ceases to be a view of this array. The only possible reasons for reallocation are the following: calling MutableArray.length(long), MutableArray.ensureCapacity(long) or MutableArray.trim() methods for this array, or any modification of this or returned array in a case when this array is copy-on-next-write.

Trusted immutable view is a compromise between absolute safety, provided by usual immutable view, and maximal efficiency, achieved while using the original non-protected array. Please see the package description to learn more about possible usage of this method.

Specified by:

asTrustedImmutable in interface Array

Specified by:

asTrustedImmutable in interface PArray

Specified by:

asTrustedImmutable in interface PFixedArray

Specified by:

asTrustedImmutable in interface PIntegerArray

Returns:

a trusted immutable view of this array (or a reference to this array if it is already trusted immutable).

See Also:

• Array.asImmutable()
• Array.checkUnallowedMutation()

mutableClone

MutableLongArray mutableClone(MemoryModel memoryModel)

Description copied from interface: Array

Returns a mutable resizable copy of this array. This method is equivalent to the following code:

 memoryModel.newArray(thisArray).copy(thisArray);
 

Please note: this method is a good choice for cloning little arrays (thousands, maybe millions elements). If you clone large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. To clone large arrays, we recommend the following code:

 MutableArray clone = memoryModel.newArray(thisArray);
 Arrays.copy(someContext, clone, a);
 

Specified by:

mutableClone in interface Array

Specified by:

mutableClone in interface PArray

Specified by:

mutableClone in interface PFixedArray

Specified by:

mutableClone in interface PIntegerArray

Parameters:

memoryModel - the memory model, used for allocation a new copy of this array.

Returns:

a mutable copy of this array.

See Also:

• Array.updatableClone(MemoryModel)

updatableClone

UpdatableLongArray updatableClone(MemoryModel memoryModel)

Description copied from interface: Array

Returns an unresizable updatable copy of this array. This method is equivalent to the following code:

 memoryModel.newUnresizableArray(thisArray).copy(thisArray);
 

Please note: this method is a good choice for cloning little arrays (thousands, maybe millions elements). If you clone large arrays by this method, the user, in particular, has no ways to view the progress of copying or to interrupt copying. To clone large arrays, we recommend the following code:

 UpdatableArray clone = memoryModel.newUnresizableArray(thisArray);
 Arrays.copy(someContext, clone, a);
 

Specified by:

updatableClone in interface Array

Specified by:

updatableClone in interface PArray

Specified by:

updatableClone in interface PFixedArray

Specified by:

updatableClone in interface PIntegerArray

Parameters:

memoryModel - the memory model, used for allocation a new copy of this array.

Returns:

an updatable copy of this array.

See Also:

• Array.mutableClone(MemoryModel)

ja

long[] ja()

Description copied from interface: Array

Returns the underlying Java array ja, if this AlgART array is its wrapper (see Arrays.isJavaArrayWrapper(Array)); otherwise returns Arrays.toJavaArray(thisObject) in other case.

In other words, this method returns a Java-array, absolutely identical to this AlgART array — having identical length and elements, — and does this as quickly as possible (unlike Arrays.toJavaArray(Array), which always copies the data).

This method is equivalent to the following operators:

     thisObject instanceof DirectAccessible da &&
                 da.hasJavaArray() &&
                 da.javaArrayOffset() == 0 &&
                 java.lang.reflect.Array.getLength(da.javaArray()) == thisObject.length() ?
                 da.javaArray() :
                 Arrays.toJavaArray(this);
 

but works little faster if the first case, "da.javaArray()", is selected (this is a wrapper).

There are overridden versions of this method in subinterfaces for specific element types: BitArray.ja(), CharArray.ja()}, ByteArray.ja()}, ShortArray.ja()}, IntArray.ja()}, ja()}, FloatArray.ja()}, DoubleArray.ja()}, ObjectArray.ja()}.

Be careful: this method is potentially unsafe! The main purpose of this method is to quickly access array data for reading. But it also allows you to modify this data, and the result of such modification is unpredictable: this may change the original AlgART array, but may also not change. Typically you should not attempt to modify the Java array returned by this method; this helps to avoid difficult bugs.

Note that usually you should prefer methods of DirectAccessible interface instead of this method, because that interface allows to quickly process sub-arrays with non-zero start offsets and mutable arrays, for which the length of underlying Java array (capacity) is usually greater than the actual AlgART array length. But if you are sure that your array is created by SimpleMemoryModel and is not a sub-array, this method provides the simplest way to receive an identical Java array maximally quickly.

Specified by:

ja in interface Array

Returns:

Java array, equivalent to this AlgART array.

See Also:

• DirectAccessible
• Arrays.isJavaArrayWrapper(Array)
• PArray.jaByte()
• PArray.jaShort()
• PArray.jaInt()
• PArray.jaLong()
• PArray.jaFloat()
• PArray.jaDouble()

matrix

default Matrix<? extends LongArray> matrix(long... dim)

Description copied from interface: Array

Equivalent to matrix(thisArray, dim).

Specified by:

matrix in interface Array

Specified by:

matrix in interface PArray

Specified by:

matrix in interface PFixedArray

Specified by:

matrix in interface PIntegerArray

Specified by:

matrix in interface PNumberArray

Parameters:

dim - the matrix dimensions.

Returns:

new matrix backed by array with the given dimensions.

getInt

int getInt(long index)

Returns the element #index, truncated to the range Integer.MIN_VALUE..Integer.MAX_VALUE: min(max(value, Integer.MIN_VALUE), Integer.MAX_VALUE).

Note that this method is already declared in PFixedArray. It is redeclared here only for documentation and code search purposes.

Specified by:

getInt in interface PFixedArray

Parameters:

index - index of element to get.

Returns:

the element at the specified position in this array.

Throws:

IndexOutOfBoundsException - if index out of range 0..length()-1.

See Also:

• UpdatablePArray.setInt(long, int)

jaLong

default long[] jaLong()

Description copied from interface: PArray

Equivalent to the following expression: thisObject instanceof LongArray a ? a.ja() : Arrays.toLongJavaArray(thisObject).

This method may be used instead of Arrays.toLongJavaArray(PArray), if you need maximally quick access to this data in a form of long[] array and there is high probability that this AlgART array is a wrapper for standard long[] array.

Be careful: this method is potentially unsafe! The main purpose of this method is to quickly access array data for reading. But it also allows you to modify this data, and the result of such modification is unpredictable: this may change the original AlgART array, but may also not change. Typically you should not attempt to modify the Java array returned by this method; this helps to avoid difficult bugs.

Specified by:

jaLong in interface PArray

Returns:

Java array containing all the elements in this array, cast to long type according to AlgART rules.

as

static UpdatableLongArray as(long[] array)

Equivalent to SimpleMemoryModel.asUpdatableLongArray(array).

Parameters:

array - the source Java array.

Returns:

an unresizable AlgART array backed by the specified Java array.

Throws:

NullPointerException - if array argument is null.