11.9.2 Validating the type of Arguments

Besides the number of arguments, inputs can be checked for various properties. validatestring is used for string arguments and validateattributes for numeric arguments.

: validstr = validatestring (str, strarray)

: validstr = validatestring (str, strarray, funcname)

: validstr = validatestring (str, strarray, funcname, varname)

: validstr = validatestring (…, position)

Verify that str is an element, or substring of an element, in strarray.

When str is a character string to be tested, and strarray is a cellstr of valid values, then validstr will be the validated form of str where validation is defined as str being a member or substring of validstr. This is useful for both verifying and expanding short options, such as "r", to their longer forms, such as "red". If str is a substring of validstr, and there are multiple matches, the shortest match will be returned if all matches are substrings of each other. Otherwise, an error will be raised because the expansion of str is ambiguous. All comparisons are case insensitive.

The additional inputs funcname, varname, and position are optional and will make any generated validation error message more specific.

Examples:

validatestring ("r", {"red", "green", "blue"})
⇒ "red"

validatestring ("b", {"red", "green", "blue", "black"})
⇒ error: validatestring: multiple unique matches were found for 'b':
   blue, black

See also: strcmp, strcmpi, validateattributes, inputParser.

: validateattributes (A, classes, attributes)

: validateattributes (A, classes, attributes, arg_idx)

: validateattributes (A, classes, attributes, func_name)

: validateattributes (A, classes, attributes, func_name, arg_name)

: validateattributes (A, classes, attributes, func_name, arg_name, arg_idx)

Check validity of input argument.

Confirms that the argument A is valid by belonging to one of classes, and holding all of the attributes. If it does not, an error is thrown, with a message formatted accordingly. The error message can be made further complete by the function name fun_name, the argument name arg_name, and its position in the input arg_idx.

classes must be a cell array of strings (an empty cell array is allowed) with the name of classes (remember that a class name is case sensitive). In addition to the class name, the following categories names are also valid:

"float"

Floating point value comprising classes "double" and "single".

"integer"

Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.

"numeric"

Numeric value comprising either a floating point or integer value.

attributes must be a cell array with names of checks for A. Some of them require an additional value to be supplied right after the name (see details for each below).

"<="

All values are less than or equal to the following value in attributes.

"<"

All values are less than the following value in attributes.

">="

All values are greater than or equal to the following value in attributes.

">"

All values are greater than the following value in attributes.

"2d"

A 2-dimensional matrix. Note that vectors and empty matrices have 2 dimensions, one of them being of length 1, or both length 0.

"3d"

Has no more than 3 dimensions. A 2-dimensional matrix is a 3-D matrix whose 3rd dimension is of length 1.

"binary"

All values are either 1 or 0.

"column"

Values are arranged in a single column.

"decreasing"

No value is NaN, and each is less than the preceding one.

"diag"

Value is a diagonal matrix.

"even"

All values are even numbers.

"finite"

All values are finite.

"increasing"

No value is NaN, and each is greater than the preceding one.

"integer"

All values are integer. This is different than using isinteger which only checks its an integer type. This checks that each value in A is an integer value, i.e., it has no decimal part.

"ncols"

Has exactly as many columns as the next value in attributes.

"ndims"

Has exactly as many dimensions as the next value in attributes.

"nondecreasing"

No value is NaN, and each is greater than or equal to the preceding one.

"nonempty"

It is not empty.

"nonincreasing"

No value is NaN, and each is less than or equal to the preceding one.

"nonnan"

No value is a NaN.

"nonnegative"

All values are non negative.

"nonsparse"

It is not a sparse matrix.

"nonzero"

No value is zero.

"nrows"

Has exactly as many rows as the next value in attributes.

"numel"

Has exactly as many elements as the next value in attributes.

"odd"

All values are odd numbers.

"positive"

All values are positive.

"real"

It is a non-complex matrix.

"row"

Values are arranged in a single row.

"scalar"

It is a scalar.

"size"

Its size has length equal to the values of the next in attributes. The next value must is an array with the length for each dimension. To ignore the check for a certain dimension, the value of NaN can be used.

