Main Content

## Property Validation Functions

### MATLAB Validation Functions

MATLAB® defines functions for use in property validation. These functions support common use patterns for validation and provide descriptive error messages. The following tables categorize the MATLAB validation functions and describe their use.

#### Numeric Value Attributes

Name

Meaning

Functions Called on Inputs

`mustBePositive(value)`

`value > 0`

`mustBeNonpositive(value)`

`value <= 0`

`mustBeNonnegative(value)`

`value >= 0`

`mustBeNegative(value)`

`value < 0`

`mustBeFinite(value)`

`value` has no `NaN` and no `Inf` elements.

`isfinite`

`mustBeNonNan(value)`

`value` has no `NaN` elements.

`isnan`

`mustBeNonzero(value)`

`value ~= 0`

`mustBeNonsparse(value)`

`value` is not sparse.

`issparse`

`mustBeSparse(value)`

`value` is sparse.

`issparse`

`mustBeReal(value)`

`value` has no imaginary part.

`isreal`

`mustBeInteger(value)`

`value == floor(value)`

`mustBeNonmissing(value)`

`value` cannot contain missing values.

`ismissing`

#### Comparison with Other Values

Name

Meaning

Functions Called on Inputs

`mustBeGreaterThan(value,c)`

`value > c`

`mustBeLessThan(value,c)`

`value < c`

`mustBeGreaterThanOrEqual(value,c)`

`value >= c`

`mustBeLessThanOrEqual(value,c)`

`value <= c`

#### Data Types

Name

Meaning

Functions Called on Inputs

`mustBeA(value,classnames)`

`value` must be of specific class.

Uses class definition relationships

`mustBeNumeric(value)`

`value` must be numeric.

`isnumeric`

`mustBeNumericOrLogical(value)`

`value` must be numeric or logical.

`mustBeFloat(value)`

`value` must be floating-point array.

`isfloat`

`mustBeUnderlyingType(value,typename)`

`value` must have specified underlying type.

`isUnderlyingType`

#### Size

Name

Meaning

Functions Called on Inputs

`mustBeNonempty(value)`

`value` is not empty.

`isempty`

`mustBeScalarOrEmpty(value)``value` must be a scalar or be empty.
`mustBeVector(value)``value` must be a vector.

`isvector`

#### Membership and Range

Name

Meaning

Functions Called on Inputs

`mustBeMember(value,S)`

`value` is an exact match for a member of `S`.

`ismember`

`mustBeInRange(value,lower,upper,boundflags)``value` must be within range.

#### Text

Name

Meaning

Functions Called on Inputs

`mustBeFile(path)`

`path` must refer to a file.

`isfile`

`mustBeFolder(folder)``path` must refer to a folder.

`isfolder`

`mustBeNonzeroLengthText(value)`

`value` must be a piece of text with nonzero length.

Not applicable

`mustBeText(value)`

`value` must be a string array, character vector, or cell array of character vectors.

Not applicable

`mustBeTextScalar(value)`

`value` must be a single piece of text.

Not applicable
`mustBeValidVariableName(varname)``varname` must be a valid variable name.

`isvarname`

### Validate Property Using Functions

Use property validation functions in class definitions to impose specific restrictions on property values. A validation function accepts a potential property value as an argument and issues an error if the value does not meet the specific requirement imposed by the function.

During the validation process, MATLAB passes the value to each validation function listed in the class definition. MATLAB calls each function from left to right and throws the first error encountered. The value passed to the validation functions is the result of any conversion applied by the class and size specifications. For more information on class and size validation, see Property Class and Size Validation.

For a list of MATLAB validation functions, see MATLAB Validation Functions.

#### Validation Function Syntax

Specify validation functions as a comma-separated list of function names or function calls with arguments, enclosed in braces.

```classdef MyClass properties Prop {fcn1,fcn2} = defaultValue end end```

MATLAB passes the potential property value to the validation function implicitly. However, if the validation function requires input arguments in addition to the potential property value, then you must include both the property and the additional arguments. Additional arguments must be literal values and cannot reference variables. Literal values are nonsymbolic representations, such as numbers and text.

For example, consider the function `mustBeGreaterThan`. It requires a limiting value as an input parameter. This validation function requires that a property value must be greater than this limiting value.

