Property Syntax - MATLAB & Simulink (original) (raw)
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 theSetAccess attribute set to private. This attribute setting means that the property values can be set only by members of thePrivateProps 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 privateSetAccess, 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 asdouble. The value must be the specified class or a class that can be converted. For example, a property that specifiesdoubleaccepts values of typesingleand converts them todouble. 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 asmustBePositiveandmustBeScalarOrEmpty. 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, seeProperty 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, theRestrictedByClass property uses class validation only, whileRestrictedByFunction 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.
Assign values to properties by putting the property reference on the left side of the equal sign.
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
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 orchar variable using an expression of the form:
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 theKeyType property.
PropName = "KeyType"; function o = getPropValue(obj,PropName) o = obj.(PropName); end