Package net.algart.arrays

Interface Array

All Known Subinterfaces:

BitArray, ByteArray, CharArray, DoubleArray, FloatArray, IntArray, LongArray, MutableArray, MutableBitArray, MutableByteArray, MutableCharArray, MutableDoubleArray, MutableFloatArray, MutableIntArray, MutableLongArray, MutableObjectArray<E>, MutableObjectInPlaceArray<E>, MutablePArray, MutablePFixedArray, MutablePFloatingArray, MutablePIntegerArray, MutablePNumberArray, MutableShortArray, ObjectArray<E>, ObjectInPlaceArray<E>, PArray, PFixedArray, PFloatingArray, PIntegerArray, PNumberArray, ShortArray, UpdatableArray, UpdatableBitArray, UpdatableByteArray, UpdatableCharArray, UpdatableDoubleArray, UpdatableFloatArray, UpdatableIntArray, UpdatableLongArray, UpdatableObjectArray<E>, UpdatableObjectInPlaceArray<E>, UpdatablePArray, UpdatablePFixedArray, UpdatablePFloatingArray, UpdatablePIntegerArray, UpdatablePNumberArray, UpdatableShortArray

All Known Implementing Classes:

AbstractArray, AbstractBitArray, AbstractByteArray, AbstractCharArray, AbstractDoubleArray, AbstractFloatArray, AbstractIntArray, AbstractLongArray, AbstractObjectArray, AbstractShortArray, AbstractUpdatableBitArray, AbstractUpdatableByteArray, AbstractUpdatableCharArray, AbstractUpdatableDoubleArray, AbstractUpdatableFloatArray, AbstractUpdatableIntArray, AbstractUpdatableLongArray, AbstractUpdatableObjectArray, AbstractUpdatableShortArray

public interface Array

AlgART array of any elements, read-only access.

It is the basic superinterface for MutableArray and UpdatableArray. Unlike that interfaces, the methods of this interface does not allow to modify elements or a number of elements. The instances of this interface, which do not implement its inheritors UpdatableArray and MutableArray, are usually returned by asImmutable() method.

If the elements of this array are primitive values (byte, short, etc.), the array must implement one of BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray subinterfaces. In other case, the array must implement ObjectArray subinterface.

Immutable arrays, implementing this interface, are thread-safe and can be used simultaneously in several threads. All other kinds of arrays are thread-compatible and can be synchronized manually if multithread access is necessary. Please see more details in the package description.

Author:

Daniel Alievsky

See Also:

• UpdatableArray
• MutableArray
• Matrix

Method Summary

Modifier and Type	Method	Description
Array	asCopyOnNextWrite()	Returns a copy-on-next-write view of this array.
Array	asImmutable()	Returns an immutable view of this array.
Array	asTrustedImmutable()	Returns a trusted immutable view of this array.
DataBuffer	buffer()	Equivalent to buffer(suitableMode, someCapacity), where both suitableMode and someCapacity arguments are chosen automatically.
DataBuffer	buffer(long capacity)	Equivalent to buffer(suitableMode, capacity), where capacity is the argument of this method and suitableMode is chosen automatically.
DataBuffer	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.
DataBuffer	buffer(DataBuffer.AccessMode mode, long capacity)	Returns a data buffer allowing block access to this array with the specified access mode and buffer capacity.
ByteOrder	byteOrder()	Returns the byte order used by this array for storing data.
long	capacity()	Returns the capacity of this array: the number of elements allocated for storing elements in this array.
void	checkUnallowedMutation()	Tries to check, whether some unallowed mutations of this trusted immutable array took place, and throw UnallowedMutationError in this case.
Class<?>	elementType()	Returns the type of array elements.
boolean	equals(Object obj)	Indicates whether some other array is equal to this one.
void	flushResources(ArrayContext context)	Equivalent to flushResources(context, false).
void	flushResources(ArrayContext context, boolean forcePhysicalWriting)	If there are some external resources, associated with this array, — files, streams, sockets, locks, etc. — and some array data are not still reflected in that resources (for example, were not saved in the disk file yet), this method flushs all these data to the external devices.
void	freeResources(ArrayContext context)	Equivalent to freeResources(context, false).
void	freeResources(ArrayContext context, boolean forcePhysicalWriting)	If there are some resources, associated with this array, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files).
void	getData(long arrayPos, Object destArray)	Copies min(this.length() - arrayPos, destArray.length}) elements of this array, starting from arrayPos index, into the specified Java array of corresponding type, starting from 0 index.
void	getData(long arrayPos, Object destArray, int destArrayOffset, int count)	Copies count elements of this array, starting from arrayPos index, into the specified Java array of corresponding type, starting from destArrayOffset index.
Object	getElement(long index)	Returns the element #index.
int	hashCode()	Returns the hash code of this array.
boolean	isCopyOnNextWrite()	Returns true if this array is copy-on-next-write.
default boolean	isEmpty()	Equivalent to the call length() == 0.
boolean	isImmutable()	Returns true if this instance is immutable, i.e. there are no ways to change its content or state.
boolean	isLazy()	Returns true if this array instance is lazy, i.e. if an access to its element means some calculations for producing result or actual saving element.
boolean	isNew()	Returns true if this array instance is new, i.e. it was created by one of MemoryModel methods, creating an array or a matrix (newXxx or valueOf), or by fully equivalent methods.
boolean	isNewReadOnlyView()	Returns true if this array instance is new-read-only-view, i.e. a newly created view of some external data, providing read-only access to this data — like LargeMemoryModel.asArray(Object, Class, long, long, java.nio.ByteOrder) method.
boolean	isUnresizable()	Returns true if this instance is unresizable, i.e. there are no ways to change its length or capacity.
Object	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.
long	length()	Returns the length: number of elements in this array.
default int	length32()	Returns the length as 32-bit int value.
void	loadResources(ArrayContext context)	If there are some external resources, associated with this array, — files, streams, sockets, locks, etc. — this method makes an effort to ensure that, when it returns, the content of this array will be resident in physical memory.
default Matrix<? extends Array>	matrix(long... dim)	Equivalent to matrix(thisArray, dim).
MutableArray	mutableClone(MemoryModel memoryModel)	Returns a mutable resizable copy of this array.
Class<? extends MutableArray>	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.
Object	newJavaArray(int length)	Returns usual Java-array (zero-filled) with the specified length and element type returned by elementType() method.
Array	shallowClone()	Returns a "shallow" clone of this object: another array consisting of the same elements, but with independent length, start offset, capacity, copy-on-next-write and possible other information about any array characteristics besides its elements.
Array	subArr(long position, long count)	Equivalent to subArray(position, position + count).
Array	subArray(long fromIndex, long toIndex)	Returns a view of the portion of this array between fromIndex, inclusive, and toIndex, exclusive.
String	toString()	Returns a brief string description of this object.
Class<? extends Array>	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.
UpdatableArray	updatableClone(MemoryModel memoryModel)	Returns an unresizable updatable copy of this array.
Class<? extends UpdatableArray>	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.

