matlab.mixin.indexing.RedefinesParen Class

Namespace: matlab.mixin.indexing

Customize class indexing operations that use parentheses

Since R2021b

Description

The matlab.mixin.indexing.RedefinesParen class is an abstract superclass that enables you to customize how indexing operations with parentheses behave. RedefinesBrace and RedefinesDot enable you to customize indexing operations with curly braces and dots. You can inherit from these classes individually, customizing one aspect of behavior without affecting the default behavior of the other indexing operations.

To customize how your class handles indexing operations with parentheses, inherit from RedefinesParen and implement its abstract methods:

• cat

• empty

• size

• parenAssign

• parenDelete

• parenListLength

• parenReference

Class Attributes

Abstract	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Methods

Specialized Operators and Functions

These methods specialize standard MATLAB^® operators and functions for objects in this class.

cat	Implement this method with signature C = cat(dim,varargin) to concatenate the class array along the specified dimension. Abstract true
empty	Implement this method with signature obj = empty(varargin) to create an empty array. Abstract true Static true
size	Implement this method with signature varargout = size(obj,varargin) to return the size of the array. Abstract true
ctranspose	B = ctranspose(obj) returns the conjugate transpose of the array. The default implementation of this method errors.
end	ind = end(obj,k,n) returns the index value represented by end, where k is the index in which the end expression appears, and n is the total number of indices in the expression. By default, this method calls size.
horzcat	C = horzcat(varargin) horizontally concatenates the input arguments. By default, horzcat calls cat(2,varargin{:}).
isempty	TF = isempty(obj) returns logical 1 (true) if the array is empty. By default, isempty calls size.
length	L = length(obj) returns the length of the largest array dimension. By default, length calls size.
ndims	N = ndims(obj) returns the number of dimensions in the array. By default, ndims calls size.
numel	n = numel(obj) returns the number of array elements. By default, numel calls size.
reshape	B = reshape(obj,varargin) reshapes the array. The default implementation of this method errors.
transpose	B = transpose(obj) returns the transpose of the array. The default implementation of this method errors.
vertcat	C = vertcat(varargin) vertically concatenates the input arguments. By default, vertcat calls C = cat(1,varargin{:}).

Protected Methods

Abstract Methods

parenAssign	Customize handling of object index assignments that begin with parentheses
parenDelete	Customize handling of object index deletions
parenListLength	Determine number of values to return from customized indexing operations beginning with parentheses
parenReference	Customize handling of object index references that begin with parentheses

Examples

Customize Parentheses Indexing

The ArrayWithLabel class has two properties: ContainedArray and Label. ArrayWithLabel customizes parentheses indexing into ContainedArray by inheriting from matlab.mixin.indexing.RedefinesParen and implementing all of its abstract methods:

• parenReference: Handles parentheses indexing into ContainedArray.

• parenDelete: Deletes parentheses-indexed elements of ContainedArray.

• parenAssign: Assigns values to the indexed elements of ContainedArray. The right-hand side of the assignment expression must be an instance of ArrayWithLabel.

• parenListLength: Determines the number of values to return from parentheses indexing operations on ContainedArray.

• cat: Concatenates the ContainedArray property of one or more instances of the class.

• empty: Returns an instance of the class with an empty ContainedArray.

• size: Returns the dimensions of ContainedArray.

ArrayWithLabel also provides two public methods:

• value: Displays the indexed values of ContainedArray.

• sum: Calculates the sum of the indexed values of ContainedArray.

ArrayWithLabel Class Code

classdef ArrayWithLabel < matlab.mixin.indexing.RedefinesParen

    properties (Access=private)
        ContainedArray
    end
    
    properties (Access=public)
        Label
    end
    
    methods
        function obj = ArrayWithLabel(val)
            obj.ContainedArray = val;
        end
    end

    methods (Access=protected)
        function varargout = parenReference(obj, indexOp)
            obj.ContainedArray = obj.ContainedArray.(indexOp(1));
            if isscalar(indexOp)
                varargout{1} = obj;
                return;
            end
            % This code forwards all indexing operations after
            % the first parentheses reference to MATLAB for handling.
            [varargout{1:nargout}] = obj.(indexOp(2:end));
        end

        function obj = parenAssign(obj,indexOp,varargin)
            % Ensure object instance is the first argument of call.
            if isempty(obj)
                obj = varargin{1};
            end
            if isscalar(indexOp)
                assert(nargin==3);
                rhs = varargin{1};
                obj.ContainedArray.(indexOp) = rhs.ContainedArray;
                return;
            end
            [obj.(indexOp(2:end))] = varargin{:};
        end

        function n = parenListLength(obj,indexOp,ctx)
            if numel(indexOp) <= 2
                n = 1;
                return;
            end
            containedObj = obj.(indexOp(1:2));
            n = listLength(containedObj,indexOp(3:end),ctx);
        end

        function obj = parenDelete(obj,indexOp)
            obj.ContainedArray.(indexOp) = [];
        end
    end

    methods (Access=public)
        function out = value(obj)
            out = obj.ContainedArray;
        end
        
        function out = sum(obj)
            out = sum(obj.ContainedArray,"all");
        end
        
        function out = cat(dim,varargin)
            numCatArrays = nargin-1;
            newArgs = cell(numCatArrays,1);
            for ix = 1:numCatArrays
                if isa(varargin{ix},'ArrayWithLabel')
                    newArgs{ix} = varargin{ix}.ContainedArray;
                else
                    newArgs{ix} = varargin{ix};
                end
            end
            out = ArrayWithLabel(cat(dim,newArgs{:}));
        end

        function varargout = size(obj,varargin)
            [varargout{1:nargout}] = size(obj.ContainedArray,varargin{:});
        end
    end

    methods (Static, Access=public)
        function obj = empty()
            obj = ArrayWithLabel([]);
        end
    end
end

Use an ArrayWithLabel Instance

Construct an ArrayWithLabel object with a 2-by-2 matrix, and assign a string to the Label property.

a = ArrayWithLabel([2 3; 5 7]);
a.Label = "primes"

a=2×2 ArrayWithLabel array with properties:
    Label: "primes"

Display the first column of the array. parenReference takes a and an instance of IndexingOperation as arguments. indexOp identifies the type of reference (Paren) and the indices being referenced. parenReference retrieves the elements corresponding to those indices and then forwards the value method call to MATLAB. (The comment in the code identifies the line in parenReference that forwards additional operations after the initial parentheses indexing.)

a(:,1).value

ans = 2×1

     2
     5

Create a new instance b of ArrayWithLabel with a 1-by-2 vector. Assign the values of b to the second row of the array in a. The parenAssign method uses the indices on the left-hand side of the assignment to determine which elements of a to replace.

b = ArrayWithLabel([11 13]);
a(2,:) = b;
a.value

ans = 2×2

     2     3
    11    13

Use the sum method to find the sum of the values in the second column.

a(:,2).sum

ans = 
16

Limitations

Inheriting from both matlab.mixin.indexing.RedefinesParen and matlab.mixin.Heteroegenous is not supported.

Version History

Introduced in R2021b