Package net.algart.arrays

Class AbstractMatrix<T extends Array>

java.lang.Object

net.algart.arrays.AbstractMatrix<T>

All Implemented Interfaces:

Cloneable, Matrix<T>

public abstract class AbstractMatrix<T extends Array>
extends Object
implements Matrix<T>

A skeletal implementation of the Matrix interface to minimize the effort required to implement this interface.

All non-abstract methods are completely implemented here and may be not overridden in subclasses.

Author:

Daniel Alievsky

Nested Class Summary

Nested classes/interfaces inherited from interface net.algart.arrays.Matrix

Matrix.ContinuationMode

Field Summary

Fields inherited from interface net.algart.arrays.Matrix

MAX_DIM_COUNT_FOR_SOME_ALGORITHMS

Constructor Summary

Constructors

Constructor	Description
AbstractMatrix()

Method Summary

Modifier and Type	Method	Description
abstract T	array()	Returns a reference to the built-in AlgART array.
long	bitsPerElement()	Returns the number of in bits, required for each element of this matrix, if they are primitive; in other case returns −1.
<U extends Array> Matrix<U>	cast(Class<U> arrayClass)	Returns this matrix, cast to the specified generic array type, or throws ClassCastException if the built-in AlgART array cannot be cast to the required type (because the array type is not its subclass).
Matrix<T>	clone()	Returns an exact clone of this matrix, created in SimpleMemoryModel.
long[]	coordinates(long index, long[] result)	Returns the coordinates in the matrix, corresponding to the given linear index in the built-in AlgART array.
long	cyclicIndex(long... coordinates)	An analog of Matrix.index(long...) method, that, before all calculations, replaces the passed coordinates with the positive remainders from division of them by the corresponding matrix dimensions.
abstract long	dim(int n)	Returns the dimension #n of this matrix or 1 if n>=Matrix.dimCount().
abstract int	dimCount()	Returns the number of dimensions of this matrix.
abstract long[]	dimensions()	Returns an array containing all dimensions of this matrix.
boolean	dimEquals(long... dimensions)	Indicates whether the passed dimensions are equal to the dimension array of this matrix.
boolean	dimEquals(Matrix<?> m)	Indicates whether the other matrix has the same dimension array.
long	dimX()	Equivalent to dim(0).
long	dimY()	Equivalent to dim(1).
long	dimZ()	Equivalent to dim(2).
Class<?>	elementType()	Returns the type of matrix elements.
boolean	equals(Object obj)	Indicates whether some other matrix is equal to this one.
void	flushResources(ArrayContext context)	Equivalent to Matrix.array().flushResources(context).
void	freeResources()	Equivalent to Matrix.array().freeResources(null).
void	freeResources(ArrayContext context)	Equivalent to Matrix.array().freeResources(context).
int	hashCode()	Returns the hash code of this matrix.
long	index(long... coordinates)	Returns the linear index in the built-in AlgART array of the matrix element with specified coordinates.
long	index(long x, long y)	The simplified version of the full index method for the case of 2-dimensional matrix.
long	index(long x, long y, long z)	The simplified version of the full index method for the case of 3-dimensional matrix.
boolean	inside(long... coordinates)	Returns true if all specified coordinates ik are inside the ranges 0..dk-1, where dk=dim(k).
boolean	inside(long x, long y)	The simplified version of the full inside method for the case of 2-dimensional matrix.
boolean	inside(long x, long y, long z)	The simplified version of the full inside method for the case of 3-dimensional matrix.
boolean	isCopyOnNextWrite()	Equivalent to Matrix.array().isCopyOnNextWrite().
boolean	isDirectAccessible()	Returns true if and only if the built-in AlgART array implements DirectAccessible interface and ((DirectAccessible)Matrix.array()).hasJavaArray() method returns true.
boolean	isFixedPoint()	Returns true if and only if the element type is fixed-point: Matrix.array() instanceof PFixedArray.
boolean	isFloatingPoint()	Returns true if and only if the element type is float or double: Matrix.array() instanceof PFloatingArray.
boolean	isImmutable()	Equivalent to Matrix.array().isImmutable().
boolean	isPrimitive()	Returns true if and only if the element type is primitive: Matrix.array() instanceof PArray.
boolean	isStructuredLike(Matrix<?> m)	Returns true if the elements of this matrix is ordered "alike" the elements of the specified matrix m, in terms of Matrix.structureLike(Matrix) method.
boolean	isSubMatrix()	Returns true if and only if this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...), parent.subMatr(...) or equivalent.
boolean	isTiled()	Returns true if and only if this matrix is a tiled view of some parent matrix, created by a call parent.tile(...) or an equivalent call.
boolean	isUnsigned()	Returns true if and only if the element type is boolean.class, short.class, byte.class or short.class.
abstract <U extends Array> Matrix<U>	matrix(U anotherArray)	Returns the new matrix backed by the specified AlgART array with the same dimensions as this one.
double	maxPossibleValue()	Returns the maximal possible value, that can stored in elements of this matrix, if they are fixed-point elements, or 1.0 for floating-point elements, or Double.NaN if elements are not primitive.
double	maxPossibleValue(double valueForFloatingPoint)	Returns the maximal possible value, that can stored in elements of this matrix, if they are fixed-point elements, or the argument for floating-point elements, or Double.NaN if elements are not primitive.
long	mirrorCyclicIndex(long... coordinates)	An analog of Matrix.index(long...) method, that, before all calculations, replaces the passed coordinates with the positive remainders from division of them by the corresponding matrix dimensions or with complement of these remainders on the dimensions, as if the matrix would be reflected in each its bound as in a mirror.
long	pseudoCyclicIndex(long... coordinates)	An analog of Matrix.index(long...) method, that does not check, whether the passed coordinates are in the required ranges, but replaces the resulting index with the positive remainder from division of it by the length of the built-in array.
Matrix<T>	structureLike(Matrix<?> m)	Returns a view ot this matrix, where the elements are reordered in some order "like" in the specified matrix m.
Matrix<T>	subMatr(long[] position, long[] dimensions)	Equivalent to Matrix.subMatrix(long[] from, long[] to) method, where from[k]=position[k] and to[k]=position[k]+dimensions[k] for all k.
Matrix<T>	subMatr(long[] position, long[] dimensions, Matrix.ContinuationMode continuationMode)	Equivalent to Matrix.subMatrix(long[] from, long[] to, ContinuationMode continuationMode) method, where from[k]=position[k] and to[k]=position[k]+dimensions[k] for all k.
Matrix<T>	subMatr(long x, long y, long dimX, long dimY)	Equivalent to subMatr(new long[]{x,y}, new long[]{dimX,dimY}).
Matrix<T>	subMatr(long x, long y, long z, long dimX, long dimY, long dimZ)	Equivalent to subMatr(new long[]{x,y,z}, new long[]{dimX,dimY,dimZ}).
Matrix<T>	subMatr(long x, long y, long z, long dimX, long dimY, long dimZ, Matrix.ContinuationMode continuationMode)	Equivalent to subMatr(new long[]{x,y,z}, new long[]{dimX,dimY,dimZ}, continuationMode).
Matrix<T>	subMatr(long x, long y, long dimX, long dimY, Matrix.ContinuationMode continuationMode)	Equivalent to subMatr(new long[]{x,y}, new long[]{dimX,dimY}, continuationMode).
Matrix<T>	subMatrix(long[] from, long[] to)	Returns a view of the rectangular fragment of this matrix between from, inclusive, and to, exclusive.
Matrix<T>	subMatrix(long[] from, long[] to, Matrix.ContinuationMode continuationMode)	An extended analog of Matrix.subMatrix(long[], long[]) method, allowing to get a rectangular fragment which is not fully inside this matrix.
Matrix<T>	subMatrix(long fromX, long fromY, long toX, long toY)	Equivalent to subMatrix(new long[]{fromX,fromY}, new long[]{toX,toY}).
Matrix<T>	subMatrix(long fromX, long fromY, long fromZ, long toX, long toY, long toZ)	Equivalent to subMatrix(new long[]{fromX,fromY,fromZ}, new long[]{toX,toY,toZ}).
Matrix<T>	subMatrix(long fromX, long fromY, long fromZ, long toX, long toY, long toZ, Matrix.ContinuationMode continuationMode)	Equivalent to subMatrix(new long[]{fromX,fromY,fromZ}, new long[]{toX,toY,toZ}, continuationMode).
Matrix<T>	subMatrix(long fromX, long fromY, long toX, long toY, Matrix.ContinuationMode continuationMode)	Equivalent to subMatrix(new long[]{fromX,fromY}, new long[]{toX,toY}, continuationMode).
Matrix<T>	subMatrix(IRectangularArea area)	Equivalent to Matrix.subMatrix(long[] from, long[] to) method, where from.length=to.length=area.coordCount(), from[k]=area.min(k), to[k]=area.max(k)+1.
Matrix<T>	subMatrix(IRectangularArea area, Matrix.ContinuationMode continuationMode)	Equivalent to Matrix.subMatrix(long[] from, long[] to, ContinuationMode continuationMode) method, where from.length=to.length=area.coordCount(), from[k]=area.min(k), to[k]=area.max(k)+1.
Matrix.ContinuationMode	subMatrixContinuationMode()	If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), returns the continuation mode, used by this submatrix.
long[]	subMatrixFrom()	If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), creates and returns a new Java array containing the starting position of this submatrix in the parent one.
Matrix<T>	subMatrixParent()	If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), returns a reference to the parent matrix instance.
long[]	subMatrixTo()	If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), creates and returns a new Java array containing the ending position (exclusive) of this submatrix in the parent one.
Matrix<T>	tile()	Returns a tiled view ot this matrix with some default dimensions of the tiles.
Matrix<T>	tile(long... tileDim)	Returns a view ot this matrix, where the elements are reordered by tiles: a grid of rectangular regions (tiles), the sizes of which are specified by tileDim argument.
long[]	tileDimensions()	If this matrix is a tiled view of some parent matrix, created by a call parent.tile(...), creates and returns a new Java array containing the tile dimensions, used while creating this tiled view (argument of Matrix.tile(long...) method).
Matrix<T>	tileParent()	If this matrix is a tiled view of some parent matrix, created by a call parent.tile(...), returns a reference to the parent matrix instance.
String	toString()	Returns a brief string description of this object.
Class<? extends Array>	type()	Returns Matrix.array().type().
<U extends Array> Class<? extends U>	type(Class<U> arraySupertype)	Returns Matrix.array().type(), if it is subtype of (or same type as) the passed arraySupertype, or throws ClassCastException in other case.
long	uncheckedIndex(long... coordinates)	An analog of Matrix.index(long...) method, that does not check, whether the passed coordinates are in the required ranges.
Class<? extends UpdatableArray>	updatableType()	Returns Matrix.array().updatableType().
<U extends Array> Class<? extends U>	updatableType(Class<U> arraySupertype)	Returns Matrix.array().updatableType(), if it is subtype of (or same type as) the passed arraySupertype, or throws ClassCastException in other case.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.algart.arrays.Matrix