Method Details

elementType

Class<?> elementType()

Returns the type of array elements. For arrays of primitive types, returns:

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

All elements of the array are values of this type or (for non-primitive types) some inheritor of this type.

There is a guarantee that this method works very quickly (usually it just returns a value of some private field).

Returns:

the type of array elements.

See Also:

• Arrays.elementType(Class)

type

Class<? extends Array> 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. 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).

Returns:

canonical AlgART type of this array.

updatableType

Class<? extends UpdatableArray> 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. 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).

Returns:

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

mutableType

Class<? extends MutableArray> 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. 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).

Returns:

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

length

long length()

Returns the length: number of elements in this array.

There is a guarantee that this method works very quickly (usually it just returns a value of some private field). The result of this method is never negative.

Returns:

the length: number of elements in this array.

length32

default int length32()
              throws TooLargeArrayException

Returns the length as 32-bit int value. If the actual length is greater than Integer.MAX_VALUE, throws TooLargeArrayException.

This method is convenient to allocate memory for a regular Java array if you want to ensure that this AlgART array can be completely copied into such an array.

Returns:

the length: number of elements in this array, if it is less than 2³¹.

Throws:

TooLargeArrayException - if the actual length is greater than Integer.MAX_VALUE=2³¹−1.

isEmpty

default boolean isEmpty()

Equivalent to the call length() == 0.

Returns:

true if the array is empty, i.e. its length is zero.

capacity

long capacity()

Returns the capacity of this array: the number of elements allocated for storing elements in this array. For resizable arrays (implementing MutableArray interface), the internal storage will be reallocated after MutableArray.length(long) call only if the new length is greater than the current capacity.

There is a guarantee that this method works very quickly (usually it just returns a value of some private field).

Returns:

the capacity of this array.

getElement

Object getElement(long index)

Returns the element #index. It this array contains elements of primitive types, the value is automatically wrapped in an object (Boolean, Byte, etc.).

It is a low-level method. For arrays of primitive elements, implementing one of corresponding interfaces BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray, we recommend to use more efficient equivalent method of that interfaces: BitArray.getBit(long), CharArray.getChar(long), ByteArray.getByte(long), ShortArray.getShort(long), IntArray.getInt(long), LongArray.getLong(long), FloatArray.getFloat(long), DoubleArray.getDouble(long). For other arrays, implementing ObjectArray, we recommend to use ObjectArray.get(long).

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.

getData

void getData(long arrayPos,
 Object destArray,
 int destArrayOffset,
 int count)

Copies count elements of this array, starting from arrayPos index, into the specified Java array of corresponding type, starting from destArrayOffset index.

For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), this method may allocate new instances for Java array elements destArray[destArrayOffset]..destArray[destArrayOffset+count-1], but also may change the state of already existing non-null elements: it depends on implementation. In any case, you can be sure that if some of target elements destArray[k]==null, this method always allocate new element.

Note: if IndexOutOfBoundsException occurs due to attempt to write data outside the passed Java array, the target Java array can be partially filled. In other words, this method can be non-atomic regarding this failure. All other possible exceptions are checked in the very beginning of this method before any other actions (the standard way for checking exceptions).

Parameters:

arrayPos - starting position in this AlgART array.

destArray - the target Java array.

destArrayOffset - starting position in the target Java array.

count - the number of elements to be copied.

Throws:

NullPointerException - if destArray argument is null.

IllegalArgumentException - if destArray argument is not an array.

IndexOutOfBoundsException - if copying would cause access of data outside this array or target Java array.

ArrayStoreException - if destArray element type mismatches with this array elementType().

ClassCastException - if destArray element type mismatches with this array elementType() (both this and ArrayStoreException are possible, depending on implementation).

See Also:

• DirectAccessible
• UpdatableArray.setData(long, Object, int, int)
• BitArray.getBits(long, long[], long, long)

getData

void getData(long arrayPos,
 Object destArray)

Copies min(this.length() - arrayPos, destArray.length}) elements of this array, starting from arrayPos index, into the specified Java array of corresponding type, starting from 0 index.

For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), this method may allocate new instances for Java array elements destArray[0]..destArray[count-1], but also may change the state of already existing non-null elements: it depends on implementation. In any case, you can be sure that if some of target elements destArray[k]==null, this method always allocate new element.

Parameters:

arrayPos - starting position in this AlgART array.

