octave_packages/m/strings/strmatch.m

   1 ## Copyright (C) 2000-2012 Paul Kienzle
   2 ## Copyright (C) 2003 Alois Schloegl
   3 ## Copyright (C) 2010 VZLU Prague
   4 ##
   5 ## This file is part of Octave.
   6 ##
   7 ## Octave is free software; you can redistribute it and/or modify it
   8 ## under the terms of the GNU General Public License as published by
   9 ## the Free Software Foundation; either version 3 of the License, or (at
  10 ## your option) any later version.
  11 ##
  12 ## Octave is distributed in the hope that it will be useful, but
  13 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  14 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 ## General Public License for more details.
  16 ##
  17 ## You should have received a copy of the GNU General Public License
  18 ## along with Octave; see the file COPYING.  If not, see
  19 ## <http://www.gnu.org/licenses/>.
  20
  21 ## -*- texinfo -*-
  22 ## @deftypefn  {Function File} {} strmatch (@var{s}, @var{A})
  23 ## @deftypefnx {Function File} {} strmatch (@var{s}, @var{A}, "exact")
  24 ## Return indices of entries of @var{A} which begin with the string @var{s}.
  25 ## The second argument @var{A} must be a string, character matrix, or a cell
  26 ## array of strings.  If the third argument @code{"exact"} is not given, then
  27 ## @var{s} only needs to match @var{A} up to the length of @var{s}.
  28 ## Trailing spaces and nulls in @var{s} and @var{A} are ignored when matching.
  29 ## option.
  30 ##
  31 ## For example:
  32 ##
  33 ## @example
  34 ## @group
  35 ## strmatch ("apple", "apple juice")
  36 ##      @result{} 1
  37 ##
  38 ## strmatch ("apple", ["apple  "; "apple juice"; "an apple"])
  39 ##      @result{} [1; 2]
  40 ##
  41 ## strmatch ("apple", ["apple  "; "apple juice"; "an apple"], "exact")
  42 ##      @result{} [1]
  43 ## @end group
  44 ## @end example
  45 ##
  46 ## @strong{Caution:} @code{strmatch} is scheduled for deprecation.  Use
  47 ## @code{strcmpi} or @code{strncmpi} in all new code.
  48 ## @seealso{strfind, findstr, strcmp, strncmp, strcmpi, strncmpi, find}
  49 ## @end deftypefn
  50
  51 ## Author: Paul Kienzle, Alois Schloegl
  52 ## Adapted-by: jwe
  53
  54 function idx = strmatch (s, A, exact)
  55
  56   if (nargin < 2 || nargin > 3)
  57     print_usage ();
  58   endif
  59
  60   if (! ischar (s) || (! isempty (s) && ! isvector (s)))
  61     error ("strmatch: S must be a string");
  62   elseif (! (ischar (A) || iscellstr (A)))
  63     error ("strmatch: A must be a string or cell array of strings");
  64   endif
  65
  66   ## Trim blanks and nulls from search string
  67   s = regexprep (s, "[ \\0]+$", '');
  68   len = length (s);
  69
  70   exact = nargin == 3 && ischar (exact) && strcmp (exact, "exact");
  71
  72   if (ischar (A))
  73     [nr, nc] = size (A);
  74     if (len > nc)
  75       idx = [];
  76     else
  77       match = all (bsxfun (@eq, A(:,1:len), s), 2);
  78       if (exact)
  79         AA = A(:,len+1:nc);
  80         match &= all (AA == " " | AA == "\0", 2);
  81       endif
  82       idx = find (match);
  83     endif
  84   else
  85     if (len > 0)
  86       idx = find (strncmp (s, A, len));
  87     else
  88       idx = find (strcmp (s, A));
  89     endif
  90     if (exact)
  91       ## We can't just use strcmp, because we need to ignore spaces at end.
  92       B = regexprep (A(idx), "[ \\0]+$", '');
  93       idx = idx(strcmp (s, B));
  94     endif
  95   endif
  96
  97 endfunction
  98
  99
 100 %!assert (strmatch("a", {"aaa", "bab", "bbb"}), 1);
 101 %!assert (strmatch ("apple", "apple juice"), 1);
 102 %!assert (strmatch ("apple", ["apple pie"; "apple juice"; "an apple"]), [1; 2]);
 103 %!assert (strmatch ("apple", {"apple pie"; "apple juice"; "tomato"}), [1; 2]);
 104 %!assert (strmatch ("apple pie", "apple"), []);
 105 %!assert (strmatch ("a ", "a"), 1);
 106 %!assert (strmatch ("a", "a \0", "exact"), 1);
 107 %!assert (strmatch ("a b", {"a b", "a c", "c d"}), 1);
 108 %!assert (strmatch ("", {"", "foo", "bar", ""}), [1, 4]);
 109 %!assert (strmatch ('', { '', '% comment', 'var a = 5', ''}, 'exact'), [1,4]);
 110
 111 %% Test input validation
 112 %!error <Invalid call to strmatch> strmatch();
 113 %!error <Invalid call to strmatch> strmatch("a");
 114 %!error <Invalid call to strmatch> strmatch("a", "aaa", "exact", 1);
 115 %!error <S must be a string> strmatch(1, "aaa");
 116 %!error <S must be a string> strmatch(char ("a", "bb"), "aaa");
 117 %!error <A must be a string> strmatch("a", 1);
 118 %!error <A must be a string> strmatch("a", {"hello", [1]});
 119