asLayers, size, size32

Constructor Details

AbstractMatrix

public AbstractMatrix()

Method Details

array

public abstract T array()

Description copied from interface: Matrix

Returns a reference to the built-in AlgART array.

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

Specified by:

array in interface Matrix<T extends Array>

Returns:

a reference to the built-in AlgART array.

elementType

public Class<?> elementType()

Description copied from interface: Matrix

Returns the type of matrix elements. Equivalent to Matrix.array().elementType().

Specified by:

elementType in interface Matrix<T extends Array>

Returns:

the type of the matrix elements.

type

public Class<? extends Array> type()

Description copied from interface: Matrix

Returns Matrix.array().type().

Specified by:

type in interface Matrix<T extends Array>

Returns:

the canonical type of AlgART array of the same kind as the built-in one.

updatableType

public Class<? extends UpdatableArray> updatableType()

Description copied from interface: Matrix

Returns Matrix.array().updatableType().

Specified by:

updatableType in interface Matrix<T extends Array>

Returns:

the canonical updatable type of AlgART array of the same kind as the built-in one.

type

public <U extends Array> Class<? extends U> type(Class<U> arraySupertype)

Description copied from interface: Matrix

Returns Matrix.array().type(), if it is subtype of (or same type as) the passed arraySupertype, or throws ClassCastException in other case. (If the passed argument is a class of UpdatableArray or some its subinterfaces or subclasses, IllegalArgumentException is thrown instead: updatable array classes cannot be specified in this method.)

Specified by:

type in interface Matrix<T extends Array>

Parameters:

arraySupertype - the required supertype of the built-in AlgART array.

Returns:

the canonical type of AlgART array of the same kind as the built-in one.

updatableType

public <U extends Array> Class<? extends U> updatableType(Class<U> arraySupertype)

Description copied from interface: Matrix

Returns Matrix.array().updatableType(), if it is subtype of (or same type as) the passed arraySupertype, or throws ClassCastException in other case.

Specified by:

updatableType in interface Matrix<T extends Array>

Parameters:

arraySupertype - the required supertype of the built-in AlgART array.

Returns:

the canonical updatable type of AlgART array of the same kind as the built-in one.

isPrimitive

public boolean isPrimitive()

Description copied from interface: Matrix

Returns true if and only if the element type is primitive: Matrix.array() instanceof PArray.

Specified by:

isPrimitive in interface Matrix<T extends Array>

Returns:

whether the type of matrix element is boolean, char, byte, short, int, long, float or double.

isFloatingPoint

public boolean isFloatingPoint()

Description copied from interface: Matrix

Returns true if and only if the element type is float or double: Matrix.array() instanceof PFloatingArray.

Specified by:

isFloatingPoint in interface Matrix<T extends Array>

Returns:

whether the type of matrix element is float or double.

isFixedPoint

