function out = validatestring( varargin )

%VALIDATESTRING Check validity of text.

%   VALIDSTR = VALIDATESTRING(STR,VALID_STRINGS) checks the validity of

%   text STR. If STR unambiguously and case-insensitively matches the

%   beginning of one of VALID_STRINGS, VALIDATESTRING returns the match

%   in VALIDSTR. Otherwise, VALIDATESTRING issues a formatted error message.

%

%   VALIDSTR = VALIDATESTRING(STR,VALID_STRINGS,ARG_INDEX) includes the 

%   position of the input in your function argument list as part of any

%   generated error messages.

%

%   VALIDSTR = VALIDATESTRING(STR,VALID_STRINGS,FUNC_NAME) includes the 

%   specified function name in generated error identifiers.

%

%   VALIDSTR = VALIDATESTRING(STR,VALID_STRINGS,FUNC_NAME,VAR_NAME) includes 

%   the specified variable name in generated error messages.

%

%   VALIDSTR = VALIDATESTRING(STR,VALID_STRINGS,FUNC_NAME,VAR_NAME,ARG_INDEX) 

%   includes the specified information in the generated error messages or

%   identifiers.

%

%   Input Arguments:

%

%   VALID_STRINGS   Array of strings or cell array of character vectors.

%

%   ARG_INDEX       Positive integer that specifies the position of the

%                   input argument.

%

%   FUNC_NAME       String scalar or character vector that specifies the

%                   function name. If you specify a missing string or an

%                   empty character vector, '', FUNC_NAME is ignored.

%

%   VAR_NAME        String scalar or character vector that specifies the

%                   input argument name. If you specify a missing string or

%                   an empty character vector, '', VAR_NAME is ignored.

%

%   Example: Define a cell array of text strings, and pass in another

%            string that is not in the cell array.

%

%       validatestring('C',{'A','B'},'func_name','var_name',2)

%

%   This code throws an error and displays a formatted message:

%

%       Expected argument 2, var_name, to match one of these strings:

%

%       'A', 'B'

%

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

%

%   See also validateattributes, inputParser.

%   Copyright 1993-2018 The MathWorks, Inc.

    narginchk(2,5); 

    try 

        [in, validStrings, optional_inputs] = checkInputs(varargin); 

    catch e

        % only VALIDATESTRING should be on the stack

        throw(e)

    end 

    try     

        % check the contents of IN

        out = checkString(in, validStrings, optional_inputs); 

    catch e

        myId = 'MATLAB:validatestring:';

        if strncmp(myId, e.identifier, length(myId))

            % leave VALIDATESTRING on the stack, because there was a misuse

            % of VALIDATESTRING itself

            throw(e)

        else

            % strip VALIDATESTRING off the stack so that the error looks like

            % it comes from the caller just as if it had hand-coded its input checking

            throwAsCaller( e )

        end

    end 

end