Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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

example

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

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. It is a case-insensitive, partial-match to "wonder".

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

    "wonder"

If there are multiple partial matches 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 there are multiple partial matches and each string is a substring of another, 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 (found using the mfilename function) in the error identifier.

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

Introduced in R2006b

Was this topic helpful?