Property Definition

What You Can Define

Control aspects of property definitions in the following ways:

Note

Properties cannot have the same name as the class.

Note

Always use case-sensitive property names in your MATLAB® code.

Initialize Property Values

There are two basic approaches to initializing property values:

  • In the property definition — MATLAB evaluates the expression only once and assigns the same value to the property of every instance.

  • In a class constructor — MATLAB evaluates the assignment expression for each instance, which ensures that each instance has a unique value.

For more information on the evaluation of expressions that you assign as property default values, see When MATLAB Evaluates Expressions.

Property Default Values

Within a properties block, you can control an individual property's default value. Assign default values as a value or MATLAB expressions. Expressions cannot reference variables. For example:

  • Prop1 — No assignment results in empty [] default value

  • Prop2 — Assign character array as default value

  • Prop3 — Assign result of expression as default value

  • Prop4 — Assign the same instance of a handle class to Prop4 for all instances of this class

  • Prop5 — Assign a default value that satisfies the specified restrictions of scalar positive double.

classdef ClassName
   properties
      Prop1
      Prop2 = 'some text'
      Prop3 = sin(pi/12)
      Prop4 = containers.Map 
      Prop5 (1,1) double {mustBePositive} = 1
   end
end

If the class definition does not specify a default property value, MATLAB initializes the property value to empty double ([]). If the class specifies any class, size, or validation function restrictions on the property value, then the class must ensure that the default value satisfies those restrictions by assigning a valid value when an empty value is invalid.

Note

Evaluation of property default values occurs only when the value is first needed, and only once when MATLAB first initializes the class. MATLAB does not reevaluate the expression each time you create an instance of the class.

For more information on the evaluation of expressions that you assign as property default values, see Evaluation of Expressions in Class Definitions and Properties Containing Objects.

For information on class, size, and validation functions used in property definitions, see Validate Property Values.

Initializing Properties to Handle Objects

MATLAB assigns the specified default values to properties only once when MATLAB loads the class definition. If you use a handle class constructor to create a property default value, MATLAB calls the constructor only when the class is first used, and then uses the same object handle as the default for the property in all objects created. Because all of the object handles reference the same object, any changes you make to the handle object in one instance are made to the handle object in all instances.

If you want a property value to be initialized to a new instance of a handle object each time you create an object of your class, assign the property value in the constructor.

Assign Property Values in Constructor

To assign values to a property from within the class constructor, refer to the object that the constructor returns (the output variable obj) and the property name using dot notation:

classdef MyClass
   properties
      Prop1
   end
   methods
      function obj = MyClass(intval)
         % Initialize Prop1 for each instance
         obj.Prop1 = intval;
      end
   end
end

When you assign a property in the class constructor, MATLAB evaluates the assignment statement for each object you create. Assign property values in the constructor if you want each object to contain a unique value for that property.

For example, suppose that you want to assign a unique handle object to the property of another object each time you create one of the other objects. Assign the handle object to the property in the constructor. Call the handle object constructor to create a unique handle object with each instance of your class.

classdef ContainsHandle
   properties
       Prop1
   end
   methods
       function obj = ContainsHandle(keySet,valueSet)
           obj.Prop1 = MyHandleClass(keySet,valueSet);
       end
   end
end

For more information on constructor methods, see Referencing the Object in a Constructor.

Default Values Evaluated Before Constructing Object

MATLAB validates property default values before the assignment of values in the constructor. It is necessary for the default value assigned in the properties block and the property value set in a class constructor to satisfy the specified validation. For example, this class restricts Prop to a scalar positive double, but does not assign a valid default value. By default, MATLAB assigns a default value of empty double, which causes a run-time error.

classdef PropInit
    properties
        % Error without valid default value
        Prop (1,1) double {mustBePositive} 
        % Empty default fails mustBePositive
    end
    methods
        function obj = PropInit(positiveInput)
            obj.Prop = positiveInput;
        end
    end
end

Calling the class constructor with a valid value for Prop results in an error from the validation function mustBePositive.

obj = PropInit(2);
Error using implicit default value of property 'Prop' of class 'PropInit':
Value must be positive.

Property Attributes

All properties have attributes that modify certain aspects of the property's behavior. Specified attributes apply to all properties in a particular properties block. For example:

classdef ClassName
   properties (PropertyAttribute = value)
      Prop1
      Prop2
   end
end

For example, only methods in the same class definition can modify and query the Salary and Password properties.

classdef EmployeeInfo
   properties (Access = private)
      Salary
      Password
   end
end

This restriction exists because the class defines these properties in a properties block with the Access attribute set to private.

Property Attributes

For a description of property attributes you can specify, see, Property Attributes.

Property Access Methods

MATLAB calls whenever setting or querying a property value. Define property set access or get access methods in methods blocks that specify no attributes and have the following syntax:

methods

   function obj = set.PropertyName(obj,value)
      ...
   end

   function value = get.PropertyName(obj)
      ...
   end

end

MATLAB does not call the property set access method when assigning the default value specified in the property's definition block.

For example, the set.Password method tests the length of the character array assigned to a property named Password. If there are fewer than seven characters in the value assigned to the property, MATLAB returns the error. Otherwise, MATLAB assigns the specified value to the property.

function obj = set.Password(obj,pw)
   if numel(pw) < 7
      error('Password must have at least 7 characters')
   else
      obj.Password = pw;
end

For more information on property access methods, see Property Access Methods.

Reference Object Properties Using Variables

MATLAB can resolve a property name from a char variable using an expression of the form:

object.(PropertyNameVar)

where PropertyNameVar is a variable containing the name of a valid object property. Use this syntax when passing property names as arguments. For example, the getPropValue function returns the value of the KeyType property:

PropName = 'KeyType';
function o = getPropValue(obj,PropName)
   o = obj.(PropName);
end

Related Topics