validatestring

Check validity of text

Syntax

matchedStr = validatestring(str,validStrings)

matchedStr = validatestring(str,validStrings,argIdx)

matchedStr = validatestring(str,validStrings,funcName)

matchedStr = validatestring(str,validStrings,funcName,varName)

matchedStr = validatestring(str,validStrings,funcName,varName,argIdx)

Description

matchedStr = validatestring(str,validStrings) checks the validity of str against validStrings. The text is valid if it is an unambiguous, case-insensitive match to any element in validStrings. The validatestring function supports partial matching of leading characters.

If str is valid, then validatestring returns the matched text. Otherwise, MATLAB^® throws an error.

matchedStr = validatestring(str,validStrings,argIdx) includes the position of the input in your function argument list as part of any generated error messages. Use this syntax to format any generated error messages.

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

matchedStr = validatestring(str,validStrings,funcName,varName) includes the specified variable name in generated error messages. Use this syntax to format any generated error messages.

matchedStr = validatestring(str,validStrings,funcName,varName,argIdx) includes the position of the input in your function argument list as part of any generated error messages. Use this syntax to format any generated error messages.

Examples

Validate Text

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

validStrings = ["wind","wonder","when"];
str = "wind";
validStr = validatestring(str,validStrings)

validStr = 

    "wind"

Check if "WON" is in the set of valid values defined by validStrings. The string is a case-insensitive, partial-match to "wonder".

str = "WON";
validStr = validatestring(str,validStrings)

validStr = 

    "wonder"

If multiple partial matches exist and each string is not a substring of another, then validatestring throws an error.

validStrings = ["showcase","show up","showtimes"];
str = "show";
validStr = validatestring(str,validStrings)

Expected input to match one of these values:

'showcase', 'show up', 'showtimes'

The input, show, matched more than one valid value.

However, if multiple partial matches exist and each string is a substring of another, then validatestring returns the shortest match.

validStrings = ["righteously","right","righteous"];
str = "rig";
validStr = validatestring(str,validStrings)

validStr = 

    "right"

Validate Text Input to Function

Create a function in a file named findArea.m. The validation for shape includes the position of the input in your function argument list as part of any generated error messages. The validation for units also includes the variable name ('units') in the error message and the file name in the error identifier. Use the mfilename function to find the file name.

function a = findArea(shape,h,w,units)
    expectedShapes = {'square','rectangle','triangle'};
    expectedUnits = {'cm','m','in','ft','yds'};
    
    shapeName = validatestring(shape,expectedShapes,1);
    unitAbbrev = validatestring(units,expectedUnits,mfilename,'units',4);
    
    switch shapeName
        case {'square','rectangle'}
            a = h*w;
        case {'triangle'}
            a = h*w/2;
        otherwise
            error('Unknown shape passing validation.')
    end
end

Call the function with a valid shape name. The value of 'Rect' is valid because it is a case-insensitive, partial match to 'rectangle'.

a = findArea('Rect',10,3,'cm')

a =

    30

Call the function with an invalid shape name. The error message contains the position of the invalid text. Here, the invalid text is the first input argument.

a = findArea('octagon',7,13,'in')

Error using findArea (line 5)
Expected input number 1 to match one of these values:

'square', 'rectangle', 'triangle'

The input, 'octagon', did not match any of the valid values.

Call the function with an invalid unit. The error message contains the variable name and the position of the invalid text. The invalid text is the fourth input argument.

a = findArea('TRI',10,3,'mi')

Error using findArea (line 6)
Expected input number 4, units, to match one of these values:

'cm', 'm', 'in', 'ft', 'yds'

The input, 'mi', did not match any of the valid values.

Use mException to view the error identifier, which includes the file name.

id = MException.last.identifier

id =

    'MATLAB:findArea:unrecognizedStringChoice'

Input Arguments

str — Text to validate

string scalar | character vector

Text to validate, specified as a string scalar or a character vector.

Example: 'textToValidate'

Example: "otherTextToValidate"

validStrings — Text to match

string array | cell array of character vectors

Text to match, specified as a string array or a cell array of character vectors.

Example: ["value1","value2"]

Example: {'val1','val2',val3'}

funcName — Name of function

string scalar | character vector

Name of the function whose input to validate, specified as a string scalar or character vector. If you specify an empty character vector '' or the <missing> string, then the validatestring function ignores the funcName input.

Example: "myFunctionName"

Example: Call to mfilename function, as in the code validatestring(units,expectedUnits,mfilename)

varName — Name of input variable

string scalar | character vector

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

Example: "inputVariable1"

Example: 'variableB'

argIdx — Position of input argument

positive integer

Position of the input argument to validate, specified as a positive integer.

Output Arguments

matchedStr — Matched text

string scalar | character vector

Matched text, returned as a string scalar if validStrings is a string array or as a character vector if validStrings is a cell array of character vectors.

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 character vector is a subset of another
balloon, ballet	Error	Multiple partial matches to unique character vectors
barn, bell	Error	No match

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You must supply the third argument and it must be funcName.

• The validStrings, funcName, varName, and argIdx arguments must be constant.

• MATLAB and the generated code behave differently when multiple partial matches exist and each string is a substring of another string. In MATLAB, validatestring returns the shortest match. In the generated code, validatestring throws an error.

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.

Version History

Introduced in R2006b