Main Content

Property Syntax

This topic describes how to define class properties in MATLAB® using properties...end blocks, and it introduces property validation syntax and concepts. It also covers the basics of getting and setting property values from a class instance.

Property Definition Block

The properties and end keywords define one or more class properties that have the same attribute settings. This is the general syntax for defining a property block:

properties (attributes)
   propName1
   ...
   propNameN
end

Note

Properties cannot have the same name as the class or any of the other members defined by the class.

For example, this properties block defines two properties with the SetAccess attribute set to private. This attribute setting means that the property values can be set only by members of the PrivateProps class.

classdef PrivateProps
   properties (SetAccess = private)
      Property1
      Property2
   end
end

You can also define multiple property blocks for properties with different attributes. In this example, one properties block defines properties with private SetAccess, and the second block defines an abstract property. Property blocks with different attributes can appear in any order in the class definition.

classdef MultiplePropBlocks
   properties (SetAccess = private)
      Property1
      Property2
   end
   properties (Abstract)
      Property3
   end
end

For a full listing of property attributes, see Property Attributes.

Property Validation Syntax

Within a properties block, you can use property validation. Property validation enables you to place one or more restrictions on each property value, including size and class. You can also define a default value for each property. The general syntax for property validation is:

properties (attributes)
   propName1 (dimensions) class {validators} = defaultValue
   ...
end

  • (dimensions) — Size of property value, specified as a comma-separated list of two or more numbers enclosed in parentheses, such as (1,2) or (1,:). A colon allows any length in that dimension. The dimensions of the value must match (dimensions) exactly or be compatible. See Compatible Array Sizes for Basic Operations for more information. (dimensions) cannot include expressions.

  • class — Class of property value, specified as the name of the class, such as double. The value must be the specified class or a class that can be converted. For example, a property that specifies double accepts values of type single and converts them to double. Beyond the classes already available in MATLAB, you can use your own classes as property validators. For user-defined classes, property validation allows a subclass of the specified class to pass without error, but it does not convert the subclass to the superclass.

  • {validators} — Validation functions, specified as a comma-separated list enclosed in curly brackets, such as mustBePositive and mustBeScalarOrEmpty. Unlike class, validation functions do not modify property values. Validation functions error when the property values do not match their conditions. For a list of validation functions, see Property Validation Functions. You can also define your own validation functions.

  • defaultValue — Default property values must conform to the specified size, class, and validation rules. A default value can also be an expression. See Define Properties with Default Values for more information about how MATLAB evaluates default value expressions.

This class defines one property. The properties block has no explicit attribute defined, which is equivalent to defining a block of public properties. MyPublicData must also be a vector of positive doubles, and it has a default value of [1 1 1].

classdef ValidationExample
   properties
      MyPublicData (1,:) double {mustBePositive} = [1 1 1]
   end  
end

Not all validation options must be used at once, and different properties in the same block can use different combinations of validators. In this example, the RestrictedByClass property uses class validation only, while RestrictedByFunction uses a validation function and assigns a default value.

classdef DifferentValidation
   properties
      RestrictedByClass uint32
      RestrictedByFunction {mustBeInteger} = 0
   end
end

For more information, see Property Class and Size Validation and Property Validation Functions.

Property Access Syntax

Property access syntax is like MATLAB structure field syntax. For example, if obj is an object of a class, then you can get the value of a property by referencing the property name.

val = obj.PropertyName

Assign values to properties by putting the property reference on the left side of the equal sign.

obj.PropertyName = val

For example, instantiate the ValidationExample class and read the value of MyPublicData.

classdef ValidationExample
   properties
      MyPublicData (1,:) double {mustBePositive} = [1 1 1]
   end  
end
x = ValidationExample;
x.MyPublicData
ans =

     1     1     1

Assign a new value to the property that satisfies the validators defined for it.

x.MyPublicData = [2 3 5 7];

You can optionally define get and set methods that MATLAB automatically calls when you use this structure field syntax. For more information, see Property Get and Set Methods.

Reference Properties Using Variables

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

object.(PropertyNameVar)

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