Use Validation Functions to Avoid Unwanted Class and Size Conversions

When an argument value that is passed to a function does not match the class and size required by the validation, MATLAB^® converts the value to the declared class and size when conversion is possible. To avoid the standard conversions performed by MATLAB from argument validation, use validation functions instead of class and size restrictions. Calls to validation functions do not return values and cannot change the value of the argument.

For example, this function restricts the first input to a two-dimensional array of any size that is of class double. The second input must be a 5-by-3 array of any class.

function f(a,b)
    arguments
        a (:,:) double
        b (5,3)
    end
    % Function code
end

Because of standard MATLAB type conversion and scalar expansion, you can call this function with the following inputs and not receive a validation error.

f('character vector',144)

By default, MATLAB converts the elements of the character vector to their equivalent numeric value and applies scalar expansion to create a 5-by-3 array from the scalar value 144.

Using specialized validation functions can provide more specific argument validation. For example, this function defines specialized validation functions that it uses in place of the class and size specifications for the first and second arguments. These local functions enable you to avoid input value conversions.

• mustBeOfClass restricts the input to a specific class without allowing conversion or subclasses. For a related function, see mustBeA.

• mustBeEqualSize restricts two inputs to be of equal size without allowing scalar expansion. For a related function, see mustBeScalarOrEmpty.

• mustBeDims restricts the input to be of a specified dimension without allowing transposition or scalar expansion. For a related function, see mustBeVector.

function fCustomValidators(a,b)
    arguments
        a {mustBeOfClass(a,'double'), mustBeDims(a,2)}
        b {mustBeEqualSize(b,a)}
    end
    % Function code
end

% Custom validator functions
function mustBeOfClass(input,className)
    % Test for specific class name
    cname = class(input);
    if ~strcmp(cname,className)
        eid = 'Class:notCorrectClass';
        msg = 'Input must be of class %s.';
        error(eid,msg,className);
    end
end

function mustBeEqualSize(a,b)
    % Test for equal size
    if ~isequal(size(a),size(b))
        eid = 'Size:notEqual';
        msg = 'Inputs must have equal size.';
        error(eid,msg)
    end
end

function mustBeDims(input,numDims)
    % Test for number of dimensions    
    if ~isequal(length(size(input)),numDims)
        eid = 'Size:wrongDimensions';
        msg = ['Input must have ',num2str(numDims),' dimension(s).'];
        error(eid,msg,numDims)
    end
end

Use fCustomValidators to test the mustBeOfClass function. The first argument is not of class double, so the function returns an error.

fCustomValidators('character vector',144)

Error using fCustomValidators
 fCustomValidators('character vector',144)
                   ↑
Invalid argument at position 1. Input must be of class double.

In this call, the number of dimensions of the first input is wrong, so the validation function returns a custom error message.

fCustomValidators(ones(2,2,4),144)

Error using fCustomValidators
 fCustomValidators(ones(2,2,4),144)
                   ↑
Invalid argument at position 1. Input must have 2 dimension(s).

The mustBeEqualSize validator function checks to see if the inputs are of the same size.

fCustomValidators(ones(2,2),144)

Error using fCustomValidators
 fCustomValidators(ones(2,2),144)
                             ↑
Invalid argument at position 2. Inputs must have equal size.

For related predefined validation functions, see mustBeA, mustBeFloat, and mustBeVector.