public boolean isFixedPoint()

Description copied from interface: Matrix

Returns true if and only if the element type is fixed-point: Matrix.array() instanceof PFixedArray.

Specified by:

isFixedPoint in interface Matrix<T extends Array>

Returns:

whether the type of matrix element is byte, short, int, long, char or boolean.

isUnsigned

public boolean isUnsigned()

Description copied from interface: Matrix

Returns true if and only if the element type is boolean.class, short.class, byte.class or short.class.

Equivalent to Arrays.isUnsignedElementType(thisMatrix.elementType()).

Specified by:

isUnsigned in interface Matrix<T extends Array>

Returns:

whether the element type of this matrix should be interpreted as unsigned primitive type.

bitsPerElement

public long bitsPerElement()

Description copied from interface: Matrix

Returns the number of in bits, required for each element of this matrix, if they are primitive; in other case returns −1. Equivalent to Arrays.bitsPerElement(thisMatrix.elementType()).

Specified by:

bitsPerElement in interface Matrix<T extends Array>

Returns:

the size of each element in bits or −1 if for non-primitive elements.

maxPossibleValue

public double maxPossibleValue(double valueForFloatingPoint)

Description copied from interface: Matrix

Returns the maximal possible value, that can stored in elements of this matrix, if they are fixed-point elements, or the argument for floating-point elements, or Double.NaN if elements are not primitive.

Equivalent to

     thisMatrix.isPrimitive() ?
         ((PArray) thisMatrix.array()).maxPossibleValue(valueForFloatingPoint) :
         Double.NaN;
 

Specified by:

maxPossibleValue in interface Matrix<T extends Array>

Parameters:

valueForFloatingPoint - some "default" value returned for floating-point element type.

Returns:

Matrix.array().maxPossibleValue() for primitive element types, or Double.NaN for non-primitive element types.

maxPossibleValue

public double maxPossibleValue()

Description copied from interface: Matrix

Returns the maximal possible value, that can stored in elements of this matrix, if they are fixed-point elements, or 1.0 for floating-point elements, or Double.NaN if elements are not primitive.

Equivalent to maxPossibleValue(1.0). It is a good default for most application.

Specified by:

maxPossibleValue in interface Matrix<T extends Array>

Returns:

maximal possible value for primitive element types (1.0 for float/double), or Double.NaN for non-primitive element types.

dimensions

public abstract long[] dimensions()

Description copied from interface: Matrix

Returns an array containing all dimensions of this matrix. Returned array is equal to the dim argument passed to methods that create new matrix instances.

The returned array is a clone of the internal dimension array, stored in this object. The returned array is never empty (its length cannot be zero). The elements of the returned array are never negative.

Specified by:

dimensions in interface Matrix<T extends Array>

Returns:

an array containing all dimensions of this matrix.

dimCount

public abstract int dimCount()

Description copied from interface: Matrix

Returns the number of dimensions of this matrix. This value is always positive (>=1). Equivalent to Matrix.dimensions().length, but works faster.

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

Specified by:

dimCount in interface Matrix<T extends Array>

Returns:

the number of dimensions of this matrix.

dim

public abstract long dim(int n)

Description copied from interface: Matrix

Returns the dimension #n of this matrix or 1 if n>=Matrix.dimCount(). Equivalent to n<Matrix.dimCount()?Matrix.dimensions()[n]:1, but works faster.

There is a guarantee that this method works very quickly.

Specified by:

dim in interface Matrix<T extends Array>

Parameters:

n - the index of dimension.

Returns:

the dimension #n of this matrix.

dimX

public long dimX()

Description copied from interface: Matrix

Equivalent to dim(0).

Specified by:

dimX in interface Matrix<T extends Array>

Returns:

the first matrix dimension.

dimY

public long dimY()

Description copied from interface: Matrix

Equivalent to dim(1).

Specified by:

dimY in interface Matrix<T extends Array>

Returns:

the second matrix dimension.

dimZ

public long dimZ()

Description copied from interface: Matrix

Equivalent to dim(2).

Specified by:

dimZ in interface Matrix<T extends Array>

Returns:

the third matrix dimension.

dimEquals

public boolean dimEquals(Matrix<?> m)

Description copied from interface: Matrix

Indicates whether the other matrix has the same dimension array. In other words, returns true if and only if both matrices have the same dimension count (Matrix.dimCount()) and the corresponding dimensions (dim(k)) are equal.

Specified by:

dimEquals in interface Matrix<T extends Array>

Parameters:

m - the matrix to be compared for equal dimensions with this matrix.

Returns:

true if the specified matrix has the same dimension array.

See Also:

• Matrix.dimEquals(long...)

dimEquals

public boolean dimEquals(long... dimensions)

Description copied from interface: Matrix

Indicates whether the passed dimensions are equal to the dimension array of this matrix. In other words, returns true if and only if dimension.length==Matrix.dimCount() and the corresponding dimensions dim(k)==dimension[k] for all k.

Note: this method does not check, whether all passed dimensions are correct (in particular, non-negative). If some elements of the passed array are incorrect, this method just returns false. But it the passed array is null, this method throws NullPointerException.

Specified by:

dimEquals in interface Matrix<T extends Array>

Parameters:

dimensions - the dimension array.

Returns:

true if the specified dimensions are equal to the dimensions of this matrix.

See Also:

• Matrix.dimEquals(Matrix)

index

public long index(long... coordinates)

Description copied from interface: Matrix

Returns the linear index in the built-in AlgART array of the matrix element with specified coordinates.

More precisely, index(i₀,i₁,...,i_n-1) returns the following value:

i_n-1d_n-2...d₁d₀ + ... + i₂d₁d₀ + i₁d₀ + i₀,

where d_k=dim(k). All passed indexes i_k must be in ranges 0..d_k-1.

All elements of coordinates array are always used, regardless of the number of matrix dimensions. But the extra elements of coordinates array must be zero, because d_k=1 for k>=Matrix.dimCount().

Good algorithms processing the matrix should use this method rarely: usually there are more optimal ways to calculate necessary linear index. For example, if you just need to calculate something for all matrix elements, the best way is the following:

 Array a = m.array();
 for (long disp = 0, n = a.length(); disp < n; disp++)
     // process the element #k of the array
 

Specified by:

index in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

the linear index of the matrix element with specified coordinates.

See Also:

• Matrix.uncheckedIndex(long...)
• Matrix.cyclicIndex(long...)
• Matrix.pseudoCyclicIndex(long...)
• Matrix.mirrorCyclicIndex(long...)
• Matrix.coordinates(long, long[])
• IPoint.toOneDimensional(long[], boolean)

index

public long index(long x,
 long y)

Description copied from interface: Matrix

The simplified version of the full index method for the case of 2-dimensional matrix.

Specified by:

index in interface Matrix<T extends Array>

Parameters:

x - the first coordinate.

y - the second coordinate.

Returns:

y * Matrix.dimX() + x.

index

public long index(long x,
 long y,
 long z)

Description copied from interface: Matrix

