ind2sub

Convert linear indices to subscripts

Syntax

[row,col] = ind2sub(sz,ind)

[I1,I2,...,In] = ind2sub(sz,ind)

Description

[row,col] = ind2sub(sz,ind) returns the arrays row and col containing the equivalent row and column subscripts corresponding to the linear indices ind for a matrix of size sz. Here sz is a vector with two elements, where sz(1) specifies the number of rows and sz(2) specifies the number of columns.

[I1,I2,...,In] = ind2sub(sz,ind) returns n arrays I1,I2,...,In containing the equivalent multidimensional subscripts corresponding to the linear indices ind for a multidimensional array of size sz. Here sz is a vector with n elements that specifies the size of each array dimension.

Examples

Convert Linear Indices to Subscripts for Matrix

Convert the linear indices [3 4 5 6] to row and column subscripts in a 3-by-3 matrix. The mapping from linear indices to subscripts (indexing by position) is illustrated in the following.

Create input vectors and perform the conversion.

ind = [3 4 5 6];
sz = [3 3];
[row,col] = ind2sub(sz,ind)

row = 1×4

     3     1     2     3

col = 1×4

     1     2     2     2

Convert Linear Indices to Subscripts for Three-Dimensional Array

Convert the linear indices [3 4 5 6] to subscripts in a 2-by-2-by-2 array. The mapping from linear indices to subscripts (indexing by position) for a 2-by-2-by-2 array can be illustrated as in the following.

Create input vectors and perform the conversion.

ind = [3 4 5 6];
sz = [2 2 2];
[I1,I2,I3] = ind2sub(sz,ind)

I1 = 1×4

     1     2     1     2

I2 = 1×4

     2     2     1     1

I3 = 1×4

     1     1     2     2

Access Element of 3-D Array

Convert a linear index of a 3-D array to a subscript index.

Create an array, and find the subscript index corresponding to the 14 th element of the array.

A = rand(3,4,2);
[row,col,page] = ind2sub(size(A),14)

row = 
2

col = 
1

page = 
2

Check that both index versions refer to the same element of the array.

A(14)

ans = 
0.4854

A(row,col,page)

ans = 
0.4854

Use ind2sub with Fewer Output Arguments

When using ind2sub for an N-dimensional array, you would typically supply N output arguments for each dimension of the matrix. This example shows the different results when you return fewer output arguments for a 3-dimensional array.

Create the input arguments needed to convert the linear indices 1 through 8 for a 3-dimensional array with size 2-by-2-by-2.

ind = 1:8;
sz = [2 2 2];

Specify three output arguments when using ind2sub to return the row, column, and page subscripts for the 2-by-2-by-2 array.

[row,col,page] = ind2sub(sz,ind)

row = 1×8

     1     2     1     2     1     2     1     2

col = 1×8

     1     1     2     2     1     1     2     2

page = 1×8

     1     1     1     1     2     2     2     2

If you specify only two output arguments, ind2sub ignores the third dimension of the array and returns subscripts for a 2-dimensional array with size 2-by-4 instead.

[row,col] = ind2sub(sz,ind)

row = 1×8

     1     2     1     2     1     2     1     2

col = 1×8

     1     1     2     2     3     3     4     4

If you specify only one output argument, ind2sub ignores the second and third dimensions of the array and returns subscripts for a 1-dimensional array with size 1-by-8 instead.

row = ind2sub(sz,ind)

row = 1×8

     1     2     3     4     5     6     7     8

Convert Linear Indices Outside Matrix Size

When converting linear indices to subscript indices using a target matrix size that is smaller than required, the ind2sub function automatically expands the matrix size as necessary.

For example, define linear indices that are outside the matrix size of 3-by-1.

ind = [9 11 13 14]

ind = 1×4

     9    11    13    14

Convert these indices to subscript indices for a 3-by-1 matrix.

[row,col] = ind2sub([3 1],ind)

row = 1×4

     3     2     1     2

col = 1×4

     3     4     5     5

ind2sub does not produce an error for this operation. Instead, ind2sub automatically adds columns and expands the matrix size to 3-by-5 to accommodate the conversion of the specified linear indices to subscript indices.

For comparison, convert the same linear indices to subscript indices for a 3-by-5 matrix. The resulting subscript indices for a 3-by-5 matrix and a 3-by-1 matrix are the same.

[row,col] = ind2sub([3 5],ind)

row = 1×4

     3     2     1     2

col = 1×4

     3     4     5     5

Input Arguments

sz — Size of array

vector of positive integers

Size of array, specified as a vector of positive integers. Each element of this vector indicates the size of the corresponding dimension. For example, [2 3 4] defines a 2-by-3-by-4 array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ind — Linear indices

scalar | vector | matrix | multidimensional array

Linear indices, specified as a scalar, vector, matrix, or multidimensional array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

row — Row subscripts

scalar | vector | matrix | multidimensional array

Row subscripts, returned as a scalar, vector, matrix, or multidimensional array. The size of row is the same as the size of the input ind.

Data Types: double

col — Column subscripts

scalar | vector | matrix | multidimensional array

Column subscripts, returned as a scalar, vector, matrix, or multidimensional array. The size of col is the same as the size of the input ind.

Data Types: double

I1,I2,...,In — Multidimensional subscripts

scalar | vector | matrix | multidimensional array

Multidimensional subscripts, returned as a scalar, vector, matrix, or multidimensional array. The size of each array I1,I2,…,In is the same as the size of the input ind.

Data Types: double

Tips

• To get the linear indices of matrix elements that satisfy a specific condition for matrix A, you can use the find function with one output argument. To get the subscript indices, use the find function with two output arguments. For example, [row,col] = ind2sub(size(A),find(A>5)) gives the same result as [row,col] = find(A>5).

Algorithms

For an array A, if [I1,…,In] = ind2sub(size(A),ind), then A(I1(k),…,In(k)) = A(ind(k)) for all k.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The ind2sub function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The input vectors sz and ind can contain only finite integer values.

• The size vector sz must be fixed size at code generation time.

• For code generation, the maximum number of elements in an array is constrained by the code generator and the target hardware. See Array Size Restrictions for Code Generation (MATLAB Coder).

  • Size vectors for arrays with more than the maximum number of elements are not supported.

  • The index vector ind cannot contain any values greater than the maximum number of elements.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The ind2sub function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2024b: Scalar input for array size is not supported

The input argument for the size of the array must be a vector of positive integers with two or more elements. In previous releases, ind2sub(sz,ind) treated a scalar input size sz as the number of rows in the array and assumed the size of the other dimensions to be 1. For example:

[row,col] = ind2sub(6,[2 3 4])

row =

     2     3     4


col =

     1     1     1

Starting in R2024b, a scalar input for sz results in an error. Instead, you must specify sz as a vector of positive integers with two or more elements. For example:

[row,col] = ind2sub([6 1],[2 3 4])