matlab.mixin.Scalar Class

Namespace: matlab.mixin
Superclasses: matlab.mixin.indexing.RedefinesParen

Enforce scalar behavior for class instances

Since R2021b

Description

Instances of classes that inherit from matlab.mixin.Scalar always behave as scalars:

• The array size is always 1-by-1.

• The creation of empty arrays is prohibited.

• Concatenation of instances is prohibited.

Scalar inherits from matlab.mixin.indexing.RedefinesParen. The protected methods that enable parentheses indexing—parenReference, parenAssign, parenDelete, and parenListLength—error by default in Scalar. You can overload these methods to customize parentheses behavior for your class.

An example of a use case for this mixin is a class that acts as an interface to a piece of hardware, such as a robotic device. Forming an array of instances of such a class might not make sense because each device can be in a different state or supporting different operations. Concatenating several instances of device states also does not have an obvious use or interpretation.

Class Attributes

HandleCompatible	true
Abstract	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	The sealed implementation of this method errors. Sealed true
horzcat	The sealed implementation of this method errors. Sealed true
vertcat	The sealed implementation of this method errors. Sealed true
size	Returns [1 1]. Sealed true
isempty	Returns logical 0. Sealed true
isscalar	Returns logical 1. Sealed true
length	Returns 1. Sealed true
ndims	Returns 2. Sealed true
numel	Returns 1. Sealed true
empty	The sealed implementation of this method errors. Sealed true Static true
reshape	The sealed implementation of this method performs no operation if the input size is 1-by-1. For all other inputs, the method errors. Sealed true
transpose	Returns the input array without performing any operation. Sealed true
ctranspose	Returns the input array without performing any operation. Sealed true
end	Returns 1 by default.

Protected Methods

parenAssign	The Scalar implementation errors by default, but you can override. See parenAssign for the syntax.
parenDelete	The Scalar implementation errors by default, but you can override. See parenDelete for the syntax.
parenListLength	The Scalar implementation errors by default, but you can override. See parenListLength for the syntax.
parenReference	The Scalar implementation errors by default, but you can override. See parenReference for the syntax.

Examples

Customize Dot Indexing in a Scalar Class

This example shows how to customize dot indexing operations in the ScalarStructClass. Instances of ScalarStructClass behave much like structs. Users can dynamically add fields and associated values like a struct, but the class also serves as a base to which additional properties and methods can be added.

The class inherits from matlab.mixin.Scalar, which means its instances are scalar objects. The only possible array size is 1-by-1, and the instances cannot be concatenated. The class also inherits from matlab.mixin.indexing.RedefinesDot and implements its abstract methods to handle dot indexing operations:

• dotReference: Handles dot references into the private AddedFields property. The syntax instance.fieldname returns the value assigned to the referenced field.

• dotAssign: Adds a new field and corresponding value to the AddedFields property. The syntax instance.fieldname = value adds the field and its corresponding value.

• dotListLength: Determines the number of values to return from dot indexing expressions that return values from or assign values to a comma-separated list.

The class also defines the getAddedFields method, which returns a list of all fields and corresponding values.

ScalarStructClass Code

classdef ScalarStructClass < matlab.mixin.indexing.RedefinesDot & ...
    matlab.mixin.Scalar
     
    properties (Dependent, SetAccess=private)
        FieldNames
    end

    properties (Access=private)
        AddedFields struct
    end

    methods
        function out = get.FieldNames(obj)
            out = string(fieldnames(obj.AddedFields));
        end
    end

    methods (Access=public)
        function obj = ScalarStructClass(fieldName,fieldValue)
            if nargin == 1
                obj.AddedFields = fieldName;
                return;
            end
            obj.AddedFields = struct(fieldName,fieldValue);
        end

        function out = getAddedFields(obj)
            out = obj.AddedFields;
        end
    end

    methods (Access=protected)
        function varargout = dotReference(obj,indexOp)
            [varargout{1:nargout}] = obj.AddedFields.(indexOp);
        end

        function obj = dotAssign(obj,indexOp,varargin)
            [obj.AddedFields.(indexOp)] = varargin{:};
        end
        
        function n = dotListLength(obj,indexOp,indexContext)
            n = listLength(obj.AddedFields,indexOp,indexContext);
        end
    end
end

Use a ScalarStructClass Instance

Construct a ScalarStructClass instance with one field and a corresponding value.

myStructClass = ScalarStructClass("Field1",75)

myStructClass = 
  ScalarStructClass with properties:

    FieldNames: "Field1"

Add a second field to the instance using dot assignment. The dotAssign method accepts an IndexingOperation object, which describes the type of indexing operation (Dot) and the name of the field, and a second argument that contains the value of the new field.

myStructClass.Field2 = 10;

Use dot notation to verify the value of Field2. Like dotAssign, the dotReference method accepts an IndexOperation object that identifies what field to access.

myStructClass.Field2

ans = 
10

Use getAddedFields to see the full list of fields and values.

myStructClass.getAddedFields

ans = struct with fields:
    Field1: 75
    Field2: 10

ScalarStructClass also supports comma-separated list assignment and reference. Add a third field to myStructClass that contains a cell array.

myStructClass.CellArray = {3 4};

Access the CellArray field. The class calls the dotReference method and returns multiple outputs.

[v1,v2] = myStructClass.CellArray{:}

v1 = 
3

v2 = 
4

Assign multiple new values to the CellArray field. Because the assignment operation begins with a dot reference and ends with a brace index, the class calls the dotListLength method in addition to dotAssign to handle the assignment operation.

[myStructClass.CellArray{:}] = deal(5,6);
myStructClass.CellArray

ans=1×2 cell array
    {[5]}    {[6]}

Version History

Introduced in R2021b

R2024b: Implicit Default Value for Properties Whose Class Is a Subclass of matlab.mixin.Scalar

For properties whose class is a subclass of matlab.mixin.Scalar, MATLAB now creates an implicit default value by calling the no-argument constructor of the class. For example, if MyScalarClass is a subclass of matlab.mixin.Scalar, MATLAB calls the no-argument constructor of MyScalarClass to assign a default value to Prop1 in TestClass.

classdef TestClass
    properties
        Prop1 MyScalarClass
    end
end

Define an explicit default value for Prop1 if your class needs different behavior.