Argument Validation Functions

MATLAB defines functions for use in argument 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`	`gt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonpositive(value)`	`value <= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNonnegative(value)`	`value >= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNegative(value)`	`value < 0`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeFinite(value)`	`value` has no `NaN` and no `Inf` elements.	`isfinite`
`mustBeNonNan(value)`	`value` has no `NaN` elements.	`isnan`
`mustBeNonzero(value)`	`value ~= 0`	`eq`, `isnumeric`, `islogical`
`mustBeNonsparse(value)`	`value` has no sparse elements.	`issparse`
`mustBeReal(value)`	`value` has no imaginary part.	`isreal`
`mustBeInteger(value)`	`value == floor(value)`	`isreal`, `isfinite`, `floor`, `isnumeric`, `islogical`
`mustBeNonmissing(value)`	`value` cannot contain missing values.	`ismissing`

Comparison with Other Values

Name	Meaning	Functions Called on Inputs
`mustBeGreaterThan(value,c)`	`value > c`	`gt`, `isscalar`, `isreal`, `isnumeric`, `islogical`
`mustBeLessThan(value,c)`	`value < c`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeGreaterThanOrEqual(value,c)`	`value >= c`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeLessThanOrEqual(value,c)`	`value <= c`	`le`, `isreal`, `isnumeric`, `islogical`

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.	`isnumeric`, `islogical`
`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.	`isscalar`, `isempty`
`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.	`gt`, `ge`, `lt`, `le`

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`

Define Validation Functions

Validation functions are MATLAB functions that check requirements on values entering functions or properties. Validation functions determine when to throw errors and what error messages to display.

Functions used for validation have these design elements:

Validation functions do not return outputs or modify program state. The only purpose is to check the validity of the input value.
Validation functions must accept the value being validated as an input argument. If the function accepts more than one input argument, the first input is the value to be validated.
Validation functions rely only on the inputs. No other values are available to the function.
Validation functions throw an error if the validation fails. Using throwAsCaller to throw exceptions avoids showing the validation function itself in the displayed error message.

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 a validation function as a local function within the function file or place it on the MATLAB path. To avoid a confluence of error messages, do not use function argument validation within user-defined validation functions.

For example, the mustBeRealUpperTriangular function restricts the input to real-valued, upper triangular matrices. The validation function uses the istriu and isreal functions.

function mustBeRealUpperTriangular(a)
    if ~(istriu(a) && isreal(a))
        eidType = 'mustBeRealUpperTriangular:notRealUpperTriangular';
        msgType = 'Input must be a real-valued, upper triangular matrix.';
        throwAsCaller(MException(eidType,msgType))
    end
end

If the input argument is not of the correct type, the function throws an error.

a = [1 2 3+2i; 0 2 3; 0 0 1];
mustBeRealUpperTriangular(a)

Input must be a real-valued, upper triangular matrix.

Documentation