Documentation Center

  • Trials
  • Product Updates

validateattributes

Check validity of array

Syntax

  • validateattributes(A,classes,attributes) example
  • validateattributes(A,classes,attributes,argIndex) example
  • validateattributes(A,classes,attributes,funcName) example
  • validateattributes(A,classes,attributes,funcName,varName) example
  • validateattributes(A,classes,attributes,funcName,varName,argIndex) example

Description

example

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.

example

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

example

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

example

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

example

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

Examples

expand all

Validate the Size of an Array

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

A = rand(3,5,2);
validateattributes(A,classes,attributes)
Expected input to be of size 4x6x2 when it is actually size 3x5x2.

Because A did not match the specified attributes, MATLAB throws an error message.

Validate Array Monotonicity

Determine if an array is increasing or nondecreasing.

A = [1 5 8 2;
     9 6 9 4]
validateattributes(A, {'double'},{'nondecreasing'})
validateattributes(A, {'double'},{'increasing'})
A =

     1     5     8     2
     9     6     9     4

Since A is both increasing and nondecreasing, validateattributes does not throw an error for either attribute check.

Setting A(2,3) equal to A(1,3) results in a column that is no longer strictly increasing, so validateattributes throws an error.

A(2,3) = 8
validateattributes(A, {'double'},{'increasing'})
A =

     1     5     8     2
     9     6     8     4

Expected input to be increasing valued.

However, the columns remain nondecreasing since each column element is equal to or greater than the next. The following code does not throw an error.

validateattributes(A, {'double'},{'nondecreasing'})

Check the Attributes of a Complex Number

Assuming that a is to be the second input argument to a function, check that it is nonnegative.

a = complex(1,1);
validateattributes(a,{'numeric'},{'nonnegative'},2); 
Expected input number 2 to be nonnegative.

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

Ensure Array Values Are Within a Specified Range

Check that the values in an array are 8-bit integers between 0 and 10.

Assume that this code occurs in a function called Rankings.

classes = {'uint8','int8'};
attributes = {'>',0,'<',10};
funcName = 'Rankings';
A = int8(magic(4));

validateattributes(A,classes,attributes,funcName)
Error using Rankings
Expected input to be an array with all of the values < 10.

Validate Function Input Parameters Using inputParser

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

Define the function.

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
end

Call the function with a nonnumeric third input.

myarea = findArea('rectangle',3,'x')
Error using findArea (line 10)
Argument 'dim2' failed validation with error:
Expected input to be one of these types:

double, single, uint8, uint16, uint32, uint64, int8, int16, int32, int64

Instead its type was char.

Validate Arguments of a Function

Check the inputs of a function and include information about the input name and position in generated error.

Define the function.

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)

Call the function without the shape input string.

vol = findVolume(10,7,4)
Error using findVolume
Expected input number 1, Shape, to be one of these types:

char

Instead its type was double.

Error in findVolume (line 2)
validateattributes(shape,{'char'},{'nonempty'},mfilename,'Shape',1)

The function name becomes part of the error identifier.

MException.last.identifier
ans =

MATLAB:findVolume:invalidType

Input Arguments

expand all

A — Inputany type of array

Input, specified as any type of array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct | cell | function_handle
Complex Number Support: Yes

classes — Valid data typescell array of strings

Valid data types, specified as a cell array of strings. Each string can be the name of any built-in or custom class, including:

'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'function handle

'numeric'Any data type for which the isa(A,'numeric') function returns true, including int8, int16, int32, int64, uint8, uint16, uint32, uint64, single, or double
'<class_name>'Any other class name

Data Types: cell

attributes — Valid attributescell array of strings

Valid attributes, specified as a cell array of 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
'3d'Array with three or fewer dimensions
'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. To skip checking a particular dimension, specify NaN for that dimension, such as [3,4,NaN,2].
'numel', NArray with N elements
'ncols', NArray with N columns
'nrows', NArray with N rows
'ndims', NN-dimensional array
'square'Square matrix; in other words, a two-dimensional array with equal number of rows and columns
'diag'Diagonal matrix
'nonempty'No dimensions that equal zero
'nonsparse'Array that is not sparse

Attributes that specify valid ranges for values in A:

'>', NAll values greater than N
'>=', NAll values greater than or equal to N
'<', NAll values less than N
'<=', NAll values less than or equal to N

Attributes that check types of values in a numeric or logical array, A:

'binary'Array of ones and zeros
'even'Array of even integers (includes zero)
'odd'Array of odd integers
'integer'Array of integer values
'real'Array of real values
'finite'Array of finite values
'nonnan'No NaN (Not a Number) elements
'nonnegative'No elements less than zero
'nonzero'No elements equal to zero
'positive'No elements less than or equal to zero
'decreasing'Each element of a column is less than the previous element and no element is NaN
'increasing'Each element of a column is greater than the previous element and no element is NaN
'nondecreasing'Each element of a column is greater than or equal to the previous element and no element is NaN
'nonincreasing'Each element of a column is less than or equal to the previous element and no element is NaN

Data Types: cell

funcName — Name of function whose input you are validatingstring

Name of function whose input you are validating, specified as a string. If you specify an empty string, '', the validateattribute function ignores the funcName input.

Data Types: char

varName — Name of input variablestring

Name of input variable, specified as a string. If you specify an empty string, '', the validateattribute function ignores the varName input.

Data Types: char

argIndex — Position of input argumentpositive integer

Position of input argument, specified as a positive integer.

Data Types: double

See Also

| | | |

Was this topic helpful?