The simplified version of the full index method for the case of 3-dimensional matrix.

Specified by:

index in interface Matrix<T extends Array>

Parameters:

x - the first coordinate.

y - the second coordinate.

z - the third coordinate.

Returns:

z * Matrix.dimY() * Matrix.dimX() + y * Matrix.dimX() + x.

coordinates

public long[] coordinates(long index,
 long[] result)

Description copied from interface: Matrix

Returns the coordinates in the matrix, corresponding to the given linear index in the built-in AlgART array. This method is reverse to Matrix.index(long...): for any index, index(coordinates(index, null)) == index.

The result argument may be null or some array, containing at least Matrix.dimCount() elements. If the first case, this method allocates new Java array long[Matrix.dimCount()] for storing coordinates and returns it. In the second case, this method stores the found coordinates in result array and returns it. The returned coordinates are always in ranges

 0 ≤ result[k] < dim(k)

Specified by:

coordinates in interface Matrix<T extends Array>

Parameters:

index - the linear index in the built-in AlgART array.

result - the array where you want to store results; may be null.

Returns:

a reference to the result argument, if it is not null, else newly created Java array contains all calculated coordinates.

uncheckedIndex

public long uncheckedIndex(long... coordinates)

Description copied from interface: Matrix

An analog of Matrix.index(long...) method, that does not check, whether the passed coordinates are in the required ranges.

More precisely, uncheckedIndex(i₀,i₁,...,i_n-1) always returns the following value:

i_n-1d_n-2...d₁d₀ + ... + i₂d₁d₀ + i₁d₀ + i₀,

where d_k=dim(k).

All calculations are performed with long type without any overflow checks. All elements of coordinates array are always used, regardless of the number of matrix dimensions. Please remember that d_k=dim(k)=1 for k>=Matrix.dimCount() (extra elements of coordinates array)..

Specified by:

uncheckedIndex in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

the linear index of the matrix element with specified coordinates, without range checks.

cyclicIndex

public long cyclicIndex(long... coordinates)

Description copied from interface: Matrix

An analog of Matrix.index(long...) method, that, before all calculations, replaces the passed coordinates with the positive remainders from division of them by the corresponding matrix dimensions.

More precisely, let i₀,i₁,...,i_n-1 are the arguments of the method. Let d_k=dim(k) and

i'_k = d_k == 0 ? 0 : i_k % d_k >= 0 ? i_k % d_k : i_k % d_k + d_k

This method returns the following value:

i'_n-1d_n-2...d₁d₀ + ... + i'₂d₁d₀ + i'₁d₀ + i'₀,

In other words, the resulting index is "cyclical".

All elements of coordinates array are always used, regardless of the number of matrix dimensions. (You can note that extra elements of coordinates array are ignored in fact: the reminders i_k%d_k=i_k%1 will be zero for them.)

Specified by:

cyclicIndex in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

the cyclical linear index of the matrix element with specified coordinates, without range checks.

See Also:

• Matrix.ContinuationMode.CYCLIC

pseudoCyclicIndex

public long pseudoCyclicIndex(long... coordinates)

Description copied from interface: Matrix

An analog of Matrix.index(long...) method, that does not check, whether the passed coordinates are in the required ranges, but replaces the resulting index with the positive remainder from division of it by the length of the built-in array.

More precisely, let i₀,i₁,...,i_n-1 are the arguments of the method, and index is the following value (as in Matrix.index(long...) method):

index = i_n-1d_n-2...d₁d₀ + ... + i₂d₁d₀ + i₁d₀ + i₀,

where d_k=dim(k). Here we do no require that the passed indexes i_k are in ranges 0..d_k-1. Then, let len=Matrix.array().length()=d_n-1...d₁d₀. The result of this method is the following:

len == 0 ? 0 : index % len >= 0 ? index % len : index % len + len

(It is in the 0..len-1 range always, excepting the generated case len==0.) In other words, the resulting index is "pseudo-cyclical", as the resulting shift in Matrices.asShifted(Matrix, long...) method.

All elements of coordinates array are always used, regardless of the number of matrix dimensions. (You can note that extra elements of coordinates array are ignored in fact: they add k*len summand, where k is an integer.)

Note that all calculations are performed absolutely precisely, even in a case when the direct calculation according the formulas above leads to overflow (because some of values in these formulas are out of Long.MIN_VALUE..Long.MAX_VALUE range).

Specified by:

pseudoCyclicIndex in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

the pseudo-cyclical linear index of the matrix element with specified coordinates, without range checks.

See Also:

• IPoint.toOneDimensional(long[], boolean)
• Matrix.ContinuationMode.PSEUDO_CYCLIC

mirrorCyclicIndex

public long mirrorCyclicIndex(long... coordinates)

Description copied from interface: Matrix

An analog of Matrix.index(long...) method, that, before all calculations, replaces the passed coordinates with the positive remainders from division of them by the corresponding matrix dimensions or with complement of these remainders on the dimensions, as if the matrix would be reflected in each its bound as in a mirror.

More precisely, let i₀,i₁,...,i_n-1 are the arguments of the method. Let d_k=dim(k),

i'_k = d_k == 0 ? 0 : i_k % d_k >= 0 ? i_k % d_k : i_k % d_k + d_k

