matlab.mixin.Copyable Class

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. The copy 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 from matlab.mixin.Copyable and overriding the copyElement method. For more information, see the example Customizing Subclass Copy Behavior.

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

Class Attributes

`Abstract`	`true`
`ConstructOnLoad`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Methods

expand all

Public Methods

copy Copy array of handle objects

Protected Methods

copyElement Copy scalar MATLAB object

Examples

Add Copy Method

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

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

Create an object.

a = MyClass;

Create a copy of the object.

b = copy(a);

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 the copy 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 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 DeepObj and ShallowObj properties.

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

ans = 

  DeepCp with properties:

    DpProp: 7

a.ShallowObj

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 object 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 object that is deep-copied is not affected.

b.DeepObj

ans = 

  DeepCp with properties:

    DpProp: 7

The shallow-copied object still references the same data.

b.ShallowObj

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 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@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 of copyElement 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:

B = copy(A);

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 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 instances you can create is limited to the ones defined inside the enumeration block. See Define 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