destArray - the target Java array.

Throws:

NullPointerException - if destArray argument is null.

IllegalArgumentException - if destArray argument is not an array.

ArrayStoreException - if destArray element type mismatches with this array elementType().

ClassCastException - if destArray element type mismatches with this array elementType() (both this and ArrayStoreException are possible, depending on implementation).

See Also:

• DirectAccessible
• getData(long, Object, int, int)
• UpdatableArray.setData(long, Object)

newJavaArray

Object newJavaArray(int length)

Returns usual Java-array (zero-filled) with the specified length and element type returned by elementType() method.

This method is equivalent to the following call: java.lang.reflect.Array.newInstance(elementType(), length).

This method can be helpful while using together with getData / setData methods.

Parameters:

length - the length of created Java-array.

Returns:

Java-array with the specified length and the same type of elements.

Throws:

NegativeArraySizeException - if the specified length is negative.

subArray

Array subArray(long fromIndex,
 long toIndex)

Returns a view of the portion of this array between fromIndex, inclusive, and toIndex, exclusive.

• If fromIndex and toIndex are equal, the returned array is empty.
• The returned array is backed by this array, so — if this array is not immutable — any changes of the elements of the returned array are reflected in this array, and vice-versa.
• The capacity of returned array (returned by capacity() method) will be equal to the its length (returned by length(), that is toIndex-fromIndex.
• The type of elements of the returned array is the same as the type of elements of this array.
• The returned array is immutable, trusted immutable or copy-on-next-write, if, and only if, this array is immutable, trusted immutable or copy-on-next-write correspondingly.
• If (and only if) this array implements UpdatableArray interface, then the returned array also implements it. If (and only if) this array implements DirectAccessible interface, then the returned array also implements it. The returned array never implements MutableArray interface; it is always unresizable.

Like List.subList method, this method eliminates the need for explicit range operations. For example, you may use Arrays.sort(UpdatableArray, ArrayComparator) method for sorting a fragment of the array.

Unlike List.subList, the semantics of the array returned by this method is well-defined in any case, even in case of resizing of the source array. Namely, if the internal storage of this or returned array is reallocated, then the returned array will cease 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. Also, if the length of this array will be reduced, it can lead to clearing some elements in returned array: see comments to MutableArray.length(long) method.

Parameters:

fromIndex - low endpoint (inclusive) of the subarray.

toIndex - high endpoint (exclusive) of the subarray.

Returns:

a view of the specified range within this array.

Throws:

IndexOutOfBoundsException - for illegal fromIndex and toIndex (fromIndex < 0 || toIndex > length() || fromIndex > toIndex).

See Also:

• subArr(long, long)

subArr

Array subArr(long position,
 long count)

Equivalent to subArray(position, position + count). The only possible difference is other exception messages. If position+count>Long.MAX_VALUE (overflow), an exception message is allowed to be not fully correct (maximal speed is more important than absolutely correct exception messages for such exotic situations).

Parameters:

position - start position (inclusive) of the subarray.

count - number of elements in the subarray.

Returns:

a view of the specified range within this array.

Throws:

IndexOutOfBoundsException - for illegal position and count (position < 0 || count < 0 || position + count > length()).

See Also:

• subArray(long, long)

buffer

DataBuffer buffer(DataBuffer.AccessMode mode,
 long capacity)

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 length(), it is truncated to this length.

Parameters:

mode - the access mode for new buffer.

capacity - the capacity of the buffer.

Returns:

new data buffer for accessing this array.

Throws:

NullPointerException - if mode argument is null.

IllegalArgumentException - if the mode is not the DataBuffer.AccessMode.READ, but this arrays does not implement UpdatableArray interface, or if the specified capacity is negative or too high (>=0..2³⁷ for bits or >=0..2³¹ for other element types).

See Also:

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

buffer

DataBuffer 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. 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.

Parameters:

mode - the access mode for new buffer.

Returns:

new data buffer for accessing this array.

Throws:

NullPointerException - if mode argument is null.

IllegalArgumentException - if the mode is not the DataBuffer.AccessMode.READ, but this arrays does not implement UpdatableArray interface.

buffer

DataBuffer buffer(long capacity)

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).

Parameters:

capacity - the capacity of the buffer.

Returns:

new data buffer for accessing this array.

Throws:

IllegalArgumentException - if the specified capacity is negative or too high (>=0..2³⁷ for bits or >=0..2³¹ for other element types).

buffer

DataBuffer buffer()

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 buffer(net.algart.arrays.DataBuffer.AccessMode) and buffer(long) methods.

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

Returns:

new data buffer for accessing this array.

asImmutable

Array asImmutable()

