validateattributes - Check validity of array

Syntax

Description

validateattributes(A,classes,attributes) validates that array A belongs to at least one of the specified classes (or its subclass) and has all of the specified attributes. If A does not meet the criteria, MATLAB throws an error and displays a formatted error message. Otherwise, validateattributes completes without displaying any output.

validateattributes(A,classes,attributes,argIndex) includes the position of the input in your function argument list as part of any generated error messages.

validateattributes(A,classes,attributes,funcName) includes the specified function name in generated error identifiers.

validateattributes(A,classes,attributes,funcName,varName) includes the specified variable name in generated error messages.

validateattributes(A,classes,attributes,funcName,varName,argIndex) includes the specified information in generated error messages or identifiers.

Input Arguments

A	Any type of array.
classes	Cell array of strings that specify valid data types for array A. Each string can be the name of any MATLAB built-in or custom class, including: 'numeric' Any value for which the isnumeric function returns true, including int8, int16, int32, int64, uint8, uint16, uint32, uint64, single, or double. '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' Structure array. 'cell' Cell array. 'function_handle' Scalar function handle.
attributes	Cell array that contains descriptions of valid attributes for array A. All attribute names are strings. Some attributes also require numeric values, such as attributes that specify the size or number of elements of A. For these attributes, the numeric value or vector must immediately follow the attribute name string in the cell array. Attributes that describe the size and shape of array A: '2d' Two-dimensional array, including scalars, vectors, matrices, and empty arrays. 'column' Column vector, N-by-1. 'row' Row vector, 1-by-N. 'scalar' Scalar value, 1-by-1. 'vector' Row or column vector, or a scalar value. 'size', [d1,...,dN] Array with dimensions d1-by-...-by-dN. If you do not want to check a particular dimension, specify NaN for that dimension, such as [3,4,NaN,2]. 'numel', N Array with N elements. 'ncols', N Array with N columns. 'nrows', N Array with N rows. 'nonempty' No dimensions equal zero. 'nonsparse' Array that is not sparse. Attributes that specify valid ranges for values in A: '>', N All values are greater than N. '>=', N All values are greater than or equal to N. '<', N All values are less than N. '<=', N All values are less than or equal to N. Attributes that check types of values in A, where A is a numeric or logical array: 'binary' Array of ones and zeros. 'even' All elements are even integers (includes zero). 'odd' All elements are odd integers. 'integer' All elements are integer-valued. 'real' All elements are real. 'finite' All elements are finite. 'nonnan' No elements equal to NaN (Not a Number). 'nonnegative' All elements are greater than or equal to zero. 'nonzero' All elements are less than or greater than zero. 'positive' All elements are greater than zero.
funcName	String that specifies the name of the function whose input you are validating. If you specify an empty string, '', the validateattribute function ignores the funcName input.
varName	String that specifies the name of the input variable. If you specify an empty string, '', the validateattribute function ignores the varName input.
argIndex	Positive integer that specifies the position of the input argument.

Examples

Check the size of an array.

classes = {'numeric'};
attributes = {'size',[4,6,2]};

A = rand(3,5,2);
validateattributes(A,classes,attributes)

Because A is not of the expected size, validateattributes throws an error and displays this message:

Expected input to be of size 4x6x2 when it is actually size 3x5x2.

Check that the values in an array are 8-bit integers within a specific range.

classes = {'uint8','int8'};
attributes = {'>',0,'<',70};

A = randi(100,4,6,2,'uint8');
validateattributes(A,classes,attributes)

If some of the values are outside the range, MATLAB displays this error message:

Expected input to be an array with all of the values < 70.

Check the attributes of a complex number.

a = complex(1,1);
validateattributes(a,{'numeric'},{'nonnegative'}); 

MATLAB displays this error message:

Expected input to be nonnegative.

Because complex numbers lack a well-defined ordering in the complex plane, validateattributes does not recognize them as positive or negative.

Check inputs to a custom function, and include information about the input name and position in generated errors.

function v = findVolume(shape,ht,wd,ln)

   validateattributes(shape,{'char'},{'nonempty'},mfilename,'Shape',1)
   validateattributes(ht,{'numeric'},{'nonempty'},mfilename,'Height',2)
   validateattributes(wd,{'numeric'},{'nonempty'},mfilename,'Width',3)
   validateattributes(ln,{'numeric'},{'nonempty'},mfilename,'Length',4)

When you call the function without the shape input string,

vol = findVolume(10,7,4)

MATLAB displays

Error using findVolume
Expected input number 1, Shape, to be one of these types:

  char

Instead its type was double.

The function name is part of the error identifier, so

MException.last.identifier

returns

ans =
    MATLAB:findVolume:invalidType

Create a custom function that checks input parameters with inputParser, and use validateattributes as the validating function for the addRequired and addOptional methods.

function a = findArea(shape,dim1,varargin)
   p = inputParser;
   charchk = {'char'};
   numchk = {'numeric'};
   nempty = {'nonempty'};

   addRequired(p,'shape',@(x)validateattributes(x,charchk,nempty));
   addRequired(p,'dim1',@(x)validateattributes(x,numchk,nempty));
   addOptional(p,'dim2',1,@(x)validateattributes(x,numchk,nempty));
   parse(p,shape,dim1,varargin{:});
 
   switch shape
      case 'circle'
         a = pi * dim1.^2;
      case 'rectangle'
         a = dim1 .* p.Results.dim2;
   end

If you call the function with a nonnumeric third input,

myarea = findArea('rectangle',3,'x')

MATLAB displays

Error using findArea
Argument 'dim2' failed validation with error:
Expected input to be one of these types:

  numeric

Instead its type was char.

See Also

inputParser | is* | isa | isnumeric | validatestring

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS