Documentation

Assignment and Size Validation

This class defines the size of the Location property as 1-by-3. Any value assigned to this property must conform to that size or must be convertible to that size.

classdef ValidateProps
   properties
      Location(1,3)
   end
end

The implicit default value assigned by MATLAB, [0 0 0], conforms to the specified size:

a = ValidateProps

a = 

  ValidateProps with properties:

    Location: [0 0 0]

MATLAB applies scalar expansion when you assign a scalar the Location property.

a = ValidateProps;
a.Location = 1

a = 

  ValidateProps with properties:

    Location: [1 1 1]

MATLAB converts columns to rows to match the size specification:

col = [1;1;1]

col =

     1
     1
     1

a.Location = col

a = 

  ValidateProps with properties:

    Location: [1 1 1]

Colon in Size Specification

A colon in the size specification indicates that the corresponding dimension can have any length. For example, you can assign a value of any length to the Label property in this class.

classdef ValidateProps
   properties
      Label(1,:)
   end
end

a = ValidateProps;
a.Label = 'Click to Start'

a = 

  ValidateProps with properties:

    Label: 'Click to Start'

Assignment to a property that defines size validation follows the same rules as the equivalent indexed array assignment. For information on indexing behavior of multidimensional arrays, see Compatible Array Sizes for Basic Operations.

Using Class Validation

The PropsWithClass class defines two properties with class definitions:

classdef PropsWithClass
   properties
      Number double
      Today char = date
   end
end

Create an object of the PropsWithClass class.

p = PropsWithClass

p = 

  PropsWithClass with properties:

    Number: []
     Today: '10-Sep-2016'

MATLAB performs conversions from any compatible class to the property class. For example, assign a datetime array to the Today property.

p.Today = [datetime('now'),datetime('tomorrow')];
disp(class(p.Today))

ans =

char

Because the datetime class has a char converter, you can assign a datetime array to the Today property.

Assigning an incompatible value to a property that uses class validation causes an error.

p.Number = datetime('now');

Error setting property 'Number' of class 'PropsWithClass':
Invalid data type. Value must be double or be convertible to double.

User-Defined Class for Validation

You can define a class to control the values assigned to a property. Enumeration classes enable users to set property values to character vectors or string scalars with inexact name matching.

For example, suppose that there is a class that represents a three-speed mechanical pump. You can define an enumeration class to represent the three flow rates.

classdef FlowRate < int32
   enumeration
      Low    (10)
      Medium (50)
      High   (100)
   end
end

The Pump class has a method to return the current flow rate in gallons per minute. Define the Speed property as a FlowRate class.

classdef Pump
   properties
      Speed FlowRate
   end
   methods
      function getGPM(p)
         if isempty(p.Speed)
            gpm = 0;
         else
            gpm = int32(p.Speed);
         end
         fprintf('Flow rate is: %i GPM\n',gpm);
      end
   end
end

Users can set the Speed property using inexact text.

p = Pump;
p.Speed = 'm'

p = 

  Pump with properties:

    Speed: Medium

The numerical value is available from the property.

getGPM(p)

Flow rate is: 50 GPM

For information about enumeration classes, see Define Enumeration Classes.

Integer Class Validation

MATLAB supports several integer classes (see Integers). However, restricting a property to an integer class can result in integer overflow. The resulting value can saturate at the maximum or minimum value in the integer’s range.

When integer overflow occurs, the value that is assigned to a property can be a value that is different from the value from the right side of the assignment statement.

For example, suppose that you want to restrict a property value to a scalar uint8.

classdef IntProperty
   properties
      Value(1,1) uint8
   end
end

Assigning a numeric value to the Value property effectively casts the numeric value to uint8, but does not result in an error for out-of-range values.

a = IntProperty;
a.Value = -10;
disp(a.Value)

0

Assignment to the Value property is equivalent to indexed assignment of an array. If the assigned value is out of the range of values that uint8 can represent, MATLAB sets the value to the closest value that it can represent using uint8.

a = uint8.empty;
a(1) = -10

a =

  uint8

   0

To avoid the potential for integer overflow, use a combination of validation functions that restrict the value to the intended range instead of an integer class.

classdef IntProperty
   properties
      Value(1,1) {mustBeInteger, mustBeNonnegative,...
         mustBeLessThan(Value,256)}
   end
end

Because there is no conversion of the assigned value by the uint8 class, the validators catch out of range values and throw an appropriate error.

a = IntProperty;
a.Value = -10;

Error setting property 'Value' of class 'IntProperty':
Value must be nonnegative.

Implicit Default Values

MATLAB defines a default value implicitly if you do not specify a default value in the class definition. This table shows how size and class determine the implicit default value of MATLAB classes.

To determine the implicit default value for nonzero and explicit size specifications, MATLAB calls the default class constructor and builds an array of the specified size using the instance returned by the constructor call. If the class does not support a default constructor (that is, a constructor called with no arguments), then MATLAB throws an error when instantiating the class containing the validation.

If the specified size has any zero or unrestricted (:) dimensions, MATLAB creates a default value that is an empty array with the unrestricted dimension set to zero.

For heterogeneous arrays, MATLAB calls the getDefaultScalarElement method to get the default object.