octave_packages/m/strings/validatestring.m

   1 ## Copyright (C) 2008-2012 Bill Denney
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray})
  21 ## @deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname})
  22 ## @deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname}, @var{varname})
  23 ## @deftypefnx {Function File} {@var{validstr} =} validatestring (@dots{}, @var{position})
  24 ## Verify that @var{str} is an element, or substring of an element, in
  25 ## @var{strarray}.
  26 ##
  27 ## When @var{str} is a character string to be tested, and @var{strarray} is a
  28 ## cellstr of valid values, then @var{validstr} will be the validated form
  29 ## of @var{str} where validation is defined as @var{str} being a member
  30 ## or substring of @var{validstr}.  This is useful for both verifying
  31 ## and expanding short options, such as "r", to their longer forms, such as
  32 ## "red".  If @var{str} is a substring of @var{validstr}, and there are
  33 ## multiple matches, the shortest match will be returned if all matches are
  34 ## substrings of each other.  Otherwise, an error will be raised because the
  35 ## expansion of @var{str} is ambiguous.  All comparisons are case insensitive.
  36 ##
  37 ## The additional inputs @var{funcname}, @var{varname}, and @var{position}
  38 ## are optional and will make any generated validation error message more
  39 ## specific.
  40 ##
  41 ## Examples:
  42 ## @c Set example in small font to prevent overfull line
  43 ##
  44 ## @smallexample
  45 ## @group
  46 ## validatestring ("r", @{"red", "green", "blue"@})
  47 ## @result{} "red"
  48 ##
  49 ## validatestring ("b", @{"red", "green", "blue", "black"@})
  50 ## @result{} error: validatestring: multiple unique matches were found for 'b':
  51 ##    blue, black
  52 ## @end group
  53 ## @end smallexample
  54 ##
  55 ## @seealso{strcmp, strcmpi}
  56 ## @end deftypefn
  57
  58 ## Author: Bill Denney <bill@denney.ws>
  59
  60 function str = validatestring (str, strarray, varargin)
  61
  62   if (nargin < 2 || nargin > 5)
  63     print_usage ();
  64   endif
  65
  66   position = 0;
  67   ## Process input arguments
  68   if (! isempty (varargin) && isnumeric (varargin{end}))
  69     position = varargin{end};
  70     varargin(end) = [];
  71   endif
  72
  73   funcname = varname = "";
  74   char_idx = cellfun ("isclass", varargin, "char");
  75   n_chararg = sum (char_idx);
  76   if (n_chararg > 2)
  77     error ("validatestring: invalid number of character inputs (3)");
  78   elseif (n_chararg == 2)
  79     [funcname, varname] = deal (varargin{char_idx});
  80   elseif (n_chararg == 1)
  81     funcname = varargin{char_idx};
  82   endif
  83
  84   ## Check the inputs
  85   if (! ischar (str))
  86     error ("validatestring: STR must be a character string");
  87   elseif (! isrow (str))
  88     error ("validatestring: STR must be a single row vector");
  89   elseif (! iscellstr (strarray))
  90     error ("validatestring: STRARRAY must be a cellstr");
  91   elseif (! isempty (funcname) && ! isrow (funcname))
  92     error ("validatestring: FUNCNAME must be a single row vector");
  93   elseif (! isempty (varname) && ! isrow (varname))
  94     error ("validatestring: VARNAME must be a single row vector");
  95   elseif (position < 0)
  96     error ("validatestring: POSITION must be >= 0");
  97   endif
  98
  99   ## Make static part of error string that uses funcname, varname, and position
 100   errstr = "";
 101   if (! isempty (funcname))
 102     errstr = sprintf ("Function: %s ", funcname);
 103   endif
 104   if (! isempty (varname))
 105     errstr = sprintf ("%sVariable: %s ", errstr, varname);
 106   endif
 107   if (position > 0)
 108     errstr = sprintf ("%sArgument position %d ", errstr, position);
 109   endif
 110   if (! isempty (errstr))
 111     errstr(end:end+1) = ":\n";
 112   endif
 113
 114   matches = strncmpi (str, strarray(:), numel (str));
 115   nmatches = sum (matches);
 116   if (nmatches == 0)
 117     error ("validatestring: %s'%s' does not match any of\n%s", errstr, str,
 118            sprintf ("%s, ", strarray{:})(1:end-2));
 119   elseif (nmatches == 1)
 120     str = strarray{matches};
 121   else
 122     ## Are the matches substrings of each other?
 123     ## If true, choose the shortest.  If not, raise an error.
 124     match_idx = find (matches);
 125     match_len = cellfun ("length", strarray(match_idx));
 126     [min_len, min_idx] = min (match_len);
 127     short_str = strarray{match_idx(min_idx)};
 128     submatch = strncmpi (short_str, strarray(match_idx), min_len);
 129     if (all (submatch))
 130       str = short_str;
 131     else
 132       error ("validatestring: %smultiple unique matches were found for '%s':\n%s",
 133              errstr, str, sprintf ("%s, ", strarray{match_idx})(1:end-2));
 134     endif
 135   endif
 136
 137 endfunction
 138
 139
 140 %!shared strarray
 141 %!  strarray = {"octave" "Oct" "octopus" "octaves"};
 142 %!assert (validatestring ("octave", strarray), "octave")
 143 %!assert (validatestring ("oct", strarray), "Oct")
 144 %!assert (validatestring ("octa", strarray), "octave")
 145 %!  strarray = {"abc1" "def" "abc2"};
 146 %!assert (validatestring ("d", strarray), "def")
 147 %!error <'xyz' does not match any> validatestring ("xyz", strarray)
 148 %!error <Function: DUMMY_TEST> validatestring ("xyz", strarray, "DUMMY_TEST")
 149 %!error <Function: DUMMY_TEST Variable: DUMMY_VAR:> validatestring ("xyz", strarray, "DUMMY_TEST", "DUMMY_VAR")
 150 %!error <Function: DUMMY_TEST Variable: DUMMY_VAR Argument position 5> validatestring ("xyz", strarray, "DUMMY_TEST", "DUMMY_VAR", 5)
 151 %!error <multiple unique matches were found for 'abc'> validatestring ("abc", strarray)
 152
 153 %% Test input validation
 154 %!error validatestring ("xyz")
 155 %!error validatestring ("xyz", {"xyz"}, "3", "4", 5, 6)
 156 %!error <invalid number of character inputs> validatestring ("xyz", {"xyz"}, "3", "4", "5")
 157 %!error <STR must be a character string> validatestring (1, {"xyz"}, "3", "4", 5)
 158 %!error <STR must be a single row vector> validatestring ("xyz".', {"xyz"}, "3", "4", 5)
 159 %!error <STRARRAY must be a cellstr> validatestring ("xyz", "xyz", "3", "4", 5)
 160 %!error <FUNCNAME must be a single row vector> validatestring ("xyz", {"xyz"}, "33".', "4", 5)
 161 %!error <VARNAME must be a single row vector> validatestring ("xyz", {"xyz"}, "3", "44".', 5)
 162 %!error <POSITION must be> validatestring ("xyz", {"xyz"}, "3", "4", -5)
 163