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