Pass the property as the first argument. Use the property name, but do not enclose the name in quotation marks. This property definition restricts `Prop` to values greater than `10`.

```properties Prop {mustBeGreaterThan(Prop,10)} end ```

#### Using Validation Functions

The following class specifies validation functions for each property.

• `Data` must be numeric and finite.

• `Interp` must be one of the three options listed. Specify a default value for this property to satisfy this requirement.

```classdef ValidatorFunction properties Data {mustBeNumeric, mustBeFinite} Interp {mustBeMember(Interp,{'linear','cubic','spline'})} = 'linear' end end```

Creating a default object of the class shows the initial values.

`a = ValidatorFunction`
```a = ValidatorFunction with properties: Data: [] Interp: 'linear'```

Assigning values to properties calls the validation functions.

`a.Data = 'cubic'`
```Error setting property 'Data' of class 'ValidatorFunction': Value must be numeric.```

Because the `Data` property validation does not include a numeric class, there is no conversion of the `char` vector to a numeric value. If you change the validation of the `Data` property to specify the class as `double`, MATLAB converts the `char` vector to a `double` array.

```properties Data double {mustBeNumeric, mustBeFinite} end ```

The assignment to the `char` vector does not produce an error because MATLAB converts the `char` vector to class `double`.

```a.Data = 'cubic' ```
```a = ValidatorFunction with properties: Data: [99 117 98 105 99] Interp: 'linear'```

Assignment to the `Interp` property requires an exact match.

```a = ValidatorFunction; a.Interp = 'cu' ```
```Error setting property 'Interp' of class 'ValidatorFunction': Value must be a member of this set linear cubic spline```

Using an enumeration class provides inexact matching and case insensitivity.

#### Enumeration Class for Inexact Matching

Property validation using an enumeration class provides these advantages:

• Inexact, case-insensitive matching for unambiguous char vectors or string scalars

• Conversion of inexact matches to correct values

For example, suppose that you define the `InterpMethod` enumeration class for the `Interp` property validation.

```classdef InterpMethod enumeration linear cubic spline end end```

Change the `Interp` property validation to use the `InterpMethod` class.

```classdef ValidatorFunction properties Data {mustBeNumeric, mustBeFinite} Interp InterpMethod end end```

Assign a value matching the first few letters of `'cubic'`.

```a = ValidatorFunction; a.Interp = 'cu'```
```a = ValidatorFunction with properties: Data: [] Interp: cubic```

### Define Validation Functions

Validation functions are ordinary MATLAB functions that are designed for the specific purpose of validating property and function argument values. Functions used to validate properties:

• Accept the potential property value as an input argument

• Do not return values

• Display error messages if the validation fails

Creating your own validation function is useful when you want to provide specific validation that is not available using the MATLAB validation functions. You can create local functions within the class file or place the function on the MATLAB path to be available for use in any class.

For example, the `ImgData` class uses a local function to define a validator that restricts the `Data` property to only `uint8` or `uint16` values, excluding subclasses and not allowing conversion from other numeric classes. The predefined validation function `mustBeInRange` restricts the range of allowed values.

```classdef ImgData properties Data {mustBeImData(Data),mustBeInRange(Data,0,255)} = uint8(0) end end function mustBeImData(a) if ~(isa(a,'uint8') || isa(a,'uint16')) error("Value of Data property must be uint8 or uint16 data.") end end```

When you create an instance of the `ImgData` class, MATLAB validates that the default value is a `uint8` or `uint16` value, in the range `0...255`, and not empty. Note that the default value must satisfy the validation requirements like any other value assigned to the property.

`a = ImgData`
```a = ImgData with properties: Data: 0```

Property assignment invokes the validators in left-to-right order. Assigning a `char` vector to the `Data` property causes an error thrown by `mustBeImData`.

`a.Data = 'red';`
```Error setting property 'Data' of class 'ImgData'. Value of Data property must be uint8 or uint16 data.```

Assigning a numeric value that is out of range causes an error thrown by `mustBeInRange`.

`a.Data = uint16(312);`
```Error setting property 'Data' of class 'ImgData'. Value must be greater than or equal to 0, and less than or equal to 255.```

For related functions, see `mustBeInteger`, `mustBeNumeric`, and `mustBePositive`.