matlab.mixin.Copyable class - Package: 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 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

Customizing Subclass 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.

Implementing a 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, DeepCp, ShallowCp)
         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 handle

  Properties:
    DpProp: 7
>> a.ShallowObj.ShProp
ans = 

  ShallowCp handle

  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 handle

  Properties:
    DpProp: 7
% The shallow copied object is still referencing the same data:
>> b.ShallowObj

ans = 

  ShallowCp handle

  Properties:
    ShProp: 5

Overriding 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@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.

Copy Behaviors for Specific Inputs

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 Enumerations for more information about enumeration classes.

Methods

copy	Copy array of handle objects

Definitions

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.

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.

Attributes

ConstructOnLoad

true

To learn about attributes of classes, see Class Attributes in the MATLAB Object-Oriented Programming documentation.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation.

See Also

handle

How To

• Class Attributes

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS