validateattributes

Check validity of array

collapse all in page

Syntax

validateattributes(A,classes,attributes)

validateattributes(A,classes,attributes,argIndex)

validateattributes(A,classes,attributes,funcName)

validateattributes(A,classes,attributes,funcName,varName)

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

Description

validateattributes(A,classes,attributes) validates that array A belongs to at least one of the specified classes (or its subclass) and has all the specified attributes. If A does not meet the criteria, then 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.

example

Examples

collapse all

Validate Array Size

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 strictly increasing.

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

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

Check Complex Number Attributes

Assuming that a is 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 Specified Range

Check that the values in an array are 8-bit integers from 0 through 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)
The value of 'dim2' is invalid. Expected input to be one of these types:

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

Validate Function Arguments

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 argument.

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

collapse all

`A` — Input
any type of array

Input, specified as any type of array.

`classes` — Valid data types
character vector | cell array of character vectors | string array

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

`'half'`	Half-precision number
`'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 `1` (`true`) or `0` (`false`)
`'char'`	Character
`'string'`	String array
`'struct'`	Structure array
`'cell'`	Cell array
`'table'`	Table
`'timetable'`	Timetable
`'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 | string

`attributes` — Valid attributes
cell array | string array

Valid attributes, specified as a cell array or a string array.

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 in a cell array. A string array cannot be used to represent numeric values in attributes.

These attributes 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
`'scalartext'`	Either a string scalar or a character vector, including inputs with zero characters
`'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', N`	Array with `N` elements
`'ncols', N`	Array with `N` columns
`'nrows', N`	Array with `N` rows
`'ndims', N`	`N`-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

These attributes specify valid ranges for values in A.

`'>', N`	All values greater than `N`
`'>=', N`	All values greater than or equal to `N`
`'<', N`	All values less than `N`
`'<=', N`	All values less than or equal to `N`
`'finite'`	All values are finite
`'nonnan'`	No values are NaN (Not a Number)

These attributes 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
`'nonnegative'`	No element is less than zero
`'nonzero'`	No element is equal to zero
`'positive'`	No element is 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 for validation
character vector | string scalar

Name of function for validation, specified as a character vector or as a string scalar. If you specify an empty character vector, '', or the <missing> string, then the validateattributes function ignores the funcName input.

Data Types: char | string

`varName` — Name of input variable
character vector | string scalar

Name of input variable, specified as a character vector or a string scalar. If you specify an empty character vector, '', or the <missing> string, then the validateattributes function ignores the varName input.

Data Types: char | string

`argIndex` — Position of input argument
positive integer

Position of input argument, specified as a positive integer.

Data Types: double

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Some error messages are a simplified version of the MATLAB error message.
The classes, funcName, varName, and argIndex arguments must be constant.
Attribute names must be constant.
In the generated code, the format of numbers in an error message might be different from the format in MATLAB. For example, here is an error message in MATLAB:
```
Expected input to be an array with all of the values > 3.
```
Here is the error message in the generated code:
```
Expected input to be an array with all of the values >   3.000000000000000e+00.
```
scalar and real attributes are supported for half-precision data type.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same limitations apply to GPU code generation.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The validateattributes function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2007b

validateattributes

Syntax

Description

Examples

Validate Array Size

Validate Array Monotonicity

Check Complex Number Attributes

Ensure Array Values Are Within Specified Range

Validate Function Input Parameters Using `inputParser`

Validate Function Arguments

Input Arguments

`A` — Input
any type of array

`classes` — Valid data types
character vector | cell array of character vectors | string array

`attributes` — Valid attributes
cell array | string array

`funcName` — Name of function for validation
character vector | string scalar

`varName` — Name of input variable
character vector | string scalar

`argIndex` — Position of input argument
positive integer

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

See Also

Topics

validateattributes

Syntax

Description

Examples

Validate Array Size

Validate Array Monotonicity

Check Complex Number Attributes

Ensure Array Values Are Within Specified Range

Validate Function Input Parameters Using inputParser

Validate Function Arguments

Input Arguments

A — Input any type of array

classes — Valid data types character vector | cell array of character vectors | string array

attributes — Valid attributes cell array | string array

funcName — Name of function for validation character vector | string scalar

varName — Name of input variable character vector | string scalar

argIndex — Position of input argument positive integer

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

See Also

Topics

Validate Function Input Parameters Using `inputParser`

`A` — Input
any type of array

`classes` — Valid data types
character vector | cell array of character vectors | string array

`attributes` — Valid attributes
cell array | string array

`funcName` — Name of function for validation
character vector | string scalar

`varName` — Name of input variable
character vector | string scalar

`argIndex` — Position of input argument
positive integer

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.