"square"

Is a square matrix.

"vector"

Values are arranged in a single vector (column or vector).

See also: isa, validatestring, inputParser.

As alternatives to validateattributes there are several shorter convenience functions to check for individual properties.

: mustBeFinite (x)

Require that input x is finite.

Raise an error if any element of the input x is not finite, as determined by isfinite (x).

See also: mustBeNonNan, isfinite.

: mustBeGreaterThan (x, c)

Require that input x is greater than c.

Raise an error if any element of the input x is not greater than c, as determined by x > c.

See also: mustBeGreaterThanOrEqual, mustBeLessThan, gt.

: mustBeGreaterThanOrEqual (x, c)

Require that input x is greater than or equal to c.

Raise an error if any element of the input x is not greater than or equal to c, as determined by x >= c.

See also: mustBeGreaterThan, mustBeLessThanOrEqual, ge.

: mustBeInteger (x)

Require that input x is integer-valued (but not necessarily integer-typed).

Raise an error if any element of the input x is not a finite, real, integer-valued numeric value, as determined by various checks.

See also: mustBeNumeric.

: mustBeLessThan (x, c)

Require that input x is less than c.

Raise an error if any element of the input x is not less than c, as determined by x < c.

See also: mustBeLessThanOrEqual, mustBeGreaterThan, lt.

: mustBeLessThanOrEqual (x, c)

Require that input is less than or equal to a given value.

Raise an error if any element of the input x is not less than or equal to c, as determined by x <= c.

See also: mustBeLessThan, mustBeGreaterThanOrEqual, le.

: mustBeMember (x, valid)

Require that input x is a member of a set of given valid values.

Raise an error if any element of the input x is not a member of the set valid, as determined by ismember (x).

Programming Note: char inputs may behave strangely because of the interaction between chars and cellstrings when calling ismember on them. But it will probably "do what you mean" if you just use it naturally. To guarantee operation, convert all char arrays to cellstrings with cellstr.

See also: mustBeNonempty, ismember.

: mustBeNegative (x)

Require that input x is negative.

Raise an error if any element of the input x is not negative, as determined by x < 0.

See also: mustBeNonnegative.

: mustBeNonempty (x)

Require that input x is nonempty.

Raise an error if the input x is empty, as determined by isempty (x).

See also: mustBeMember, mustBeNonzero, isempty.

: mustBeNonNan (x)

Require that input x is non-NaN.

Raise an error if any element of the input x is NaN, as determined by isnan (x).

See also: mustBeFinite, mustBeNonempty, isnan.

: mustBeNonnegative (x)

Require that input x is not negative.

Raise an error if any element of the input x is negative, as determined by x >= 0.

See also: mustBeNonzero, mustBePositive.

: mustBeNonpositive (x)

Require that input x is not positive.

Raise an error if any element of the input x is positive, as determined by x <= 0.

See also: mustBeNegative, mustBeNonzero.

: mustBeNonsparse (x)

Require that input x is not sparse.

Raise an error if the input x is sparse, as determined by issparse (x).

See also: issparse.

: mustBeNonzero (x)

Require that input x is not zero.

Raise an error if any element of the input x is zero, as determined by x == 0.

See also: mustBeNonnegative, mustBePositive.

: mustBeNumeric (x)

Require that input x is numeric.

Raise an error if the input x is not numeric, as determined by isnumeric (x).

See also: mustBeNumericOrLogical, isnumeric.

: mustBeNumericOrLogical (x)

Require that input x is numeric or logical.

Raise an error if the input x is not numeric or logical, as determined by isnumeric (x) || islogical (x).

See also: mustBeNumeric, isnumeric, islogical.

: mustBePositive (x)

Require that input x is positive.

Raise an error if any element of the input x is not positive, as determined by x > 0.

See also: mustBeNonnegative, mustBeNonzero.

: mustBeReal (x)

Require that input x is real.

Raise an error if the input x is not real, as determined by isreal (x).

See also: mustBeFinite, mustBeNonNan, isreal.