Returns an immutable view of this array. If this array is already immutable (i.e. 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 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: isNew() method, called for the result of this method, always returns false — because it does not implement UpdatableArray.

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

• it this object is immutable (isImmutable()==true), then it is obvious (this method just returns a reference to this array);
• it this object is not immutable (isImmutable()==false), then, according to the contract to isNewReadOnlyView() method, isNewReadOnlyView() must return false for this array (in other case 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 isNewReadOnlyView()).

Returns:

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

See Also:

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

isImmutable

boolean isImmutable()

Returns true if this instance is immutable, i.e. there are no ways to change its content or state. (See asImmutable() method for more details.)

It is possible that array is immutable in fact, but this method returns false: for example, if the array is mapped to read-only file. However, it is guaranteed: if the array was created via asImmutable() method, this method returns true.

Typically, this method returns true if the array:

1. does not implement UpdatableArray interface;
2. does not implement DirectAccessible interface, or implements it, but DirectAccessible.hasJavaArray() method returns false.

But you should not use these conditions to check whether an array is immutable; please use this method instead. In principle, it is possible that both these conditions are satisfied, but the array is though mutable. Maybe, some class from another package (or from future versions of this package), implementing Array interface, does not implement neither UpdatableArray, nor DirectAccessible, but offers another methods allowing to change its state or content.

Note: if this method returns true, it does not mean that its content cannot be modified at all. Quite the contrary, usually an immutable array a is just an immutable view of another mutable array b (created via a=b.asImmutable() call), and the original array b does allow to change the content of the immutable array a. Immutability means only that there are no ways to modify the content or state of the object a, if this object a is the only reference to its content, which you have. The same note is true for immutable collections, created by the standard Collections.unmodifiableList and analogous methods. Please compare this with the behaviour of another method isNewReadOnlyView().

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

true if this instance is immutable.

See Also:

• asImmutable()

asTrustedImmutable

Array asTrustedImmutable()

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 checkUnallowedMutation() method.

In some implementations — for example, if DirectAccessible interface is not supported by this array — this method may return the same result as 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 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.

Returns:

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

See Also:

• asImmutable()
• checkUnallowedMutation()

checkUnallowedMutation

void checkUnallowedMutation()
                     throws UnallowedMutationError

Tries to check, whether some unallowed mutations of this trusted immutable array took place, and throw UnallowedMutationError in this case. Does nothing if this array implement UpdatableArray interface or if it is truly immutable.

Implementation of this method usually checks whether the hash code was changed since array creation.

We recommend to call this method in finally sections after using the trusted immutable array. If it is impossible to create necessary finally section, you may use Finalizer class (or an equivalent tool) to schedule call of this method for the shallow clone of this array on deallocation of this array:

 Finalizer fin = ...(some global application finalizer);
 final Array dup = thisArray.shallowClone();
 // - must be here, not inside the following inner class, to allow deallocation of thisArray
 fin.invokeOnDeallocation(thisArray, new Runnable() {
     void run() {
         try {
             dup.checkUnallowedMutation();
         } catch (UnallowedMutationError ex) {
             myLogger.severe(ex.toString());
         }
     }
 });
 

Important: while using this finalization scheme, this array must not be copy-on-next-write! Illegal modifications of copy-on-next-write array will not change it's shallow clone and will not be detected.

Throws:

UnallowedMutationError - if some unallowed mutations of this array took place.

See Also:

• asTrustedImmutable()

asCopyOnNextWrite

Array asCopyOnNextWrite()

Returns a copy-on-next-write view of this array. If this array is immutable (and only in this case), returns a reference to this object. If (and only if) this array implements UpdatableArray interface, then the returned array also implements it. If (and only if) this array implements MutableArray interface, then the returned array also implements it.

Copy-on-next-write array is an array with the following special feature: the next attempt (but not further!) to modify this array, or any other access that can lead to its modification (like DirectAccessible.javaArray() method), will lead to reallocation of the underlying storage, used for array elements, before performing the operation. In other words, you have a guarantee: if this array is a view of some another array or data (for example, a subarray or a view of Java array, that there are no ways to change that data via accessing the returned array. Any changes, it they will occur, will be performed with the newly allocated storage only.

Please be careful: it you will want to change arrays created by this method, the result may be unexpected! For example, an attempt to copy other arrays into copy-on-next-write array by some methods like Arrays.copy(ArrayContext, UpdatableArray, Array) will probable do nothing. The reason is working with the array via its subarrays — for example, Arrays.copy method splits the source and target arrays into subarrays and copies these subarrays. (Usual UpdatableArray.copy(Array) method and other mutation methods of the resulting array will work normally.) The main goal of copy-on-next-write arrays is protection againts unwanted changing an original array; it is supposed that the client, in normal situation, will only read such arrays and will not try to change them.

There are no guarantees that the returned array will be a view of this one, even immediately after creation. Some implementations of updatable arrays may just return the full (deep) copy of this object, alike mutableClone(MemoryModel) method, and in this case TooLargeArrayException is possible. All implementations from this package, excepting AbstractUpdatableXxxArray classes, returns a view; but in AbstractUpdatableXxxArray classes this method is equivalent to updatableClone(Arrays.SMM).

Please note that copy-on-next-write arrays are not traditional copy-on-write objects like CopyOnWriteArrayList! In particular, copy-on-next-write arrays are not thread-safe.

The main purpose of using copy-on-next-write arrays is more efficient alternative to cloning and creating quite immutable views, when we need to be sure that original data will not be corrupted. Please see the package description to learn more about possible usage of this technique.

Returns:

a copy-on-next-write view of this array (or a reference to this array if it is immutable).

Throws:

TooLargeArrayException - if this method actually creates a copy of this array, but the length of this array is too large for the memory model, used for allocating a copy.

See Also:

• isCopyOnNextWrite()
• MemoryModel.newLazyCopy(Array)
• MemoryModel.newUnresizableLazyCopy(Array)

isCopyOnNextWrite

boolean isCopyOnNextWrite()

Returns true if this array is copy-on-next-write. In other words, if this method returns true, it means that the next attempt (but not further) to modify this array, or any other access that can lead to its modification (like DirectAccessible.javaArray() method), will lead to reallocation of the underlying storage. After reallocation, the array will cease to be copy-on-next-write: further calls of this method will return false.

This method can be useful if it's possible to select another, more optimal algorithm branch, allowing to avoid reallocation for copy-on-next-write arrays. The typical example is usage of DirectAccessible interface. That interface, providing direct access to the internal Java array (which is a storage of the array elements), can optimize most of the algorithms processing an array. However, reallocation of the Java array, that will be a result of calling DirectAccessible.javaArray() for copy-on-next-write array, can make such "optimization" very unwanted.

The only standard way to make copy-on-next-write is calling asCopyOnNextWrite() method.

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

true if this array is copy-on-next-write.

See Also:

• asCopyOnNextWrite()

isUnresizable

boolean isUnresizable()

Returns true if this instance is unresizable, i.e. there are no ways to change its length or capacity.

It is guaranteed that if the array was created via asImmutable() method, this method returns true.

Typically, this method returns true if the array does not implement MutableArray. But you should not use this condition to check whether an array is unresizable; please use this method instead. Maybe, some class from another package (or from future versions of this package), implementing this Array interface, does not implement MutableArray, but offer another methods allowing to change its state or content.

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

true if this instance is unresizable.

See Also:

• UpdatableArray.asUnresizable()

isNew

boolean isNew()

Returns true if this array instance is new, i.e. it was created by one of MemoryModel methods, creating an array or a matrix (newXxx or valueOf), or by fully equivalent methods. All other ways of creating AlgART array instance (asImmutable(), shallowClone(), subArray(long, long), SimpleMemoryModel.asUpdatableArray(Object) etc.) create non-new arrays.

In updatable arrays the "new status", returned by this method, can be cleared manually by UpdatableArray.setNonNew() method. Note that immutable arrays, not implementing UpdatableArray interface, are never new (this method returns false).

If the array is new, you can be sure that it is an original object, storing the data, but not a view of some other array (immutable view, subarray, etc.) or of another kind of data (Java array, file, etc.) This can be important for managing data, associated with AlgART arrays.

For example, let we have some source (factory), generating AlgART arrays (like a library of installable Java plugins), and we need to safely store the content of these arrays in some permanent storage. Of course, we can store a full clone of each array with help of updatableClone(MemoryModel) or mutableClone(MemoryModel) method, but it can be inefficient for very large arrays (many gigabytes). On the other hand, we usually cannot just store a reference to an AlgART array or to its internal data: it is very possible, that one array, received from the factory, is a view of another one (immutable view, subarray, etc.), and storing both references in our storage will lead to incorrect behaviour — possible future changing of one element of the storage will be reflected in other elements.

New status of the array, provided by this method, allows to correctly resolve this problem. We should store in the storage the full content (clone) of an array, if this method returns false, or the reference to an array or to its internal data (as DirectAccessible.javaArray()), if it returns true. In the second case, we must additionally clear the status of the original array object, received from the factory, by UpdatableArray.setNonNew() method — it guarantees that we shall store only 1 reference to each really new array.

Additional important feature, provided by this method: if you know the memory model, which has created this instance, then you can be absolutely sure in all details of the algorithm of internal storing the array data (if it is documented in the corresponding memory model). It is important, for example, for LargeMemoryModel: if this method returns true, then the content of this array corresponds to the content of an external file according to a known, fully documented scheme. Unlike this, another forms of AlgART arrays — like subarrays — have no documented correspondence with the content of an external data, even when we can retrieve some information about such data (as a name of the disk file LargeMemoryModel.getDataFilePath(Array)).

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

whether this array instance is new: a new object, allocated by some MemoryModel.

See Also:

• isNewReadOnlyView()

isNewReadOnlyView

boolean isNewReadOnlyView()

Returns true if this array instance is new-read-only-view, i.e. a newly created view of some external data, providing read-only access to this data — like LargeMemoryModel.asArray(Object, Class, long, long, java.nio.ByteOrder) method. All other ways of creating AlgART array instance (methods of MemoryModel class, asImmutable(), shallowClone(), subArray(long, long)} etc.) create arrays, in which this method returns false. In the current version of this package, the only ways to create new-read-only-view AlgART array are the following:

• the method LargeMemoryModel.asArray(Object, Class, long filePosition, long fileAreaSize, ByteOrder byteOrder), when its filePosition argument is zero (filePosition==0);
• the versions of this method for concrete element types asBitArray, asCharArray, asByteArray, asShortArray, asIntArray, asLongArray, asFloatArray, asDoubleArray in a case of the same condition: their filePosition argument is zero;
• LargeMemoryModel.asMatrix(Object filePath, MatrixInfo matrixInfo) method in a case when the data offset, stored in its MatrixInfo argument, is zero — then the array, extracted from such a matrix by LargeMemoryModel.getRawArrayForSavingInFile(Matrix) method, will be new-read-only-view.

New-read-only-view status, returned by this method, is final and cannot be changed after instantiation of the instance. (More precisely, there are no methods, allowing to change it after finishing the method, which has created a new array instance.) Note that in updatable arrays, implementing UpdatableArray interface, this method returns false always. Moreover, if this method returns true, then there is a guarantee that isImmutable() method also returns true.

If this method returns true, you can be sure that it is an original object, associated with external data with read-only access rights, but not a view of some other array (immutable view, subarray, etc.) and not an updatable view of some external data, allowing to change them. This can improve efficiency of managing data, associated with AlgART arrays, in addition to isNew() method.

Please read again the possible scheme of storing array data in some storage, listed in the comments to isNew(). Sometimes we need to store some number of absolutely identical AlgART arrays, corresponding to the same data, maybe very large (many gigabytes). The listed scheme permits storing only 1 reference to each array (or its data), because we should avoid ability of changes in one stored array, reflecting in another stored array. It is a good and safe strategy, but it does not provide maximal performance in a case, when we know that all data are immutable (read-only) and we shall never change them. In the last case, there is no problem to create any number of references to the same data, as well as there is no problem to create a lot of references to the same immutable Java object like String.

This method allows to improve the described behaviour. Namely, if this method returns true, you still may store the reference to an AlgART array or to its internal data in your storage, though isNew() returns false. Yes, you can so create several references to the same array data, but it does not lead to incorrect behaviour — this data will always remain unchanged.

But here is an important warning: while using this technique, you should never try to increase the access rights to the external data, corresponding to the AlgART array, stored in your storage. More precisely, you should not try to provide write access to this data — even if the API allows to do this. In a case of LargeMemoryModel, it means that you should not access to the disk file, retrieved from an array by LargeMemoryModel.getDataFilePath(Array) method, via LargeMemoryModel.asUpdatableArray method — please use the original reference to AlgART array (where this method returns true) or new instances, created by LargeMemoryModel.asArray method. Maybe, future versions of LargeMemoryModel class will contain API, which will allow to provide OS-level protection against any attempts to write into files, containing the data, stored in your storage of AlgART arrays.

In addition, this method provides the same feature as isNew() method: if you know the memory model, which has created this instance, then you can be absolutely sure in all details of the algorithm of internal storing the array data (if it is documented in the corresponding memory model). It is important for LargeMemoryModel: if this method returns true, then the content of this array corresponds to the content of an external file according to a known, fully documented scheme. Unlike this, another forms of AlgART arrays — like subarrays — have no documented correspondence with the content of an external data, even when we can retrieve some information about such data (as a name of the disk file LargeMemoryModel.getDataFilePath(Array)).

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

whether this array instance is a newly created view of some external data, providing read-only access to this data.

isLazy

boolean isLazy()

Returns true if this array instance is lazy, i.e. if an access to its element means some calculations for producing result or actual saving element. Examples of lazy arrays are results of Arrays.asFuncArray(net.algart.math.functions.Func, Class, PArray...) and analogous methods.

If this method returns false, it means that reading elements (and writing for updatable arrays) is performed as quickly as possible: it is just copying data from one memory (maybe a disk) to another. In particular, this method returns false for new arrays, their immutable views, subarrays, etc.

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

whether this array instance if lazy.

byteOrder

ByteOrder byteOrder()

Returns the byte order used by this array for storing data.

This value does not important for using AlgART arrays. The only case when it can be interesting is when the array is stored in some external resources, for example, in a disk file.

For all array instances created by this package the byte order is native (ByteOrder.nativeOrder()), with the only exception: arrays, created by LargeMemoryModel.asArray(Object, Class, long, long, ByteOrder), LargeMemoryModel.asUpdatableArray(Object, Class, long, long, boolean, ByteOrder) methods and their versions for concrete element types, will have byte order specified by the argument of these methods.

Please note: in the combined arrays, created via CombinedMemoryModel, this method returns ByteOrder.nativeOrder(), though the byte order in the underlying storage arrays may be another.

This method never returns null.

There is a guarantee that this method works very quickly (usually it just returns a constant or a value of some private field).

Returns:

the byte order used by this array for storing data.

shallowClone

Array shallowClone()

Returns a "shallow" clone of this object: another array consisting of the same elements, but with independent length, start offset, capacity, copy-on-next-write and possible other information about any array characteristics besides its elements. In other words, any changes in the elements of the returned array are usually reflected in this array, and vice-versa; but changes of any other characteristics of the original or returned array, including the length, capacity, etc., will not be reflected in another array.

Please note: this method never returns a reference to this object, even if this array is immutable! Moreover, the returned object does not store any references to this instance in any internal fields. It can be important while using weak references and reference queues: this object and its shallow copy are deallocated by the garbage collector separately.

There are no guarantees that the returned array will share the elements with this one. Some implementations may return the full (deep) copy of this object, alike updatableClone(MemoryModel) or mutableClone(MemoryModel) methods. All implementations from this package returns a shallow (non-deep) copy.

If modifications of this or returned 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.

The values of length(), capacity(), DirectAccessible.javaArrayOffset(), isCopyOnNextWrite() in the result will be the same as in this array. The returned instance implements the same set of interfaces as this array.

This method is an analog of the standard Java NIO ByteBuffer.duplicate() method. However, unlike ByteBuffer.duplicate(), this method is necessary very rarely. Usually, you need another forms of array views: asImmutable(), UpdatableArray.asUnresizable(), etc. The most often usage of this method is finalization via Finalizer class: see example in comments to checkUnallowedMutation() method. Also this method can be useful if you need to pass an array with the same content into some another class, but must be sure that further resizing of the source array will not affect to correct work of that class.

Returns:

a shallow copy of this object.

See Also:

• length()
• capacity()
• DirectAccessible.javaArrayOffset()
• isCopyOnNextWrite()

mutableClone

MutableArray mutableClone(MemoryModel memoryModel)

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);
 

