validatestring - Check validity of text string

Syntax

Description

validStr = validatestring(str,validStrings) checks the validity of text string str. If str is an unambiguous, case-insensitive match to a string in cell array validStrings, the validatestring function returns the matching string in validstr. Otherwise, MATLAB throws an error and issues a formatted error message.

validStr = validatestring(str,validStrings,argIndex) includes the position of the input in your function argument list as part of any generated error messages.

validStr = validatestring(str,validStrings,funcName) includes the specified function name in generated error identifiers.

validStr = validatestring(str,validStrings,funcName,varName) includes the specified variable name in generated error messages.

validStr = validatestring(str,validStrings,funcName,varName,argIndex) includes the specified information in generated error messages or identifiers.

Input Arguments

str	String to validate, of type char.
validStrings	Cell array of allowed strings.
funcName	String that specifies the name of the function whose input you are validating. If you specify an empty string, '', the validatestring function ignores the funcname input.
varName	String that specifies the name of the input variable. If you specify an empty string, '', the validatstring function ignores the varName input.
argIndex	Positive integer that specifies the position of the input argument.

Output Arguments

validStr

String that contains the element of validStrings that is an unambiguous, case-insensitive match to str. Example — Match 'ball' with . . . Return Value Type of Match ball, barn, bell ball Exact match balloon, barn balloon Partial match (leading characters) ballo, balloo, balloon ballo (shortest match) Multiple partial matches where each string is a subset of another balloon, ballet Error Multiple partial matches to unique strings barn, bell Error No match

Examples

Check whether a string is in a set of valid values.

str = 'won';
validStrings = {'wind','wonder','when'};

validStr = validatestring(str,validStrings)

Because str is a partial match to a unique string, this code returns

validStr =
     wonder

However, if str is a partial match to multiple strings, and the strings are not subsets of each other, validatestring throws an error and displays a formatted message.

str = 'won';
validStrings = {'wonder','wondrous','wonderful'};

validStr = validatestring(str,validStrings)

The error message is

Expected argument to match one of these strings:

  wonder, wondrous, wonderful

The input, 'won', matched more than one valid string.

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

function a = findArea(shape,ht,wd,units)
   a = 0;
   expectedShapes = {'square','rectangle','triangle'};
   expectedUnits = {'cm','m','in','ft','yds'};

   shapeName = validatestring(shape,expectedShapes,mfilename,'Shape',1)
   unitAbbrev = validatestring(units,expectedUnits,mfilename,'Units',4)

When you call the function with valid input strings,

myarea = findArea('rect',10,3,'cm')

the function stores the inputs in local variables shapeName and unitAbbrev:

shapeName =
     rectangle

unitAbbrev =
     cm

However, if the inputs are not valid, such as

myarea = findArea('circle',10,3,'cm')

MATLAB displays

Error using findArea
Expected argument 1, Shape, to match one of these strings:

  square, rectangle, triangle

The input, 'circle', did not match any of the valid strings.

The function name is part of the error identifier, so

MException.last.identifier

returns

MATLAB:findArea:unrecognizedStringChoice

See Also

inputParser | is* | isa | validateattributes

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