matlab.mixin.Heterogeneous - Superclass for heterogeneous array formation - MATLAB (original) (raw)

Namespace: matlab.mixin

Superclass for heterogeneous array formation

Description

matlab.mixin.Heterogeneous is an abstract class that supports forming arrays of objects that differ in their specific class but are all derived from a common root class. The root class derives directly frommatlab.mixin.Heterogeneous.

Class Attributes

For information on class attributes, see Class Attributes.

Methods

expand all

More About

expand all

Use matlab.mixin.Heterogeneous to define hierarchies of classes whose instances you can combine into heterogeneous arrays.

The following class definition enables the formation of heterogeneous arrays that combine instances of any classes derived fromHierarchyRoot.

classdef HierarchyRoot < matlab.mixin.Heterogeneous % HierarchyRoot is a direct subclass of matlab.mixin.Heterogeneous. % HierarchyRoot is the root of this heterogeneous hierarchy. end

Deriving the HierarchyRoot class directly frommatlab.mixin.Heterogeneous enables theHierarchyRoot class to become the root of a hierarchy of classes. You can combine instances of the members of this hierarchy into a heterogeneous array. Only instances of classes derived from the same root class can combine to form a valid heterogeneous array.

The class of a heterogeneous array is always the class of the most specific superclass common to all objects in the array. For example, suppose you define the following class hierarchy:

Forming an array containing an instance of LeafA with an instance of LeafB creates an array of classMiddle.

harray = [LeafA LeafB]; class(harray)

Forming an array containing an instance of LeafC with an instance of LeafD creates an array of classHierarchyRoot.

harray = [LeafC LeafD]; class(harray)

Forming an array containing an instance of LeafA with another instance of LeafA creates a homogeneous array of classLeafA.

harray = [LeafA LeafA]; class(harray)

Restrictions on Heterogeneous Array Formation

You can form heterogeneous arrays only with objects that are derived from the same hierarchy root (for example, the HierarchyRoot class in the hierarchy shown previously).

You can form heterogeneous arrays with objects that derive from multiple superclasses, but only one branch in the hierarchy can define a heterogeneous root.

Forming a Heterogeneous Array

Heterogeneous arrays are the result of operations that produce arrays containing instances of two or more classes from the heterogeneous hierarchy. Usually, the operation is concatenation or indexed assignment. For example, these statements form a heterogeneous array using indexed assignment.

harray(1) = LeafA; harray(2) = LeafC; class(harray)

Growing the Array Can Change Its Class

If an array contains objects derived frommatlab.mixin.Heterogeneous, assigning new objects into it can change the class of the array. For example, consider a homogeneous array containing objects only of the LeafA class.

harray = [LeafA,LeafA,LeafA]; class(harray)

Adding an object of a different class derived from the same root to a homogeneous array converts the array's class to the most specific superclass.

harray(4) = LeafB; class(harray)

When MATLAB® invokes a method for which the dominant argument is a heterogeneous array:

• The method must be defined for the class of the heterogeneous array, either directly by the class of the array or by inheritance from a superclass.
• The method must be Sealed = true (that is, cannot be overridden by a subclass). If you need to seal an inherited method, see Sealing Inherited Methods.

As with a homogeneous array, the class of the heterogeneous array determines which class method executes for any given method invocation. MATLAB does not consider the class of individual elements in the array when dispatching to methods.

Sealing Inherited Methods

The requirement that methods called on a heterogeneous array beSealed = true ensures correct and predictable behavior with all array elements.

You must override methods that are inherited from outside the heterogeneous hierarchy if these methods are not Sealed = true and you want to call these methods on heterogeneous arrays.

For example, suppose you define a heterogeneous array by subclassing matlab.mixin.SetGet, in addition to matlab.mixin.Heterogeneous. Override theset method to call thematlab.mixin.SetGet superclass method as required by your class design.

classdef HeterogeneousSetGet < matlab.mixin.SetGet & matlab.mixin.Heterogeneous properties P end methods(Sealed) function varargout = set(obj,varargin) [varargout{1:nargout}] = set@matlab.mixin.SetGet(obj,varargin{:}); end end end

Method implementations can take advantage of the fact that, given a heterogeneous array harray and a scalar indexn, the expression

is not a heterogeneous array. Therefore, when invoking a method on a single element of a heterogeneous array, special requirements for heterogeneous arrays do not apply.

Heterogeneous arrays in MATLAB can be created with missing array elements. For example:

• Indexed assignment creates an array with gaps. For example, ifharray is not previously defined:
• Loading a heterogeneous array from a MAT-file, but MATLAB cannot find the class definition of a specific object.

In cases like these, the matlab.mixin.Heterogeneous class calls the method getDefaultScalarElement to create default objects to fill the gaps. This method returns an instance of the root class, which is the direct subclass ofmatlab.mixin.Heterogeneous in a heterogeneous hierarchy.

