validateattributes - Check validity of array

Syntax

validateattributes(A, classes, attributes) validateattributes(A, classes, attributes, position) validateattributes(A, classes, attributes, funcname) validateattributes(A, classes, attributes, funcname, varname) validateattributes(A, classes, attributes, funcname, varname, position)

Description

validateattributes(A, classes, attributes) validates that array A belongs to at least one of the classes specified by the classes input and has all of the attributes specified by the attributes input. If the validation succeeds, the command completes without displaying any output and without throwing an error. If the validation does not succeed, MATLAB issues a formatted error message.

The classes input is a cell array containing one or more strings from the Class Values table shown below.

The attributes input is a cell array containing one or more strings from the Attribute Values table shown below. Size validation requires two inputs: the 'size' keyword and the length of each dimension (e.g., {'size', [4,3,7]}). Value range validation requires two inputs for each aspect of the range being validated (e.g., {'>', 10, '<=', 65}).

validateattributes(A, classes, attributes, position) validates array A and, if the validation fails, displays an error message that includes the position of the failing variable in the function argument list. The position input must be a positive integer.

validateattributes(A, classes, attributes, funcname) validates array A and, if the validation fails, displays an error message that includes the name of the function performing the validation (funcname). The funcname input must be a string.

validateattributes(A, classes, attributes, funcname, varname) validates array A and, if the validation fails, displays an error message that includes the name of the function performing the validation (funcname), and the name of the variable being validated (varname). The funcname and varname inputs must be strings enclosed in single quotation marks.

validateattributes(A, classes, attributes, funcname, varname, position) validates array A and, if the validation fails, displays an error message that includes the name of the function performing the validation (funcname), the name of the variable being validated (varname), and the position of this variable in the function argument list (position). The funcname and varname inputs must be strings enclosed in single quotation marks. The position input must be a positive integer.

Class Values

`classes` Argument	Contents of Array `A`
`'numeric'`	Any numeric value
`'single'`	Single-precision number
`'double'`	Double-precision number
`'int8'`	Signed 8-bit integer
`'int16'`	Signed 16-bit integer
`'int32'`	Signed 32-bit integer
`'int64'`	Signed 64-bit integer
`'uint8'`	Unsigned 8-bit integer
`'uint16'`	Unsigned 16-bit integer
`'uint32'`	Unsigned 32-bit integer
`'uint64'`	Unsigned 64-bit integer
`'logical'`	Logical `true` or `false`
'`'char'`	Character or string
`'struct'`	MATLAB structure
`'cell'`	Cell array
`'function_handle'`	Scalar function handle
class name	Object of any MATLAB class

Attribute Values

`attributes` Argument	Description of array `A`
`'>', N`	Array in which all values are greater than `N`.
`'>=', N`	Array in which all values are greater than or equal to `N`.
`'<', N`	Array in which all values are less than `N`.
`'<=', N`	Array in which all values are lass than or equal to `N`.
`'2d'`	Array having dimensions `M`-by-`N` (includes scalars, vectors, 2-D matrices, and empty arrays)
`'binary'`	Array of ones and zeros
`'column'`	Array having dimensions `N`-by-1
`'even'`	Numeric or logical array in which all elements are even (includes zero)
`'finite'`	Numeric array in which all elements are finite
`'integer'`	Numeric array in which all elements are integer-valued
`'nonempty'`	Array having no dimension equal to zero
`'nonnan'`	Numeric array in which there are no elements equal to NaN (Not a Number)
`'nonnegative'`	Numeric array in which all elements are zero or greater than zero
`'nonsparse'`	Array that is not sparse
`'nonzero'`	Numeric or logical array in which all elements are less than or greater than zero
`'odd'`	Numeric or logical array in which all elements are odd integers
`'positive'`	Numeric or logical array in which all elements are greater than zero
`'real'`	Numeric array in which all elements are real
`'row'`	Array having dimensions 1-by-`N`
`'scalar'`	Array having dimensions 1-by-1
`'size', [M,N,...]`	Array having dimensions `M`-by-`N`-by- `...`.
`'vector'`	Array having dimensions `N`-by-1 or 1-by-`N` (includes scalar arrays)

Numeric properties, such as positive and nonnan, do not apply to strings. If you attempt to validate numeric properties on a string, validateattributes generates an error.

Examples

Example 1

In this example, the empl_profile1 function compares the values passed in each argument to the specified classes and attributes and throws an error if they are not correct:

function empl_profile1(empl_id, empl_info, healthplan, ...
   vacation)
validateattributes(empl_id, {'numeric'}, ...
   {'integer', 'nonempty'});
validateattributes(empl_info, {'struct'}, {'vector'});
validateattributes(healthplan, {'cell', 'char'}, ...
   {'vector'});
validateattributes(vacation, {'numeric'}, ...
   {'nonnegative', 'scalar'});