Parameters:

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

Returns:

a mutable copy of this array.

Throws:

NullPointerException - if the argument is null.

UnsupportedElementTypeException - if thisArray.elementType() is not supported by the specified memory model.

TooLargeArrayException - if the length of this array is too large for this the specified memory model.

See Also:

• updatableClone(MemoryModel)

updatableClone

UpdatableArray updatableClone(MemoryModel memoryModel)

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);
 

Parameters:

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

Returns:

an updatable copy of this array.

Throws:

NullPointerException - if the argument is null.

UnsupportedElementTypeException - if thisArray.elementType() is not supported by the specified memory model.

TooLargeArrayException - if the length of this array is too large for this the specified memory model.

See Also:

• mutableClone(MemoryModel)

ja

Object 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.

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()}, LongArray.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.

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 Array> matrix(long... dim)

Equivalent to matrix(thisArray, dim).

Parameters:

dim - the matrix dimensions.

Returns:

new matrix backed by array with the given dimensions.

Throws:

NullPointerException - if array or dim argument is null.

IllegalArgumentException - if the passed array is resizable (for example, implements MutableArray), or if the number of dimensions is 0 (empty dim Java array), or if some of dimensions are negative.

SizeMismatchException - if the product of all dimensions is not equal to the array length.

TooLargeArrayException - if the product of all dimensions is greater than Long.MAX_VALUE.

