Main Content

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.

Related Topics