Superclass providing copy functionality for handle objects
The matlab.mixin.Copyable class is an abstract handle class that provides a copy method for copying handle objects. The copy method makes a shallow copy of the object (that is, it shallow copies all non-dependent properties from the source to the destination object). In making a shallow copy, MATLAB® does not call copy recursively on any handles contained in property values.
Subclass matlab.mixin.Copyable when you want to define handles classes that inherit a copy method. The copy method:
Copies data without calling class constructors or property set functions and therefore produces no side effects.
Enables subclasses to customize the copy behavior
The copy method provides the public, non-overrideable interface to copy behavior. copy takes an array of objects as input and returns an array of the same shape and dimensions.
copyElement is a protected method that the copy method uses to perform the copy operation on each object in the input array. copyElement is not Sealed so you can override it in your subclass to customize the behavior of the inherited copy method.
This example overrides the copyElement method in a subclass of matlab.mixin.Copyable to implement a deep copy of a specific class of handle objects.
Consider the following classes:
ContainsHandles — subclass of matlab.mixin.Copyable that contains handle objects in two properties
DeepCp — subclass of matlab.mixin.Copyable
ShallowCp — subclass of handle
Here are the simplified class definitions:
classdef ContainsHandles < matlab.mixin.Copyable properties Prop1 Prop2 DeepObj % Contains a DeepCp object ShallowObj % Contains a ShallowCp object end methods function obj = ContainsHandles(val1, val2, deepobj, shallowobj) if nargin > 0 obj.Prop1 = val1; obj.Prop2 = val2; obj.DeepObj = deepobj; obj.ShallowObj = shallowobj; end end end methods(Access = protected) % Override copyElement method: function cpObj = copyElement(obj) % Make a shallow copy of all four properties cpObj = copyElement@matlab.mixin.Copyable(obj); % Make a deep copy of the DeepCp object cpObj.DeepObj = copy(obj.DeepObj); end end end
The DeepCp class derives from matlab.mixin.Copyable:
classdef DeepCp < matlab.mixin.Copyable properties DpProp end methods function obj = DeepCp(val) ... end end end
The handle class ShallowCp does not derive from matlab.mixin.Copyable and, therefore, has no copy method:
classdef ShallowCp < handle properties ShProp end methods function obj = ShallowCp(val) ... end end end
Create a ContainsHandles object, which contains the two handle objects in its DpProp and ShProp properties:
>> sc = ShallowCp(7); >> dc = DeepCp(7); >> a = ContainsHandles(4,5,dc,sc); >> a.DeepObj ans = DeepCp with properties: DpProp: 7 >> a.ShallowObj.ShProp ans = ShallowCp with properties: ShProp: 7
Make a copy of the ContainsHandles object:
>> b = copy(a);
The returned copy b contains a shallow copy of object sc, and a deep copy of object dc. That is, the dc object passed to ContainsHandles constructor is now a new, independent objects as a result of the copy operation. You can now change the dc object without affecting the copy. This is not the case for the shallow copied object, sc:
% Change the property values of the handle objects: >> sc.ShProp = 5; >> dc.DpProp = 5; % Note that the deep copied object is not affected: >> b.DeepObj ans = DeepCp with properties: DpProp: 7 % The shallow copied object is still referencing the same data: >> b.ShallowObj ans = ShallowCp with properties: ShProp: 5
The copyElement method in a superclass cannot access the private data in a subclass.
If you override copyElement in a subclass of matlab.mixin.Copyable, and then use this subclass as a superclass, you need to override copyElement in all subclasses that contain private properties. The override of copyElement in subclasses should call the copyElement in the respective superclass, as in the previous example.
The following simplified code demonstrates this approach:
classdef SuperClass < matlab.mixin.Copyable properties(Access = private) super_prop end methods ... function cpObj = copyElement(obj) ... cpObj = copyElement@mixin.matlab.Copyable(obj); ... end end end classdef SubClass1 < SuperClass properties(Access=private) sub_prop1 end methods function cpObj = copyElement(obj) % Copy super_prop cpObj = copyElement@SuperClass(obj); % Copy sub_prop1 in subclass % Assignment can introduce side effects cpObj.sub_prop1 = obj.sub_prop1; end end end
The override of copyElement in SubClass1 copies the private subclass property because the superclass cannot access private data in the subclass.
Note: The assignment of sub_prop1 in the override of copyElement in SubClass1 calls the property set method, if one exists, possibly introducing side effects to the copy operation.
Given a call to the matlab.mixin.Copyable copy method of the form:
B = copy(A);
Under the following conditions, produces the described results:
A has dynamic properties — copy does not copy dynamic properties. You can implement dynamic-property copying in the subclass if needed.
A has no non-Dependent properties — copy creates a new object with no property values without calling the class constructor to avoid introducing side effects.
A contains deleted handles — copy creates deleted handles of the same class in the output array.
A has attached listeners — copy does not copy listeners.
A contains objects of enumeration classes — Enumeration classes cannot subclass matlab.mixin.Copyable.
A delete method calls copy — copy creates a legitimate copy, obeying all the behaviors that apply in any other usage.
Note: You cannot derive an enumeration class from matlab.mixin.Copyable because the number of instances you can create are limited to the ones defined inside the enumeration block. See Working with Enumerations for more information about enumeration classes.
|copy||Copy array of handle objects|
Copy each property value and assign it to the new (copied) property. Recursively copy property values that reference handle objects to copy all of the underlying data.
Copy each property value and assign it to the new (copied) property. If a property value is a handle, copy the handle but not the underlying data.
To learn about attributes of classes, see Class Attributes in the MATLAB Object-Oriented Programming documentation.
Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.