(as in Matrix.cyclicIndex(long...) and

i''_k = d_k == 0 ? 0 : ⌊i_k / d_k⌋ % 2 == 0 ? i'_k : d_k − 1 − i'_k

(here ⌊x⌋ means the integer part of x, i.e. Math.floor(x)).

This method returns the following value:

i''_n-1d_n-2...d₁d₀ + ... + i''₂d₁d₀ + i''₁d₀ + i''₀,

In other words, the resulting index is "mirroring-cyclical".

All elements of coordinates array are always used, regardless of the number of matrix dimensions. (You can note that extra elements of coordinates array are ignored in fact: the reminders i_k%d_k=i_k%1 will be zero for them.)

Specified by:

mirrorCyclicIndex in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

the mirror-cyclical linear index of the matrix element with specified coordinates, without range checks.

See Also:

• Matrix.ContinuationMode.MIRROR_CYCLIC

inside

public boolean inside(long... coordinates)

Description copied from interface: Matrix

Returns true if all specified coordinates i_k are inside the ranges 0..d_k-1, where d_k=dim(k).

This method allows simply check that the arguments of the index method are correct and will not lead to IndexOutOfBoundsException:

 if (matrix.inside(i1, i2, ...)) {
     long index = matrix.index(i1, i2, ...);
     // processing an element at this index
 } else {
     // special branch for positions outside the matrix
 }
 

Specified by:

inside in interface Matrix<T extends Array>

Parameters:

coordinates - all coordinates.

Returns:

true if all specified coordinates are inside the matrix.

inside

public boolean inside(long x,
 long y)

Description copied from interface: Matrix

The simplified version of the full inside method for the case of 2-dimensional matrix.

Specified by:

inside in interface Matrix<T extends Array>

Parameters:

x - the first coordinate.

y - the second coordinate.

Returns:

tt>true if all specified coordinates are inside the matrix.

inside

public boolean inside(long x,
 long y,
 long z)

Description copied from interface: Matrix

The simplified version of the full inside method for the case of 3-dimensional matrix.

Specified by:

inside in interface Matrix<T extends Array>

Parameters:

x - the first coordinate.

y - the second coordinate.

z - the third coordinate.

Returns:

tt>true if all specified coordinates are inside the matrix.

matrix

public abstract <U extends Array> Matrix<U> matrix(U anotherArray)

Description copied from interface: Matrix

Returns the new matrix backed by the specified AlgART array with the same dimensions as this one. Equivalent to Matrices.matrix(anotherArray, Matrix.dimensions()).

The array anotherArray must be unresizable, and its length must be equal to the length of the array built-in this matrix.

Specified by:

matrix in interface Matrix<T extends Array>

Parameters:

anotherArray - some another AlgART array with the same length as Matrix.array().

Returns:

new matrix instance.

cast

public <U extends Array> Matrix<U> cast(Class<U> arrayClass)

Description copied from interface: Matrix

Returns this matrix, cast to the specified generic array type, or throws ClassCastException if the built-in AlgART array cannot be cast to the required type (because the array type is not its subclass). Works alike matrix((U)array), but returns the reference to this instance and is compiled without "unchecked cast" warning.

This method is useful when you need to cast the type of AlgART array, built in this matrix, to to its sub- or superinterface.

Specified by:

cast in interface Matrix<T extends Array>

Parameters:

arrayClass - the type of built-in array in the new matrix.

Returns:

new matrix with the same dimensions, based on the same array cast to the required type.

subMatrix

public Matrix<T> subMatrix(long[] from,
 long[] to)

Description copied from interface: Matrix

Returns a view of the rectangular fragment of this matrix between from, inclusive, and to, exclusive.

More precisely, the returned matrix consists of all elements of this one with coordinates i₀, i₁, ..., i_n−1, n=Matrix.dimCount(), matching the following conditions:

     from[0] <= i0 < to[0],
     from[1] <= i1 < to[1],
     . . .
     from[n-1] <= in-1 < to[n-1]
 

So, every dimension dim(k) in the returned matrix will be equal to to[k]-from[k]. The following condition must be fulfilled for all k: 0<=from[k]<=to[k]<=thisMatrix.dim(k). The element type of the returned matrix is identical to the element type of this matrix.

This method is equivalent to the call subMatrix(from,to,Matrix.ContinuationMode.NONE).

The built-in AlgART array of the returned matrix is backed by the built-in array of this matrix, so — if this matrix is not immutable — any changes of the elements of the returned matrix are reflected in this matrix, and vice-versa. The returned matrix is immutable if, and only if, the built-in array of this matrix does not implement UpdatableArray. The Array.asTrustedImmutable() method in the built-in array of the returned matrix is equivalent to Array.asImmutable(), and Array.asCopyOnNextWrite() method just returns the full copy of the array.

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

from - low endpoints (inclusive) of all coordinates.

to - high endpoints (exclusive) of all coordinates.

Returns:

a view of the specified rectangular fragment within this matrix.

See Also:

• Matrix.subMatrix(long[], long[], ContinuationMode)
• Matrix.subMatrix(IRectangularArea)
• Matrix.subMatr(long[], long[], ContinuationMode)
• Matrix.subMatr(long[], long[])
• Matrix.isSubMatrix()

subMatrix

public Matrix<T> subMatrix(IRectangularArea area)

Description copied from interface: Matrix

Equivalent to Matrix.subMatrix(long[] from, long[] to) method, where from.length=to.length=area.coordCount(), from[k]=area.min(k), to[k]=area.max(k)+1.

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

area - rectangular area within this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatrix

public Matrix<T> subMatrix(long fromX,
 long fromY,
 long toX,
 long toY)

Description copied from interface: Matrix

Equivalent to subMatrix(new long[]{fromX,fromY}, new long[]{toX,toY}). Note that this matrix must be 2-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

fromX - low endpoints (inclusive) of the first coordinate.

fromY - low endpoints (inclusive) of the second coordinate.

toX - high endpoints (exclusive) of the first coordinate.

toY - high endpoints (exclusive) of the second coordinate.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatrix

public Matrix<T> subMatrix(long fromX,
 long fromY,
 long fromZ,
 long toX,
 long toY,
 long toZ)

Description copied from interface: Matrix

Equivalent to subMatrix(new long[]{fromX,fromY,fromZ}, new long[]{toX,toY,toZ}). Note that this matrix must be 3-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

fromX - low endpoints (inclusive) of the first coordinate.

fromY - low endpoints (inclusive) of the second coordinate.

fromZ - low endpoints (inclusive) of the third coordinate.

toX - high endpoints (exclusive) of the first coordinate.

toY - high endpoints (exclusive) of the second coordinate.

toZ - high endpoints (exclusive) of the third coordinate.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatrix

public Matrix<T> subMatrix(long[] from,
 long[] to,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

An extended analog of Matrix.subMatrix(long[], long[]) method, allowing to get a rectangular fragment which is not fully inside this matrix.

More precisely, unlike Matrix.subMatrix(long[], long[]), here the only requirement for the from and to coordinate boundaries is from[k]<=to[k], but from[k] may be negative and to[k] may be greater than dim(k). (And there is also a trivial obvious requirement to[k]-from[k]≤Long.MAX_VALUE, i.e. that the dimensions of the result must be representable by long type.)

The elements of the returned matrix, that do not correspond to any elements of this one, i.e. "lie outside" of the source matrix, are considered to be equal to some values, according to some continuation model, described by continuationMode argument. Such "outside" elements can correspond (according some rules) to actual elements of the source elements — then attempts to read them return the values of the corresponding source elements and attempts to write into them modify the corresponding source elements (it is so for Matrix.ContinuationMode.CYCLIC, Matrix.ContinuationMode.PSEUDO_CYCLIC, Matrix.ContinuationMode.MIRROR_CYCLIC modes), — or can be calculated "virtually" (according some rules) — then attempts to read them return the calculated values and attempts to modify them are ignored (it is so for the constant continuation mode). See Matrix.ContinuationMode class for more details.

Important note: there are two cases, when requirements to the from and to coordinate boundaries are more strong, than described above.

1. If continuationMode==Matrix.ContinuationMode.NONE, this method is strictly equivalent to more simple Matrix.subMatrix(long[], long[]) method, so all requirements are the same as for that method.
2. If continuationMode is Matrix.ContinuationMode.CYCLIC, Matrix.ContinuationMode.PSEUDO_CYCLIC or Matrix.ContinuationMode.MIRROR_CYCLIC (but it is not a constant continuation mode) and some dimension #k of this matrix is zero — dim(k)==0 — then both corresponding coordinate boundaries from[k] and to[k] must be zero (as in Matrix.subMatrix(long[], long[]) method).

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

from - low endpoints (inclusive) of all coordinates.

to - high endpoints (exclusive) of all coordinates.

continuationMode - the mode of continuation outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

See Also:

• Matrix.subMatr(long[], long[], ContinuationMode)
• Matrix.subMatrix(long[], long[])
• Matrix.subMatr(long[], long[])
• Matrix.isSubMatrix()

subMatrix

public Matrix<T> subMatrix(IRectangularArea area,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to Matrix.subMatrix(long[] from, long[] to, ContinuationMode continuationMode) method, where from.length=to.length=area.coordCount(), from[k]=area.min(k), to[k]=area.max(k)+1.

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

area - rectangular area within this matrix.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatrix

public Matrix<T> subMatrix(long fromX,
 long fromY,
 long toX,
 long toY,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to subMatrix(new long[]{fromX,fromY}, new long[]{toX,toY}, continuationMode). Note that this matrix must be 2-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

fromX - low endpoints (inclusive) of the first coordinate.

fromY - low endpoints (inclusive) of the second coordinate.

toX - high endpoints (exclusive) of the first coordinate.

toY - high endpoints (exclusive) of the second coordinate.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatrix

public Matrix<T> subMatrix(long fromX,
 long fromY,
 long fromZ,
 long toX,
 long toY,
 long toZ,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to subMatrix(new long[]{fromX,fromY,fromZ}, new long[]{toX,toY,toZ}, continuationMode). Note that this matrix must be 3-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatrix in interface Matrix<T extends Array>

Parameters:

fromX - low endpoints (inclusive) of the first coordinate.

fromY - low endpoints (inclusive) of the second coordinate.

fromZ - low endpoints (inclusive) of the third coordinate.

toX - high endpoints (exclusive) of the first coordinate.

toY - high endpoints (exclusive) of the second coordinate.

toZ - high endpoints (exclusive) of the third coordinate.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatr

public Matrix<T> subMatr(long[] position,
 long[] dimensions)

Description copied from interface: Matrix

Equivalent to Matrix.subMatrix(long[] from, long[] to) method, where from[k]=position[k] and to[k]=position[k]+dimensions[k] for all k.

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

position - low endpoints (inclusive) of all coordinates.

dimensions - dimensions of the returned submatrix.

Returns:

a view of the specified rectangular fragment within this matrix.

See Also:

• Matrix.subMatr(long[], long[], ContinuationMode)

subMatr

public Matrix<T> subMatr(long x,
 long y,
 long dimX,
 long dimY)

Description copied from interface: Matrix

Equivalent to subMatr(new long[]{x,y}, new long[]{dimX,dimY}). Note that this matrix must be 2-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

x - low endpoint (inclusive) of the first coordinate.

y - low endpoint (inclusive) of the second coordinate.

dimX - th first dimension of the returned submatrix.

dimY - the second dimension of the returned submatrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatr

public Matrix<T> subMatr(long x,
 long y,
 long z,
 long dimX,
 long dimY,
 long dimZ)

Description copied from interface: Matrix

Equivalent to subMatr(new long[]{x,y,z}, new long[]{dimX,dimY,dimZ}). Note that this matrix must be 3-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

x - low endpoint (inclusive) of the first coordinate.

y - low endpoint (inclusive) of the second coordinate.

z - low endpoint (inclusive) of the third coordinate.

dimX - th first dimension of the returned submatrix.

dimY - the second dimension of the returned submatrix.

dimZ - the third dimension of the returned submatrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatr

public Matrix<T> subMatr(long[] position,
 long[] dimensions,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to Matrix.subMatrix(long[] from, long[] to, ContinuationMode continuationMode) method, where from[k]=position[k] and to[k]=position[k]+dimensions[k] for all k.

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

position - low endpoints (inclusive) of all coordinates.

dimensions - dimensions of the returned submatrix.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

See Also:

• Matrix.subMatr(long[], long[])

subMatr

public Matrix<T> subMatr(long x,
 long y,
 long dimX,
 long dimY,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to subMatr(new long[]{x,y}, new long[]{dimX,dimY}, continuationMode). Note that this matrix must be 2-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

x - low endpoint (inclusive) of the first coordinate.

y - low endpoint (inclusive) of the second coordinate.

dimX - th first dimension of the returned submatrix.

dimY - the second dimension of the returned submatrix.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

subMatr

public Matrix<T> subMatr(long x,
 long y,
 long z,
 long dimX,
 long dimY,
 long dimZ,
 Matrix.ContinuationMode continuationMode)

Description copied from interface: Matrix

Equivalent to subMatr(new long[]{x,y,z}, new long[]{dimX,dimY,dimZ}, continuationMode). Note that this matrix must be 3-dimensional (in other case IllegalArgumentException will be thrown).

Specified by:

subMatr in interface Matrix<T extends Array>

Parameters:

x - low endpoint (inclusive) of the first coordinate.

y - low endpoint (inclusive) of the second coordinate.

z - low endpoint (inclusive) of the third coordinate.

dimX - th first dimension of the returned submatrix.

dimY - the second dimension of the returned submatrix.

dimZ - the third dimension of the returned submatrix.

continuationMode - the value returned while reading elements, lying outside this matrix.

Returns:

a view of the specified rectangular fragment within this matrix.

isSubMatrix

public boolean isSubMatrix()

Description copied from interface: Matrix

Returns true if and only if this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...), parent.subMatr(...) or equivalent. The Matrix.subMatrixParent() method throws NotSubMatrixException if and only if this method returns false.

Specified by:

isSubMatrix in interface Matrix<T extends Array>

Returns:

whether this object is created by subMatrix(...), subMatr(...) or equivalent call.

See Also:

• Matrix.subMatrix(long[], long[])
• Matrix.subMatrix(long[], long[], ContinuationMode)
• Matrix.subMatr(long[], long[])
• Matrix.subMatr(long[], long[], ContinuationMode)
• Matrix.subMatrixParent()

subMatrixParent

public Matrix<T> subMatrixParent()

Description copied from interface: Matrix

If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), returns a reference to the parent matrix instance. If this matrix is not a submatrix, throws NotSubMatrixException.

Specified by:

subMatrixParent in interface Matrix<T extends Array>

Returns:

a reference to the parent matrix, if this instance is a submatrix.

See Also:

• Matrix.isSubMatrix()

subMatrixFrom

public long[] subMatrixFrom()

Description copied from interface: Matrix

If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), creates and returns a new Java array containing the starting position of this submatrix in the parent one. The result will be equal to "from" argument of Matrix.subMatrix(long[], long[]) and Matrix.subMatrix(long[], long[], ContinuationMode) methods. If this matrix is not a submatrix, throws NotSubMatrixException.

Specified by:

subMatrixFrom in interface Matrix<T extends Array>

Returns:

low endpoints (inclusive) of all coordinates of this submatrix in its parent matrix.

See Also:

• Matrix.isSubMatrix()

subMatrixTo

public long[] subMatrixTo()

Description copied from interface: Matrix

If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), creates and returns a new Java array containing the ending position (exclusive) of this submatrix in the parent one. The result will be equal to "to" argument of Matrix.subMatrix(long[], long[]) and Matrix.subMatrix(long[], long[], ContinuationMode) methods. If this matrix is not a submatrix, throws NotSubMatrixException.

Specified by:

subMatrixTo in interface Matrix<T extends Array>

Returns:

low endpoints (inclusive) of all coordinates of this submatrix in its parent matrix.

See Also:

• Matrix.isSubMatrix()

subMatrixContinuationMode

public Matrix.ContinuationMode subMatrixContinuationMode()

Description copied from interface: Matrix

If this matrix is a submatrix of some parent matrix, created by one of calls parent.subMatrix(...) or parent.subMatr(...), returns the continuation mode, used by this submatrix. If this matrix is not a submatrix, throws NotSubMatrixException.

If the submatrix was created by Matrix.subMatrix(long[], long[], net.algart.arrays.Matrix.ContinuationMode) or equivalent method, the continuationMode argument, passed to that method, is returned. If the submatrix was created by Matrix.subMatrix(long[], long[]) or equivalent method, Matrix.ContinuationMode.NONE constant is returned.

Specified by:

subMatrixContinuationMode in interface Matrix<T extends Array>

Returns:

low endpoints (inclusive) of all coordinates of this submatrix in its parent matrix.

See Also:

• Matrix.isSubMatrix()

structureLike

public Matrix<T> structureLike(Matrix<?> m)

Description copied from interface: Matrix

Returns a view ot this matrix, where the elements are reordered in some order "like" in the specified matrix m. In other words, the elements of the built-in array of the returned matrix are the same as the elements of the built-in array of this one (any changes of the elements of the returned matrix are reflected in this matrix, and vice-versa), but the order of the elements can differ. The precise algorithm of reordering is not specified and depends of the matrix m: this method tries to help algorithms, processing the same or similar areas in both matrices, to provide maximal performance.

This method returns non-trivial results only if the matrix m is already a view of some other matrix with some form of reordering elements, for example, if m is a tiled matrix. In other case, this method just returns this instance.

In the current version of this package (if this instance was created by means of methods of this package), this method is equivalent to the following:

 m.Matrix.isTiled() ?
     thisInstance.tile(m.Matrix.tileDimensions()) :
     thisInstance;
 

In future versions, it is possible that this method will recognize other forms of reordering matrix elements and return non-trivial results for such m matrices.

Because the precise order of elements of the returning matrix is not specified, we recommend to use this method generally for newly created matrices, for example:

 memoryModel.newMatrix(UpdatablePArray.class, m).structureLike(m);
 

or, more briefly,

 memoryModel.newStructuredMatrix(UpdatablePArray.class, m);
 

Specified by:

structureLike in interface Matrix<T extends Array>

Parameters:

m - some matrix, probably a view of another matrix with reordered elements (for example, tiled).

Returns:

a view of this matrix with elements reordered in similar order, or a reference to this instance if m matrix is not reodered or this method does not "know" about the way of that reordering.

See Also:

• Matrix.isStructuredLike(Matrix)

isStructuredLike

public boolean isStructuredLike(Matrix<?> m)

Description copied from interface: Matrix

Returns true if the elements of this matrix is ordered "alike" the elements of the specified matrix m, in terms of Matrix.structureLike(Matrix) method. "Ordered alike" does not mean that the dimensions of both matrices are equal, or that the details of the structure are the same; it means only that both matrices use similar reordering algorithms.

More precisely, Matrix.structureLike(Matrix) method returns this instance if and only if this method returns true.

In the current version of this package (if this instance was created by means of methods of this package), this method is equivalent to: thisInstance.Matrix.isTiled()==m.Matrix.isTiled().

Specified by:

isStructuredLike in interface Matrix<T extends Array>

Parameters:

m - some matrix, probably a view of another matrix with reordered elements (for example, tiled).

Returns:

whether this matrix is reordered alike m.

tile

public Matrix<T> tile(long... tileDim)

Description copied from interface: Matrix

Returns a view ot this matrix, where the elements are reordered by tiles: a grid of rectangular regions (tiles), the sizes of which are specified by tileDim argument. It means that the elements of the built-in AlgART array of the returned matrix are the elements of the built-in array of this one, but "shuffled" so that all elements of every tile in the returned matrix are located in a continuous block of the built-in array of this matrix. The returned matrix is named tiled matrix. The dimensions of the returned matrix are the same as the dimensions of this one. The element type of the returned matrix is identical to the element type of this matrix.

More precisely, let this matrix be M and the tiled matrix, returned by this method, be T. Let i₀, i₁, ..., i_n−1 (n=Matrix.dimCount()) be coordinates of some element it the tiled matrix T, that is located in T.array() at the index i=T.index(i₀,i₁,...,i_n−1). This element is located in the original array M.array() at another index j, which is calculated by the following algorithm.

1. Let d_k = M.dim(k), k=0,1,...,n−1: dimensions of this and returned matrix.
2. Let i'_k = i_k%tileDim[k], k=0,1,...,n−1: i'_k are the coordinates of this element inside the tile, containing it in T matrix.
3. Let s_k = i_k−i'_k, k=0,1,...,n−1: s_k are the coordinates of the starting element of the tile, containing this element in T matrix.
4. Let t_k = min(tileDim[k], d_k−s_k), k=0,1,...,n−1: t_k are the dimensions of the tile, containing this element in T matrix. (Note that boundary tiles can be less than tileDim, if dimensions of matrix are not divisible by corresponding dimensions of tiles.)
5. Let previousVolume = d₀d₁...d_n−3d_n−2s_n−1 + d₀d₁...d_n−3c_n−2t_n−1 + ... + s₀t₁...t_n−2t_n−1. This complex formula returns the summary sizes of all tiles, that are fully located in the source T.array() before the given element. In 2-dimensional case, the formula is more simple: previousVolume = d_xs_y + s_xt_y.
6. Let indexInTile = i'₀ + i'₁t₀ + ... + i'_n−1t_n−2...t₀: it is the index of the element with coordinates i'₀,i'₁,...,i'_n−1 in the built-in array of a little matrix, dimensions of which are equal to the tile dimensions.
7. The required index of the given element in the original array M.array() is j = previousVolume + indexInTile.

Tiled matrices are necessary to provide good performance of many algorithms, if this matrix is very large (much greater than amount of RAM) and is located on disk or other external devices. For example, extracting a rectangular area 1000x1000 from a byte matrix 1000000x1000000 (1 terabyte) will probably work much faster if it is tiled, than if it is a usual matrix, where every line occupies 1 MB of continuous disk space.

In the degenerated case of 1-dimensional matrix (Matrix.dimCount()=1) the tiled matrix is absolutely useless, though still works correctly.

Recommended tile dimensions are from several hundreds to several thousands, but it depends on the number of dimensions. If tile dimensions are degrees of two (2^k), the tiled matrix will probably work faster.

The built-in AlgART array of the returned matrix is backed by the built-in array of this matrix, so — if this matrix is not immutable — any changes of the elements of the returned matrix are reflected in this matrix, and vice-versa. The returned matrix is immutable if, and only if, the built-in array of this matrix does not implement UpdatableArray. The Array.asTrustedImmutable() method in the built-in array of the returned matrix is equivalent to Array.asImmutable(), and Array.asCopyOnNextWrite() method just returns the full copy of the array.

Specified by:

tile in interface Matrix<T extends Array>

Parameters:

tileDim - dimensions of the tiles in the returned matrix (excepting the boundary tiles, which can be less).

Returns:

a tiled view of this matrix.

See Also:

• Matrix.tile()
• Matrix.isTiled()
• Matrix.tileDimensions()

tile

public Matrix<T> tile()

Description copied from interface: Matrix

Returns a tiled view ot this matrix with some default dimensions of the tiles. Equivalent to tile(tileDim), where all elements of tileDim are equal to the default integer value, retrieved from the system property "net.algart.arrays.matrixTile2D", "net.algart.arrays.matrixTile3D" "net.algart.arrays.matrixTile4D" "net.algart.arrays.matrixTile5D" or "net.algart.arrays.matrixTileND", if the number of dimensions of this matrix is correspondingly 2, 3, 4, 5 or greater. If there is no such property, or if it contains not a number, or if some exception occurred while calling Long.getLong, this method uses the following tile dimensions: 4096x4096 in 2-dimensional case, 256x256x256 in 3-dimensional case, 64x64x64x64 in 4-dimensional case, 32x32x32x32x32 in 5-dimensional case, 16x16x... if the number of dimensions is greater than 5. If the corresponding property exists and contains a valid integer number, but it is too small, in particular, zero or negative, then it is replaced with some minimal positive value. The values of all these system property is loaded and checked only once while initializing Arrays class. If the number of dimensions is 1 (degenerated case), this method always uses 65536 as the tile size. (Warning! These defaults can be changed in future versions!)

Specified by:

tile in interface Matrix<T extends Array>

Returns:

a tiled view of this matrix with default tile dimensions.

See Also:

• Matrix.tile(long...)
• Matrix.isTiled()
• Matrix.tileDimensions()

tileParent

public Matrix<T> tileParent()

Description copied from interface: Matrix

If this matrix is a tiled view of some parent matrix, created by a call parent.tile(...), returns a reference to the parent matrix instance. If this matrix is not a tiled view, throws NotTiledMatrixException.

Specified by:

tileParent in interface Matrix<T extends Array>

Returns:

a reference to the parent matrix, if this instance is a tiled view of other matrix.

See Also:

• Matrix.isTiled()

tileDimensions

public long[] tileDimensions()

Description copied from interface: Matrix

If this matrix is a tiled view of some parent matrix, created by a call parent.tile(...), creates and returns a new Java array containing the tile dimensions, used while creating this tiled view (argument of Matrix.tile(long...) method). If this matrix is not a tiled view, throws NotTiledMatrixException.

Specified by:

tileDimensions in interface Matrix<T extends Array>

Returns:

sizes of each tile, if this instance is a tiled view of other matrix.

See Also:

• Matrix.isTiled()

isTiled

public boolean isTiled()

Description copied from interface: Matrix

Returns true if and only if this matrix is a tiled view of some parent matrix, created by a call parent.tile(...) or an equivalent call. The Matrix.tileParent() method throws NotSubMatrixException if and only if this method returns false.

Specified by:

isTiled in interface Matrix<T extends Array>

Returns:

whether this object is created by tile(...) or equivalent call.

See Also:

• Matrix.tile(long...)
• Matrix.tile()

isImmutable

public boolean isImmutable()

Description copied from interface: Matrix

Equivalent to Matrix.array().isImmutable().

There is a guarantee that this method works very quickly.

Specified by:

isImmutable in interface Matrix<T extends Array>

Returns:

true if this instance is immutable.

isCopyOnNextWrite

public boolean isCopyOnNextWrite()

Description copied from interface: Matrix

Equivalent to Matrix.array().isCopyOnNextWrite().

There is a guarantee that this method works very quickly.

Specified by:

isCopyOnNextWrite in interface Matrix<T extends Array>

Returns:

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

isDirectAccessible

public boolean isDirectAccessible()

Description copied from interface: Matrix

Returns true if and only if the built-in AlgART array implements DirectAccessible interface and ((DirectAccessible)Matrix.array()).hasJavaArray() method returns true.

There is a guarantee that this method works very quickly.

Specified by:

isDirectAccessible in interface Matrix<T extends Array>

Returns:

whether this matrix can be viewed as a Java array or a part of Java array.

clone

public Matrix<T> clone()

Description copied from interface: Matrix

Returns an exact clone of this matrix, created in SimpleMemoryModel.

For primitive element types, equivalent to Matrices.clone(thisInstance), but the generic type of the result is not updatable. For any types, equivalent to the following operators:

     final Matrix result = Arrays.SMM.newMatrix(UpdatableArray.class, thisInstance);
     Matrices.copy(null, result, thisInstance); // - maximally fast multithreading copying
     (return result)
 

Specified by:

clone in interface Matrix<T extends Array>

Overrides:

clone in class Object

Returns:

exact clone of the passed matrix.

flushResources

public void flushResources(ArrayContext context)

Description copied from interface: Matrix

Equivalent to Matrix.array().flushResources(context).

Specified by:

flushResources in interface Matrix<T extends Array>

Parameters:

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

freeResources

public void freeResources(ArrayContext context)

Description copied from interface: Matrix

Equivalent to Matrix.array().freeResources(context).

Specified by:

freeResources in interface Matrix<T extends Array>

Parameters:

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

freeResources

public void freeResources()

Description copied from interface: Matrix

Equivalent to Matrix.array().freeResources(null).

Specified by:

freeResources in interface Matrix<T extends Array>

toString

public String toString()

Description copied from interface: Matrix

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 built-in AlgART array and all matrix dimensions.

Specified by:

toString in interface Matrix<T extends Array>

Overrides:

toString in class Object

Returns:

a brief string description of this object.

hashCode

public int hashCode()

Description copied from interface: Matrix

Returns the hash code of this matrix. The result depends on all elements of the built-in array (as Array.hashCode() and all matrix dimensions.

Specified by:

hashCode in interface Matrix<T extends Array>

Overrides:

hashCode in class Object

Returns:

the hash code of this matrix.

equals

public boolean equals(Object obj)

Description copied from interface: Matrix

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

1. the specified object is a matrix (i.e. implements Matrix),
2. both matrices have the same dimension count (Matrix.dimCount()) and the same corresponding dimensions;
3. the built-in AlgART arrays (Matrix.array()) are equal (see Array.equals(Object)).

Specified by:

equals in interface Matrix<T extends Array>

Overrides:

equals in class Object

Parameters:

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

Returns:

true if the specified object is a matrix equal to this one.