Learn more about MATLAB

validatestring - Check validity of text string

Syntax

validstr = validatestring(str, strarray) validstr = validatestring(str, strarray, position) validstr = validatestring(str, strarray, funname) validstr = validatestring(str, strarray, funname, varname) validstr = validatestring(str, strarray, funname, varname, position)

Description

validstr = validatestring(str, strarray) checks the validity of text string str. If str matches one or more of the text strings in the cell array strarray, MATLAB returns the matching string in validstr. If str does not match any of the strings in strarray, MATLAB issues a formatted error message. MATLAB compares the strings without respect to letter case.

This table shows how validatestring determines what value to return. If multiple matches are found, validatestring returns the shortest matching string.

Type of Match	Example — Match '`ball`' with . . .	Return Value
Exact match	`ball`, `barn`, `bell`	`ball`
Partial match (leading characters)	`balloon`, `barn`	`balloon`
Multiple partial matches where each string is a subset of another	`ball`, `ballo`, `balloo`, `balloon`	`ball`
Multiple partial matches where strings are unique	`balloon`, `ballet`	Error
No match	`barn`, `bell`	Error

validstr = validatestring(str, strarray, position) checks the validity of text string str 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.

validstr = validatestring(str, strarray, funname) checks the validity of text string str 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.

validstr = validatestring(str, strarray, funname, varname) checks the validity of text string str 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.

validstr = validatestring(str, strarray, funname, varname, position) checks the validity of text string str 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.

Examples

Example 1

Use validatestring to find the word won in the cell array of strings:

validatestring('won', {'wind', 'won', 'when'})
ans =
   won

Replace the word won with wonder in the string array. Because the leading characters of the input string and wonder are the same, validatestring finds a partial match between the two words and returns the full word wonder:

validatestring('won', {'wind', 'wonder', 'when'})
ans =
   wonder

If there is more than one partial match, and each string in the array is a subset or superset of the others, validatestring returns the shortest matching string:

validatestring('wond', {'won', 'wonder', 'wonderful'})
ans =
   wonder

However, if each string in the array is not subset or superset of each other, MATLAB throws an error because there is no exact match and it is not clear which of the two partial matches should be returned:

validatestring('wond', {'won', 'wonder', 'wondrous'})
??? Error using ==> validatestring at 89
Function VALIDATESTRING expected its input argument to 
   match one of these strings:

  won, wonder, wondrous

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

Example 2

In this example, the get_flight_numbers function returns the flight numbers for routes between two cities: a point of origin and point of destination. The function uses validatestring to see if the origin and destination are among those covered by the airline. If not, an error message is displayed:

function get_flight_numbers(origin, destination)
% Only part of the airline's flight data is shown here.
   flights.chi2rio = [503, 196, 331, 373, 1475];   
   flights.chi2par = [718, 9276, 172, 903, 7724 992, 1158];
   flights.chi2hon = [9193, 880, 471, 391];

   routes = {'Athens', 'Paris', 'Chicago', 'Sydney', ...
      'Cancun', 'London', 'Rio de Janeiro', 'Honolulu', ...
      'Rome', 'New York City'};
   orig = '';  dest = '';

      % Does the airline cover these cities?
      try
         orig = validatestring(origin, routes);
         dest = validatestring(destination, routes);
      catch
         % If not covered, then display error message.
         if isempty(orig)
            fprintf(...
               'We have no flights with origin: %s.\n', ...
               origin)
         elseif isempty(dest)
            fprintf('%s%s%s.\n', 'We have no flights ', ...
                    'with destination: ', destination)
         end
      return
      end

   % If covered, display the flights from 'orig' to 'dest'.
   fprintf(...
      'Flights available from %s to %s are:\n', orig, dest)
   reply = eval(...
     ['flights.' lower(orig(1:3)) '2' lower(dest(1:3))])';
   fprintf('   Flight %d\n', reply)

Enter a point of origin that is not covered by this airline:

get_flight_numbers('San Diego', 'Rio de Janeiro')
ans =
We have no flights with origin: San Diego.

Enter a destination that is misspelled:

get_flight_numbers('Chicago', 'Reo de Janeiro')
ans =
We have no flights with destination: Reo de Janeiro.

Enter a route that is covered:

get_flight_numbers('Chicago', 'Rio de Janeiro')
ans =
Flights available from Chicago to Rio de Janeiro are:
   Flight 503
   Flight 196
   Flight 331
   Flight 373
   Flight 1475

Example 3

Rewrite the try-catch block of Example 2 by adding funname, varname, and position arguments to the call to validatestring and replacing the return statement with rethrow:

   % See if the cities entered are covered by this airline.
   try
      orig = validatestring(...
         origin, routes, mfilename, 'Flight Origin', 1);
      dest = validatestring(...
         destination, routes, mfilename, ...
           'Flight Destination', 2);
   catch e
      % If not covered, then display error message.
      if isempty(orig)
          fprintf(...
             'We have no flights with origin: %s.\n', ...
             origin)
      elseif isempty(dest)
          fprintf('%s%s%s.\n', 'We have no flights ', ...
                  'with destination: ', destination)
      end
      rethrow(e);
   end

In response to the rethrow command, MATLAB displays an error message that includes the function name get_flight_numbers, the failing variable name Flight Destination', and its position in the argument list, 2:

get_flight_numbers('Chicago', 'Reo de Janeiro')
We have no flights with destination: Reo de Janeiro.

??? Error using ==> validatestring at 89
Function GET_FLIGHT_NUMBERS expected its input argument 
    number 2, Flight Destination, to match one of these 
    strings:

  Athens, Paris, Chicago, Sydney, Cancun, London, Rio de 
Janeiro, Honolulu, Rome

The input, 'Reo de Janeiro', did not match any of the valid
   strings.

Error in ==> get_flight_numbers at 17
   dest = validatestring(destination, routes, mfilename, 
   'destination', 2);