loadResources

void loadResources(ArrayContext context)

If there are some external resources, associated with this array, — files, streams, sockets, locks, etc. — this method makes an effort to ensure that, when it returns, the content of this array will be resident in physical memory. In other words, this method tries to preload the content of this array into RAM to provide fastest access to its elements in the nearest future.

There are no any guarantees that all elements of this array will be really preloaded into RAM. This method usually avoids loading too large amount of data, comparable with the whole amount of RAM. For example, if the size of this array is 10 GB, it is possible only first several megabytes or tens of megabytes will be preloaded. If you work with a large array, we recommend to call this method for a not too large its subarray, which really should be processed now, for example:

 final int blockSize = 1048576;
 for (long pos = 0, n = array.length(); pos < n; pos += blockSize) {
     int len = (int)Math.min(blockSize, n - pos);
     Array region = array.subArr(pos, len);
     region.loadResources(someContext)};
     // some algorithm processing len elements of this region
 }
 

If the resources, associated with this array, are shared with some another arrays (usually when one array is a view of another one), this method tries to preload the content of that arrays, though it is not guaranteed. This method usually does nothing if the length of this array is zero.

The context argument is necessary to allow user to interrupt this method and to view the execution progress. Namely, if this argument is not null, this method probably calls context.checkInterruption and context.updateProgress methods from time to time. It may be useful if preloading data can require long time, for example, the content should be loaded from Internet. You always may pass null as this argument; then all will work correctly, but, maybe, the user will be bored for some time. For all arrays, created by this package, this method works quickly enough and doesn't require non-null context.