Call the empl_profile1 function, passing the expected argument types, and the example completes without error:

empl_id = 51723;
empl_info.name = 'John Miller';  
empl_info.address = '128 Forsythe St.';
empl_info.town = 'Duluth';  empl_info.state='MN';

empl_profile1(empl_id, empl_info, 'HCP Medical Plus', 14.3)

If you accidentally pass the argument values out of their correct sequence, MATLAB throws an error in response to the first argument that is not a match:

empl_profile1(empl_id, empl_info, 14.3, 'HCP Medical Plus')

??? Error using ==> empl_profile1 at 6
Expected input to be one of these types:

  cell, char

Instead its type was double.

Example 2

Write a new function empl_profile2 that displays the function name, variable name, and position of the argument:

function empl_profile2(empl_id, empl_info, healthplan, ...
   vacation)

validateattributes(empl_id, ...
   {'numeric'}, {'integer', 'nonempty'}, ...
   mfilename, 'Employee Identification', 1);

validateattributes(empl_info, ...
   {'struct'}, {'vector'}, ...
   mfilename, 'Employee Info', 2);

validateattributes(healthplan, ...
   {'cell', 'char'}, {'vector'}, ...
   mfilename, 'Health Plan', 3);

validateattributes(vacation, ...
   {'numeric'}, {'nonnegative', 'scalar'}, ...
   mfilename, 'Vacation Accrued', 4);

Call empl_profile2 with the argument values out of sequence. MATLAB throws an error that includes the name of the function validating the attributes, the name of the variable that was in error, and its position in the input argument list:

??? Error using ==> empl_profile2
Expected input number 3, Health Plan, to be one of 
these types:

  cell, char

Instead its type was double.

Error in ==> empl_profile2 at 12
validateattributes(healthplan, ...

Example 3

Write a new function empl_profile3 that checks the input parameters with inputParser. Use validateattributes as the validating function for the inputParser methods:

function empl_profile3(empl_id, varargin) 
p = inputParser;   

% Validate the input arguments.
addRequired(p, 'empl_id', ...
   @(x)validateattributes(x, {'numeric'}, {'integer'})); 
addOptional(p, 'empl_info', '', ...
   @(x)validateattributes(x, {'struct'}, {'nonempty'})); 
addParamValue(p, 'health', 'HCP Medical Plus', ...
   @(x)validateattributes(x, {'cell', 'char'}, ...
   {'vector'}));
addParamValue(p, 'vacation', [], ...
   @(x)validateattributes(x, {'numeric'}, ...
   {'nonnegative', 'scalar'}));  
parse(p, empl_id, varargin{:}); 
p.Results

Call empl_profile3 using appropriate input arguments:

empl_info.name = 'John Miller';  
empl_info.address = '128 Forsythe St.';
empl_info.town = 'Duluth';  empl_info.state='MN';

empl_profile3(51723, empl_info, 'vacation', 14.3)

ans = 
     empl_id: 51723
   empl_info: [1x1 struct]
      health: 'HCP Medical Plus'
    vacation: 14.3000

Call empl_profile3 using a character string where a structure is expected:

empl_profile3(51723, empl_info.name,  'vacation', 14.3)

??? Error using ==> empl_profile3 at 12
Argument 'empl_info' failed validation with error:
Expected input to be one of these types:

  struct

Instead its type was char.

Example 4

Create a 4-by-2-by-6 array and then validate its size:

x = rand(4,2,6);

validateattributes(x, {'numeric'}, {'size', [4,2,6]});

Create an array of integers between 50 and 200 and then validate that these values are within the intended range:

y = uint8(50:10:200);

validateattributes(y, {'uint8'}, {'>=', 50, '<=', 200})

This next statement fails for y(end):

validateattributes(y, {'uint8'}, {'>=', 50, '<', 200})
??? Expected input to be an array with all of the values < 200.

Example 5

Generate a new array z and validate that it is a 4-by-2-by-6 nonsparse array of class double, with all elements being between 0.005 and 50, inclusive:

z = rand(4,2,6) * 50;

validateattributes(z, {'numeric', 'double'}, ...
   {'<', 50, 'size', [4 2 6], 'nonsparse', '>=', .005});

There are several things to note in the above statement:

All class arguments are enclosed in just one set of curly braces {}. All attribute arguments the same way.
The placement of the <, <=, >, and >= arguments in the argument list is unimportant. However, you must immediately follow any of these arguments with the numeric argument it relates to.
The placement of the 'size' argument in the argument list is unimportant. However, you must immediately follow this argument with the numeric vector argument it relates to.

If you add to this a requirement that z be two-dimensional, validateattributes throws an error because z has three dimensions:

validateattributes(z, {'double'}, ...
   {z, '<', 50, 'size', [4 2 6], '2d', 'positive', '>', 0});
Warning: Failed to find attribute in list. 
??? Expected input to be two-dimensional.