Argument Validation Functions

MATLAB defines functions for use in argument validation. These functions support common use patterns for validation and provide descriptive error messages. This table lists the MATLAB validation functions, their meanings, and the MATLAB functions used by them.

Name

Meaning

Functions Called on Inputs

mustBePositive(value)

value > 0

gt, isreal, isnumeric, islogical

mustBeNonpositive(value)

value <= 0

ge, isreal, isnumeric, islogical

mustBeFinite(value)

value has no NaN and no Inf elements.

isfinite

mustBeNonNan(value)

value has no NaN elements.

isnan

mustBeNonnegative(value)

value >= 0

ge, isreal, isnumeric, islogical

mustBeNegative(value)

value < 0

lt, isreal, isnumeric, islogical

mustBeNonzero(value)

value ~= 0

eq, isnumeric, islogical

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

mustBeNonempty(value)

value is not empty.

isempty

mustBeNonsparse(value)

value has no sparse elements.

issparse

mustBeNumeric(value)

value is numeric.

isnumeric

mustBeNumericOrLogical(value)

value is numeric or logical.

isnumeric, islogical

mustBeReal(value)

value has no imaginary part.

isreal

mustBeInteger(value)

value == floor(value)

isreal, isfinite, floor, isnumeric, islogical

mustBeMember(value,S)

value is an exact match for a member of S.

ismember

Define Validation Functions

Validation functions are ordinary MATLAB® functions that are designed for validating input values. Functions used for validation must do these things:

  • Accept the potential value as an input argument.

  • Not return values

  • Throw an error 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 them as local functions within the function file or place them 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 ImgData function uses a local function to define a validator that restricts the Data input to a specific range of numeric values. The mustBeNumeric validator is an existing function.

function ImgData(Data)
    arguments
        Data {mustBeNumeric, mustBeInRange(Data,[0,255])}
    end

    % Function code
    imagesc(Data)
end

% Custom validation function
function mustBeInRange(arg,b)
    if any(arg(:) < b(1)) || any(arg(:) > b(2))
        error(['Value assigned to Data is not in range ',...
            num2str(b(1)),'...',num2str(b(2))])
    end
end

The Data input argument can be a numeric array of any size with values in the range 0–255. If values do not satisfy these requirements, MATLAB throws an error.

ImgData(randi(300,10,10))
Error using ImgData
Invalid input argument at position 1. Value assigned to Data is not in range 0...255

Related Topics