Main Content

Comparison of Handle and Value Classes

Basic Difference

A value class constructor returns an object that is associated with the variable to which it is assigned. If you reassign this variable, MATLAB® creates an independent copy of the original object. If you pass this variable to a function to modify it, the function must return the modified object as an output argument. For information on value-class behavior, see Avoid Unnecessary Copies of Data.

A handle class constructor returns a handle object that is a reference to the object created. You can assign the handle object to multiple variables or pass it to functions without causing MATLAB to make a copy of the original object. A function that modifies a handle object passed as an input argument does not need to return the object.

All handle classes are derived from the abstract handle class.

Create a Value Class

By default, MATLAB classes are value classes. The following definition creates a value class named MyValueClass:

classdef MyValueClass 
   ...
end

Create a Handle Class

To create a handle class, derive the class from the handle class.

classdef MyHandleClass < handle
   ...
end

Behavior of MATLAB Built-In Classes

MATLAB fundamental classes are value classes (numeric, logical, char, cell, struct, and function handle). For example, if you create an object of the class int32 and make a copy of this object, the result is two independent objects. When you change the value of a, the value of b does not change. This behavior is typical of classes that represent values.

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

b
   7

MATLAB graphics objects are implemented as handle objects because they represent visual elements. For example, create a graphics line object and copy its handle to another variable. Both variables refer to the same line object.

x = 1:10; y = sin(x);
l1 = line(x,y);
l2 = l1;

Set the properties of the line object using either copy of the handle.

set(l2,'Color','red') 
set(l1,'Color','green') 

get(l2,'Color')
ans =

     0     1     0

Calling the delete function on the l2 handle destroys the line object. If you attempt to set the Color property on the line l1, the set function returns an error.

delete(l2)
set(l1,'Color','blue')
Error using matlab.graphics.primitive.Line/set
Invalid or deleted object.

If you delete the object by deleting any one of the existing handles, all copies are now invalid because you deleted the single object to which all handles refer.

Deleting a handle object is not the same as clearing the handle variable. In the graphics object hierarchy, the parent of the object holds a reference to the object. For example, the parent axes hold a reference to the line object referred to by l1 and l2. If you clear both variables from the workspace, the object still exists.

For more information on the behavior of handle objects, see Handle Object Behavior.

User-Defined Value Classes

MATLAB associates objects of value classes with the variables to which you assign the object. When you copy a value object to another variable or pass a value object to a function, MATLAB creates an independent copy of the object and all the data contained by the object. The new object is independent of changes to the original object. Value objects behave like MATLAB numeric and struct classes. Each property behaves essentially like a MATLAB array.

Value objects are always associated with one workspace or temporary variable. Value objects go out of scope when their variable goes out of scope or is cleared. There are no references to value objects, only copies that are independent objects.

Value Object Behavior

Here is a value class that stores a value in its Number property. The default property value is the number 1.

classdef NumValue
   properties
      Number = 1
   end
end

Create a NumValue object assigned to the variable a.

a = NumValue
a = 

  NumValue with properties:

    Number: 1

Assign the value of a to another variable, b.

b = a
b = 

  NumValue with properties:

    Number: 1

The variables a and b are independent. Changing the value of the Number property of a does not affect the Number property of b.

a.Number = 7
a = 

  NumValue with properties:

    Number: 7
b
b = 

  NumValue with properties:

    Number: 1

Modifying Value Objects in Functions

When you pass a value object to a function, MATLAB creates a copy of that object in the function workspace. Because copies of value objects are independent, the function does not modify the object in the caller’s workspace. Therefore, functions that modify value objects must return the modified object to be reassigned in the caller’s workspace.

For more information, see Object Modification.

User-Defined Handle Classes

Instances of classes that derive from the handle class are references to the underlying object data. When you copy a handle object, MATLAB copies the handle, but does not copy the data stored in the object properties. The copy refers to the same object as the original handle. If you change a property value on the original object, the copied handle references the same change.

Handle Object Behavior

Here is a handle class that stores a value in its Number property. The default property value is the number 1.

classdef NumHandle < handle
   properties
      Number = 1
   end
end

Create a NumHandle objects assigned to the variable a.

a = NumHandle
a = 

  NumHandle with properties:

    Number: 1

Assign the value of a to another variable, b.

b = a
b = 

  NumHandle with properties:

    Number: 1

The variables a and b refer to the same underlying object. Changing the value of the Number property of a also changes the Number property of b. That is, a and b refer to the same object.

a.Number = 7
a = 

  NumHandle with properties:

    Number: 7
b
b = 

  NumHandle with properties:

    Number: 7

Modifying Handle Objects in Functions

When you pass a handle object to a function, MATLAB creates a copy of the handle in the function workspace. Because copies of handles reference the same underlying object, functions that modify the handle object effectively modify the object in the caller’s workspace as well. Therefore, it is not necessary for functions that modify handle objects passed as input arguments to return the modified object to the caller.

For more information, see Object Modification.

Deleting Handles

You can destroy handle objects by explicitly calling the handle delete method. Deleting the handle of a handle class object makes all handles invalid. For example:

a = NumHandle;
b = a;
delete(a)
b.Number

Invalid or deleted object.

Calling delete on a handle object invokes the destructor function or functions for that object. See Handle Class Destructor for more information.

Initialize Properties to Contain Handle Objects

For information on the differences between initializing properties to default values in the properties block and initializing properties from within the constructor, see Initialize Property Values and Create and Initialize Object Arrays.

Determining Equality of Objects

Equality for value objects means that the objects are of the same class and have the same state.

Equality for handle objects means that the handle variables refer to the same object. You also can identify handle variables that refer to different objects of the same class that have the same state.

Equality of Value Objects

To determine if value objects are the same size and their contents are of equal value, use isequal. For example, use the previously defined NumValue class to create two instances and test for equality:

a = NumValue;
b = NumValue;
isequal(a,b)
ans =

     1

a and b are independent and therefore are not the same object. However each represents the same value.

If you change the value represented by a value object, the objects are no longer equal.

a = NumValue;
b = NumValue;
b.Number = 7;
isequal(a,b)
ans =

     0

Value classes do not have a default eq method to implement the == operation.

Equality of Handle Objects

Handle objects inherit an eq method from the handle base class. You can use == and isequal to test for two different relationships among handle objects:

  • The handles refer to the same object: == and isequal return true.

  • The handles refer to objects of the same class that have the same values, but are not the same objects — only isequal returns true.

Use the previously defined NumHandle class to create an object and copy the handle.

a = NumHandle;
b = a;

Test for equality using == and isequal.

a == b
ans =

     1
isequal(a,b)
ans =

     1

Create two instances of the NumHandle class using the default values.

a = NumHandle;
b = NumHandle;

Determine if a and b refer to the same object.

a == b
ans =

     0

Determine if a and b have the same values.

isequal(a,b)
ans =

     1

Functionality Supported by Handle Classes

Deriving from the handle class enables your class to:

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

Related Topics