[ILNumerics Computing Engine]
Namespace: ILNumerics
Assembly: ILNumerics.Computing (in ILNumerics.Computing.dll) Version: 5.5.0.0 (5.5.7503.3146)
public static RetArray<long> ind2sub<T, LocalT, InT, OutT, RetT, StorageT>( ConcreteArray<T, LocalT, InT, OutT, RetT, StorageT> A, InArray<long> indices, int nrOutDims = -1 ) where LocalT : Mutable<T, LocalT, InT, OutT, RetT, StorageT> where InT : Immutable<T, LocalT, InT, OutT, RetT, StorageT> where OutT : Mutable<T, LocalT, InT, OutT, RetT, StorageT> where RetT : ConcreteRetArray<T, LocalT, InT, OutT, RetT, StorageT> where StorageT : new(), BaseStorage<T, LocalT, InT, OutT, RetT, StorageT>
Parameters
- A
- Type: ILNumerics.Core.ArraysConcreteArrayT, LocalT, InT, OutT, RetT, StorageT
The input array providing the size, strides and element type to compute subscript indices for. - indices
- Type: ILNumericsInArrayInt64
Sequential ('linear') indices into A. n elements of arbitrary shape. - nrOutDims (Optional)
- Type: SystemInt32
[Optional] Number of subscript dimensions. Default: (-1) A.S.NumberOfDimensions.
Type Parameters
- T
- LocalT
- InT
- OutT
- RetT
- StorageT
Return Value
Type: RetArrayInt64A matrix [m, n], where m = indices.S.NumberOfElements and n = A.S.NumberOfDimensions. Indices for each dimension are stored in columns.
Exception | Condition |
---|---|
ArgumentException | if A has less than 1 dimension. |
ArgumentNullException | if A or indices are null. |
This function converts sequential element indices into subscript indices. Subscript indices specify the position of an element in A by giving the position of the element in each dimension individually. Hence, n subscript indices are required to describe the element position in A. In contrast to that, sequential indices specify the position of an element in A by a single sequential index, where all elements are considered to be 'lined-up'. The sequential index is than simply the index of the element in the line.
The (virtual) lining-up of the elements in A is performed in column major order. Note, that the order considered by ind2sub``6(ConcreteArrayUMP, UMP, UMP, UMP, UMP, UMP, InArrayInt64, Int32) is not related to the actual order of the elements as they are stored in memory.
If indices is not a vector its elements are read in column major order.
If the optional parameter nrOutDims is positive it specifies the number of output subscript dimensions to compute. This number can differ from the actual number of dimensions in A. If nrOutDims is smaller than the number of dimensions in A unspecified trailing dimensions of A are virtually merged and the last column of subscript indices holds the indices into those merged dimension. Note, that in order to use these indices to address elements of A subarray indexing must be performed in ArrayStyle = ILNumericsV4.
If nrOutDims is larger than A.S.NumberOfDimensions then subscripts in columns corresponding to virtual dimensions of A will be '0'.
The matrix returned gives the subscripts for each element index in indices in rows. The matrix stores m rows of subscripts, corresponding to m elements in indices.
indices can contain values addressing non-existing elements in A (indices out-of-range). These indices will produce out-of-range subscript indices also. In ILNumericsV4 they may be used to grow the size of an array in a left-side index expression. ind2sub``6(ConcreteArrayUMP, UMP, UMP, UMP, UMP, UMP, InArrayInt64, Int32) does not give an error for out-of-range elements nor for negative values in indices! The special meaning of latter (i.e.: counting from the end) is not considered here.
sub2ind``6(ConcreteArrayUMP, UMP, UMP, UMP, UMP, UMP, InArrayInt64) and ind2sub``6(ConcreteArrayUMP, UMP, UMP, UMP, UMP, UMP, InArrayInt64, Int32) are equivalent operations, inverting the results of the respective other function. Combining both functions creates a roundtrip and gives the original data.
[ILNumerics Computing Engine]