MATLAB®

Comparing Handle and Value Classes

Why Select Value or Handle

MATLAB^® classes support two kinds of classes — value classes and handle classes. The kind of class you select to use depends on the desired behavior of the class instances and which features you want to use. For example, do you want to use events and listeners, define dynamic properties, and so on.

The section Which Kind of Class to Use describes how to select the kind of class to use for your application.

Back to Top

Behavior of MATLAB^® Built-In Classes

If you create an object of the class int32 and make a copy of this object, the result is two independent objects having no data shared between them. The following code example creates an object of class int32 and assigns it to variable a, which is then copied to b. When you raise a to the fourth power and assign the value again to the variable a, the MATLAB language creates a new object with the new data and assigns it to the variable a, overwriting the previous assignment. The value of b does not change.

a = int32(7);
b = a;
a = a^4;
b
   7

The value of a is copied to b and results in two independent versions of the original object. This is typical of MATLAB numeric classes.

Handle Graphics^® classes return a handle to the object created. A handle is a variable that references an instance of a class. If you copy the handle, you have another variable that refers to the same object. There is still only one version of the object's data. For example, if you create a Handle Graphics line object and copy its handle to another variable, you can set the properties of the same line using either copy of the handle.

x = 1:10; y = sin(x);
h1 = line(x,y);
h2 = h1;

>>set(h2,'Color','red') % line is red
>>set(h1,'Color','green') % line is green
>>delete(h2)
>>set(h1,'Color','blue')
??? Error using ==> set
Invalid handle object.

Note also, if you delete one handle, all copies are now invalid because you have deleted the single object that all copies point to.

Back to Top

Behavior of User-Defined Classes

Value class instances behave like built-in numeric classes and handle class instances behave like Handle Graphics objects, as illustrated in Behavior of MATLAB^® Built-In Classes.

Value Classes

Objects of value classes are permanently associated with the variables to which they are assigned. When a value object is copied, the object's data is also copied and the new object is independent of changes to the original object. Instances behave like standard MATLAB numeric and struct classes.

Value Class Behavior

Value classes are useful in cases when both assigning an object to a variable and passing an object to a function should make a copy of the object. Value objects are always associated with one workspace or temporary variable and go out of scope when that variable goes out of scope or is cleared. There are no references to value objects, only copies which are themselves objects.

For example, suppose you define a polynomial class whose Coefficients property stores the coefficients of the polynomial. Note how copies of these value-class objects are independent of each other:

p = polynomial([1 0 -2 -5]);
p2 = p;
p.Coefficients = [2 3 -1 -2 -3];
p2.Coefficients
ans = 
   1 0 -2 -5

Creating a Value Class

All classes that are not subclasses of the handle class are value classes. Therefore, the following classdef creates a value class named myValueClass:

classdef myValueClass 
   ...
end 

Handle Classes

Objects of handle classes use a handle to reference objects of the class. A handle is a variable that identifies a particular instance of a class. When a handle object is copied, the handle is copied, but not the data stored in the object's properties. The copy refers to the same data as the original—if you change a property value on the original object, the copied object reflects the same change.

All handle classes are derived from the abstract handle class. In addition to providing handle copy semantics, deriving from the handle class enables your class to:

• Inherit a number of useful methods (Handle Class Methods)

• Define events and listeners (Defining Events and Listeners — Syntax and Techniques)

• Define dynamic properties (Dynamic Properties — Adding Properties to an Instance)

• Implement Handle Graphics type set and get methods (Dynamic Properties — Adding Properties to an Instance)

Creating a Handle Class

You have to explicitly subclass the handle class to create a handle class:

classdef myClass < handle
   ...
end 

See The Handle Base Class for more information on the handle class and its methods.

Subclasses of Handle Classes

If you subclass a class that is itself a subclass of the handle class, your subclass is also a handle class. You do not need to explicitly specify the handle superclass in your class definition. For example, the following employee class is defined as a handle class:

classdef employee < handle 
...
end

Suppose you want to create a subclass of the employee class for engineer employees, which must also be a handle class. You do not need to specify handle as a superclass in the classdef:

classdef engineer < employee 
...
end

Handle Class Behavior

A handle is an object that references its data indirectly. When constructing a handle, the MATLAB runtime creates an object with storage for property values and the constructor function returns a handle to this object. When the handle is assigned to a variable or when the handle is passed to a function, the handle is copied, but not the underlying data.

For example, suppose you have defined a handle class that stores data about company employees, such as the department in which they work:

classdef employee < handle 
   properties
      Name = ''
      Department = '';
   end
   methods
      function e = employee(name,dept)
         e.Name = name;
         e.Department = dept;
      end % employee
      function transfer(obj,newDepartment)
         obj.Department = newDepartment;
      end % transfer
   end
end

The transfer method in the above code changes the employee's department (the Department property of an employee object). In the following statements, e2 is a copy of the handle object e. Notice that when you change the Department property of object e, the property value also changes in object e2.

e = employee('Fred Smith','QE');
e2 = e; % Copy handle object
transfer(e,'Engineering')
e2.Department
ans =
Engineering

The variable e2 is an alias for e and refers to the same property data storage as e.

If the employee class was a value class, the transfer method would modify only its local copy of the employee object and would have to return the modified object to copy over the existing object:

e = transfer(e,'Engineering');

However, in a value class, the preceding statement would have no effect on the variable e2, which is a different employee object.

Deleting Handles

You can destroy handle objects before they become unreachable by explicitly calling the delete function. Deleting the handle of a handle class object makes all handles invalid. For example:

delete(e2)
e.Department
??? Invalid or deleted object.

Calling the delete function on a handle object invokes the destructor function(s) for that object. See Handle Class Delete Methods for more information.

Back to Top

Value or Handle Class — Which to Use

Which Kind of Class to Use