This method does nothing for arrays created by the simple memory model and the buffer memory model, and also for constant arrays created by Arrays.nByteCopies(long, byte), Arrays.nCharCopies(long, char), etc.: these arrays have no associated resources.

Parameters:

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

See Also:

• freeResources(ArrayContext)
• flushResources(ArrayContext)
• flushResources(ArrayContext, boolean)

flushResources

void flushResources(ArrayContext context)

Equivalent to flushResources(context, false). It is the most typical case of flushing resources.

Parameters:

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

See Also:

• loadResources(ArrayContext)
• freeResources(ArrayContext)

flushResources

void flushResources(ArrayContext context,
 boolean forcePhysicalWriting)

If there are some external resources, associated with this array, — files, streams, sockets, locks, etc. — and some array data are not still reflected in that resources (for example, were not saved in the disk file yet), this method flushs all these data to the external devices.

This method may not perform immediate writing data to the storage devices. But it guarantees that:

1. if some AlgART array will be created and associated with the same resources as this array — for example, will be mapped to the same external file — all data stored in this array will be "visible" in the new array;
   
2. if this array is a view of some external resource, that is not "temporary" (i.e. will not be automatically deleted after shutting down JVM), then all changes, made in this array, will be really stored in that resource and will be able to be loaded by another software, at least, after shutting down JVM.

If forcePhysicalWriting argument is false, this method works as quick as possible.

If forcePhysicalWriting argument is true, this method tries to physically flush all unsaved elements of this array to the storage device. The precise actions, performed in this case, are not specified. The typical behaviour: all internal caches, if they are provided by Java imlementation of the AlgART array, are written to the external device via OS calls, and OS is requested to flush buffers or file-mapping to the physical disk. The mode forcePhysicalWriting=true increases chances that the data will be really flushed to external devices and, so, OS will release physical memory, which was probably used for disk or another cache. This mode also increases chances that all changes, made in this array until this moment, will be immediately "visible" in another software (another OS process) as changes in the corresponding external resources (for example, in the disk file).

If the resources, associated with this array, are shared with some another arrays (usually when one array is a view of another one), this method still does flush these resource.

You may use subArray(long, long) / subArr(long, long) methods to flush any portion of this array, for example:

     array.subArr(destPos, count).flushResources(context, false);

But there is no guarantee that flushing a subarray will not lead to flushing some other parts of the source array.

In particular, please note: this method may do something even for immutable arrays. If an array is an immutable view of another array a, flushing this view is equivalent to flushing the original array a.

The context argument is necessary to allow user to interrupt this method and to view the execution progress. Namely, if this argument is not null, this method probably calls context.checkInterruption and context.updateProgress methods from time to time. It may be useful if this array is very large and writing non-flushed data to an external device requires long time. For example, it is possible for arrays, created by LargeMemoryModel.newLazyCopy method. You always may pass null as this argument; then all will work correctly, but, maybe, the user will be bored for some time.

This method does nothing for arrays created by the simple memory model and the buffer memory model, and also for constant arrays created by Arrays.nByteCopies(long, byte), Arrays.nCharCopies(long, char), etc.: these arrays have no associated resources.

All operations, performed by this method, are also performed by freeResources(ArrayContext, boolean) method with the same forcePhysicalWriting argument.

Performance note: please avoid sequential calls of this method, like the following:

     array.flushResources(null, false);
     array.flushResources(null, false); // - unnecessary call
 

The second call here is not necessary, because all data are already flushed while the first call — however, it is still possible that the second call will spend time for writing data again t o an external device.

Parameters:

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

forcePhysicalWriting - is it necessary to try forcing physical writing all associated resources to the external device.

See Also:

• loadResources(ArrayContext)
• flushResources(ArrayContext)
• freeResources(ArrayContext, boolean)

freeResources

void freeResources(ArrayContext context)

Equivalent to freeResources(context, false). It is the most typical case of freeing resources.

Parameters:

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

See Also:

• loadResources(ArrayContext)
• flushResources(ArrayContext)

freeResources

void freeResources(ArrayContext context,
 boolean forcePhysicalWriting)

If there are some resources, associated with this array, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files). However, the array stays alive: if the resources will be necessary for following array operations, they will be automatically re-acquired.

As a part of the work, this method always performs the same actions as flushResources(context, forcePhysicalWriting) call with the same forcePhysicalWriting argument. See comments to that method for more details about flushing external resources.

This method guarantees that any changes, made after its call in any external resources, associated with this array, will be "visible" in this array while any accesses to it after these changes. For example, if this array is a view of some disk file, you need to call this method to be sure that any changes, performed in the file by another application after this call and before the next access to this array, will be successfully reflected in this array.

If the resources, associated with this array, are shared with some another arrays (usually when one array is a view of another one), this method still does release these resource. It means that calling this method can slow down the next access not only to this array, but also to another ones, for example, to its subarrays.

The context argument is necessary to allow user to interrupt this method and to view the execution progress. Namely, if this argument is not null, this method probably calls context.checkInterruption and context.updateProgress methods from time to time. It may be useful if this array is very large and writing non-flushed data to an external device requires long time. For example, it is possible for arrays, created by LargeMemoryModel.newLazyCopy method. You always may pass null as this argument; then all will work correctly, but, maybe, the user will be bored for some time.

This method does nothing for arrays created by the simple memory model and the buffer memory model, and also for constant arrays created by Arrays.nByteCopies, Arrays.nCharCopies, etc.: these arrays have no associated resources.

Performance note 1: you may use the call

     array.subArray(0,0).freeResources(null, false)
 

to release all resources, associated with the original array. It may work faster than simple "array.freeResources(null,false)", because there is no necessity to flush all array elements: releasing a subarray requires flushing only the subarray elements, i.e. no elements in a case of the zero-length subarray. This speeding-up is guaranteed for arrays, created by large memory model, but is not guaranteed for other arrays: it is still possible that "array.subArray(0,0).freeResources(context,false)" call will flush all array data.

Performance note 2: please avoid calling flushResources(ArrayContext, boolean) together with this method:

     array.flushResources(null, false); // - unnecessary call
     array.freeResources(null, false);
 

or

     array.flushResources(null, true);
     array.freeResources(null);
     // - it's much better to use a single call "array.freeResources(null, true)"
 

It is very possible that the call of freeResources method will spend time for flushing data again, though they were already flushed by the previous flushResources method. If is much better to perform all the work in a single call of this method with the corresponding forcePhysicalWriting argument.

All resources allocated by this package are automatically released and — for temporary resources, i.e. garbage, — removed (as it is possible) by built-in cleanup procedures while JVM termination. However, we recommend to directly call freeResources(context) at the end of methods that create and process large AlgART arrays. The reason is that if there will be a lot of non-released large arrays, the automatic cleanup procedure may strongly reduce the speed of closing the application.

Important: you must use this method if you are working with some collection (like java.util.List or a usual Java array) of large AlgART arrays (each per many megabytes or gigabytes) and if this collection contains many elements: more than several tens. If an AlgART array has some associated resources, for example, like arrays created by LargeMemoryModel and mapped on a disk file, then every such instance usually occupies some RAM (and also, maybe, OS address space for mapping), usually up to several tens of megabytes (for large arrays) for caching and similar needs. This RAM cannot be automatically released by the garbage collector until you call this method. So, you must manually release all resources by calling this method every time, when this array is already not necessary, but should be stored in some collection for the future. In other case, thousands of inactive instances of AlgART arrays with non-released resources can exhaust all available RAM (or address space).

Parameters:

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

forcePhysicalWriting - is it necessary to try forcing physical writing all associated resources to the external device.

See Also:

• loadResources(ArrayContext context)
• flushResources(ArrayContext context, boolean forcePhysicalWriting)
• freeResources(ArrayContext)
• Arrays.freeAllResources()

toString

String toString()

Returns a brief string description of this object.

The result of this method may depend on implementation and usually contains a short description of the array length, capacity, element type.

Note: for character arrays, unlike CharSequence.toString(), this method works as for all other array types. If you need to convert a character array to a string, containing all characters of the array, you may use Arrays.toString(CharArray) method.

Overrides:

toString in class Object

Returns:

a brief string description of this object.

hashCode

int hashCode()

Returns the hash code of this array. The result depends on all elements of the array (from element #0 to element #length()-1).

For non-primitive element type (ObjectArray, UpdatableObjectArray, MutableObjectArray subinterfaces), the result is always based on implementation of hashCode method in the class of elements (elementType()).

Overrides:

hashCode in class Object

Returns:

the hash code of this array.

equals

boolean equals(Object obj)

Indicates whether some other array is equal to this one. Returns true if and only if:

1. the specified object is an array (i.e. implements Array),
2. both arrays have the same length,
3. for arrays of primitive elements (BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray): both arrays have the same element type and all corresponding pairs of elements are equal (for float and double elements, unlike the == operator, this method considers NaN equals to itself, and 0.0 unequal to -0.0);
4. for non-primitive arrays (when both arrays implement ObjectArray), the method may check one from two following conditions (only 1st or only 2nd, depending on implementation):
   • both arrays have the same element type and all corresponding pairs of elements contain identical data (equals method of the class of elements is not used in this case: combined arrays are an example);
   • for all corresponding pairs of elements e1, e2 (e1 is an element #i of this array, e2 is an element #i of the obj argument, i=0,1,...,length()-1), the following check returns true: (e1==null ? e2==null : e1.equals(e2)).

Overrides:

equals in class Object

Parameters:

obj - the object to be compared for equality with this array.

Returns:

true if the specified object is an array equal to this one.