sub2ind

Convert subscripts to linear indices

Syntax

ind = sub2ind(sz,row,col)

ind = sub2ind(sz,I1,I2,...,In)

Description

ind = sub2ind(sz,row,col) returns the linear indices ind corresponding to the row and column subscripts in row and col 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.

ind = sub2ind(sz,I1,I2,...,In) returns the linear indices ind corresponding to multidimensional subscripts in n arrays I1,I2,...,In 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 Subscripts to Linear Indices for Matrix

The mapping from subscripts (indexing by position) to linear indices for a 3-by-3 matrix can be illustrated as in the following.

Specify the row and column subscripts in a 3-by-3 matrix. Convert the subscripts to linear indices.

row = [1 2 3 1];
col = [2 2 2 3];
sz = [3 3];
ind = sub2ind(sz,row,col)

ind = 1×4

     4     5     6     7

Convert Subscripts to Linear Indices for Three-Dimensional Array

The mapping from subscripts to linear indices for a 2-by-2-by-2 array can be illustrated as in the following.

Specify the row, column, and page subscripts in a 2-by-2-by-2 array. Convert the subscripts to linear indices.

I1 = [1 2 1 2];
I2 = [2 2 1 1];
I3 = [1 1 2 2];
sz = [2 2 2];
ind = sub2ind(sz,I1,I2,I3)

ind = 1×4

     3     4     5     6

Access Element of 3-D Array

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

Create an array, and find the linear index corresponding to the element in the (2,1,2) position.

A = rand(3,4,2);
linearInd = sub2ind(size(A),2,1,2)

linearInd = 
14

Check that both index versions refer to the same element.

A(2,1,2)

ans = 
0.4854

A(14)

ans = 
0.4854

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

row — Row subscripts

scalar | vector | matrix | multidimensional array

Row subscripts, specified as a scalar, vector, matrix, or multidimensional array. row and col can be arrays of the same size, or either one can be scalar.

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

col — Column subscripts

scalar | vector | matrix | multidimensional array

Column subscripts, specified as a scalar, vector, matrix, or multidimensional array. row and col can be arrays of the same size, or either one can be scalar.

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

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

scalar | vector | matrix | multidimensional array

Multidimensional subscripts, specified as a scalar, vector, matrix, or multidimensional array. I1,I2,…,In can be arrays of the same size, or any of them can be scalar.

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

Output Arguments

ind — Linear indices

scalar | vector | matrix | multidimensional array

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

• If the subscript inputs all have the same size, then ind is also that size.

• If the subscript inputs are a mix of scalars and arrays, then ind has the size of the nonscalar subscript inputs.

Data Types: double

Algorithms

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

Extended Capabilities

Tall Arrays

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

The sub2ind 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 first argument must be a valid size vector. Code generation does not support size vectors for arrays with more than intmax elements.

• The generated code treats NaN inputs as out of range and throws a run-time error.

• See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The first argument must be a valid size vector. Code generation does not support size vectors for arrays with more than intmax 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 sub2ind 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

R2024a: sub2ind accepts mix of scalars and vectors for subscript inputs

sub2ind now leverages scalar expansion and accepts a mix of scalars and vectors for subscript inputs. For example, sub2ind(sz,[1 2 3],2) is now the same as sub2ind(sz,[1 2 3],[2 2 2]). Previously, the subscript inputs were required to be the same size.