subsref

Subscripted reference

Syntax

B = subsref(A,S)

Description

For classes authored in R2021b and later, the recommended process for customizing indexing is to inherit from some combination of matlab.mixin.indexing.RedefinesParen, matlab.mixin.indexing.RedefinesDot, and matlab.mixin.indexing.RedefinesBrace. For more information, see Customize Object Indexing.

B = subsref(A,S) is called by MATLAB^® for the syntax A(i), A{i}, or A.i when A is an object.

Examples

Parentheses Indexing

This example shows how MATLAB® calls subsref for the following indexing expression.

A = magic(5);
A(1:2,:)

ans = 2×5

    17    24     1     8    15
    23     5     7    14    16

The syntax, A(1:2,:), results in a call to B = subsref(A,S) where S is a 1-by-1 structure where S.type is '()' and S.subs is {1:2,':'}. The colon character indicates a colon used as a subscript.

Brace Indexing

This example shows how MATLAB® calls subsref for indexing expression that use braces.

C = {"one", 2, 'three'};
C{1:2}

ans = 
"one"

ans = 
2

The syntax, C{1:2}, results in a call to [c1,c2] = subsref(C,S) where S.type is '{}' and S.subs is {[1 2]}.

Dot Indexing

This example shows how MATLAB® calls subsref for indexing expression that use dot notation.

A = struct('number',10);
A.number

ans = 
10

The syntax A.number results in a call to B = subsref(A,S) where S.Type is '.' and S.subs is 'number'.

Input Arguments

A — Indexed object array

any object

Indexed object array, passed by MATLAB as the object array that is part of the indexing expression.

S — Indexing structure

specialized indexing structure

Indexing structure, passed by MATLAB as the indexing substruct for the indexing expression that caused the call to subsref. This structure has these fields:

• type – Character vector or string scalar containing (), {}, or ., specifying the subscript type.

• subs – Cell array, character vector, or string scalar containing the actual subscripts.

Index expressions can use more than one level to form more complicated expressions. For example A{1}.field(3:5) has three levels of indexing. For this expression, S is a 3-by-1 structure array with these fields:

disp(S(1))
    type: '{}'
    subs: {[1]}
disp(S(2))
    type: '.'
    subs: 'field'
disp(S(3))
    type: '()'
    subs: {[3 4 5]}

Data Types: struct

Output Arguments

B — Result of indexing expression

any type of value

Result of indexing expression.

More About

Understanding Indexing Expressions

A(I) is an array formed from the elements of A specified by the subscript vector I. The resulting array is the same size as I except for the special case where A and I are both vectors. In this case, A(I) has the same number of elements as I but has the orientation of A.

A(I,J) is an array formed from the elements of the rectangular submatrix of A, specified by the subscript vectors I and J. The resulting array has length(I) rows and length(J) columns. A colon used as a subscript indicates all elements in that dimension. For example, A(I,:) means all columns of those rows specified by vector I. Similarly, A(:,J) means all rows of columns specified by J.

A(I,J,K,...) is the array specified by the subscripts. The result is length(I)-by-length(J)-by-length(K)....

A{I} where A is a cell array and I is a scalar forms a copy of the array in the specified cell of A. If I has more than one element, this expression is a comma-separated list. You can also use multiple subscripts that specify a scalar element, as in A{3,4}.

A(I).field when A is a structure array and I is a scalar forms a copy of the array in the field with the name field. If I has more than one element, this expression is a comma-separated list. If A is a 1-by-1 structure array, then the subscript can be dropped. In this case, A.field is the same as A(1).field.

Extended Capabilities

Tall Arrays

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

Tall arrays support a limited subset of indexing operations. For details, see Index and View Tall Array 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 subsref function supports GPU array input with these usage notes and limitations:

• Curly brace indexing for cell arrays and dot indexing for structures are not supported (GPU arrays do not support cell arrays or structures).

• Sparse GPU arrays only support referencing whole rows or columns by index. For example, you can access the fifth row of sparse matrix A by calling A(5,:) or A(5,1:end).

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

Usage notes and limitations:

• Curly brace indexing for cell arrays and dot indexing for structures are not supported.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a