matlab.mixin.Copyable - Superclass providing copy functionality for handle objects - MATLAB (original) (raw)

• Documentation
• Examples
• Functions
• Apps
• Videos
• Answers

Main Content

Namespace: matlab.mixin

Superclass providing copy functionality for handle objects

Description

The matlab.mixin.Copyable class is an abstract handle class that provides a copy method for copying handle objects. Thecopy method makes a shallow copy of the object (that is, it shallow-copies all nondependent properties from the source object to the destination object). MATLAB® does not call copy recursively on any handles contained in property values.

Subclass matlab.mixin.Copyable to define handle classes that inherit a copy method. The copy method copies data without calling the class constructor or property set functions. It therefore produces no side effects.

Subclasses can customize copy behavior by deriving frommatlab.mixin.Copyable and overriding thecopyElement method. For more information, see the example Customizing Subclass Copy Behavior.

The matlab.mixin.Copyable class is a handle class.

Class Attributes

For information on class attributes, see Class Attributes.

Methods

expand all

Public Methods

Protected Methods

Examples

Add Copy Method

Add a copy method to your handle class by subclassingmatlab.mixin.Copyable.

classdef MyClass < matlab.mixin.Copyable properties Prop end end

Create an object.

Create a copy of the object.

For more information, see Implement Copy for Handle Classes.

Customizing Subclass Copy Behavior

The copy method provides the public, non-overrideable interface to copy behavior. This method takes an array of objects as input and returns an array of the same dimensions.

copyElement is a protected method that thecopy method uses to perform the copy operation on each object in the input array. You can override copyElement in your subclass to customize the behavior of the inherited copy method.

Use the property NonCopyable attribute to control if the copy operation copies specific property values.

Implement Selective Deep Copy

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 ofmatlab.mixin.Copyable that containshandle objects in two properties
• DeepCp — subclass ofmatlab.mixin.Copyable
• ShallowCp — subclass ofhandle

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 frommatlab.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 nocopy 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 DeepObj andShallowObj properties.

sc = ShallowCp(7); dc = DeepCp(7); a = ContainsHandles(4,5,dc,sc); a.DeepObj

ans =

DeepCp with properties:

DpProp: 7

ans =

ShallowCp with properties:

ShProp: 7

Make a copy of the ContainsHandles object.

The returned copy b contains a shallow copy of objectsc, and a deep copy of object dc. That is, the dc object passed toContainsHandles constructor is now a new, independent object as a result of the copy operation. You can now change thedc 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 object that is deep-copied is not affected.

ans =

DeepCp with properties:

DpProp: 7

The shallow-copied object still references the same data.

ans =

ShallowCp with properties:

ShProp: 5

Override Copy Behavior in Hierarchies

The copyElement method in a superclass cannot access the private data in a subclass.

If you override copyElement in a subclass ofmatlab.mixin.Copyable, and then use this subclass as a superclass, you need to override copyElement in all subclasses that contain private properties. The override ofcopyElement in subclasses should call thecopyElement 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@matlab.mixin.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 ofcopyElement in SubClass1 calls the property set method, if one exists, possibly introducing side effects to the copy operation.

Copy Behaviors for Specific Inputs

Consider a call to the matlab.mixin.Copyable copy method of this form:

This call to copy produces the results described for each of the following conditions:

• 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 subclassmatlab.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 frommatlab.mixin.Copyable because the instances you can create is limited to the ones defined inside the enumeration block. SeeDefine Enumeration Classes for more information about enumeration classes.

More About

expand all

Making a Deep Copy

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.

Making a Shallow Copy

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.

Version History

Introduced in R2011a

See Also