MATLAB Function Reference

validateattributes - Check validity of array

Syntax

validateattributes(A, classes, attributes)
validateattributes(A, classes, attributes, position)
validateattributes(A, classes, attributes, funname)
validateattributes(A, classes, attributes, funname, varname)
validateattributes(A, classes, attributes, funname, 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 also has at least one 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, the MATLAB^® software issues a formatted error message.

The classes input is a cell array of one or more strings, each string containing the name of a MATLAB class (i.e., one of the 15 MATLAB data types), the name of a MATLAB class, or the keyword numeric. (See the Class Values table, below.

The attributes input is a cell array of one or more strings, each string describing an array attribute. (See the Attribute Values table, below).

validateattributes(A, classes, attributes, position) validates array A as described above 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, funname) validates array A as described above and, if the validation fails, displays an error message that includes the name of the function performing the validation (funname). The funname input must be a string enclosed in single quotation marks.

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

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

Class Values

Attribute Values

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

This function, which resides in M-file empl_profile, compares the values passed in each argument with the specified classes and attributes and throws an error if they are not correct:

function empl_profile(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 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_profile(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_profile(empl_id, empl_info, 14.3, 'HCP Medical Plus')

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

  cell, char

Instead its type was double.

Example 2

Modify the empl_profile M-file shown in the last example, adding arguments to validateattributes to display the function name, variable name, and position of the argument:

function empl_profile(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_profile with the argument values out of their correct 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 it position in the input argument list:

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

  cell, char

Instead its type was double.

Error in ==> empl_profile at 6
validateattributes(healthplan,{'cell', 'char'}, {'vector'}, ...

Example 3

Modify the empl_profile M-file so that it checks the function inputs using the MATLAB inputParser. Use validateattributes as the validating function for the inputParser methods:

function empl_profile(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_profile using appropriate input arguments:

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

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

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

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

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

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

  struct

Instead its type was char.

See Also

validatestring, is*, isa, inputparser

userpath

validatestring