Main Content

validatestring

Check validity of text

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.

example

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.

example

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

collapse all

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"

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

collapse all

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

Example: 'textToValidate'

Example: "otherTextToValidate"

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

Example: ["value1","value2"]

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

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)

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'

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

Output Arguments

collapse all

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 ValueType of Match
ball, barn, bellballExact match
balloon, barnballoonPartial match (leading characters)
ballo, balloo, balloonballo (shortest match)Multiple partial matches where each character vector is a subset of another
balloon, balletErrorMultiple partial matches to unique character vectors
barn, bellErrorNo match

Extended Capabilities

Version History

Introduced in R2006b