When the root class is abstract or is not an appropriate default object for the classes in the heterogeneous hierarchy, you can override thegetDefaultScalarElement method to return an instance of class that is derived from the root class.

Defining the getDefaultScalarElement Method

Specify the class of the default object by overriding thematlab.mixin.Heterogeneous method calledgetDefaultScalarElement in the root class of the heterogeneous hierarchy. You can overridegetDefaultScalarElement only in the root class.

The getDefaultScalarElement method has the following signature:

methods (Static,Sealed,Access = protected) function defaultObject = getDefaultScalarElement ... end end

The getDefaultScalarElement method must satisfy these criteria:

• Static — MATLAB calls this method without an object.
• Protected — MATLAB calls this method; object users do not.
• Sealed (not required) — Seal this method to ensure users of the heterogeneous hierarchy do not change the intended behavior of the class.
• It must return a scalar object
• Its returned value must pass the isa test for the root class, that is
  (isa(getDefaultScalarElement,'HierarchyRoot')
  where HierarchyRoot is the name of the heterogeneous hierarchy root class. This means the default object can be an instance of any class derived from the root class.

Indexing and concatenation behavior with Heterogeneous arrays follows much of the usual indexing behaviors in MATLAB, but there are a few exceptions.

Indexed Assignment Behavior

Statements of the form

a(m:n) = [objm ... objn];

assign the right-hand side objects to the array elements (m:n), specified on the left side of the assignment.

Indexed assignment to a heterogeneous array can do any of these:

• Increase or decrease the size of the array.
• Overwrite existing array elements.
• Change property values of objects within the array.
• Change the class of the array.
• Change whether the array is heterogeneous.

Indexed Reference Behavior

Statements of the form

assign the elements of harray referenced by indicesm:n, to array a.

Indexed reference on a heterogeneous array returns a sub-range of the original array. Depending on the specific elements within that sub-range (m:n), the result might have a different class than the original array, and might not be heterogeneous.

Concatenation Behavior

Statements of the form

create an array, a, containing the objects listed in brackets.

Concatenating Heterogeneous objects of the same specific class preserves the class of the objects and does not form a heterogeneous array.

Concatenating Heterogeneous objects that are derived from the same root superclass, but that are of different specific classes, yields a heterogeneous array. MATLAB does not attempt to convert the class of any array members if all are part of the same root hierarchy.

Customized Indexing Not Supported

Heterogeneous arrays require consistent indexing and concatenation behaviors. Therefore, subclasses of matlab.mixin.Heterogeneous cannot change their default indexing or concatenation behavior.

Classes in a heterogeneous array cannot inherit from these mixin classes:

• matlab.mixin.indexing.RedefinesParen
• matlab.mixin.indexing.RedefinesDot
• matlab.mixin.indexing.RedefinesBrace

You also cannot overload these methods in your subclasses:

• cat
• horzcat
• vertcat
• subsref
• subsasgn

In cases involving multiple inheritance in which your subclass inherits from superclasses in addition to matlab.mixin.Heterogeneous, the superclasses cannot inherit from any of these mixins or overload any of these methods.

If you attempt to form a heterogeneous array with objects that are not derived from the same root class, MATLAB calls the convertObject method, if it exists, to convert objects to the dominant class. Implementing aconvertObject method enables the formation of heterogeneous arrays containing objects that are not part of the heterogeneous hierarchy.

When Is Conversion Necessary

Suppose there are two classes A and B, where B is not derived frommatlab.mixin.Heterogeneous, or where A and B are derived from different root classes that are derived from matlab.mixin.Heterogeneous.

MATLAB attempts to call the convertObject method implemented by the root class of A in the following cases:

• Indexed assignment A(k) = B
• Horizontal and vertical concatenations [A B] and [A;B]

Implement a convertObject method if you want to support conversion of objects whose class is not defined in your heterogeneous hierarchy. You do not need to implement this method if your class design does not require this conversion.

Implementing convertObject

Only the root class of the heterogeneous hierarchy can implement aconvertObject method.

The convertObject method must have the following signature.

methods (Static, Sealed, Access = protected) function cobj = convertObject(DomClass,objToConvert) ... end end

Where for indexed assignment A(k) = B and concatenation[A B]:

• DomClass is the name of the class of the arrayA.
• objToConvert is the object to be converted,B in this case.
• cobj is a legal member of the heterogeneous hierarchy to which A belongs.

MATLAB issues an error if convertObject returns an object that is not in the hierarchy that class A belongs to.

The matlab.mixin.Heterogeneous class is handle compatible. It can be combined with either handle or value classes when defining a subclass using multiple superclasses. See Handle Compatible Classes for information on handle compatibility.

The matlab.mixin.Heterogeneous class is a value class. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation.

Version History

Introduced in R2011a