octave_packages/m/strings/substr.m

   1 ## Copyright (C) 1996-2012 Kurt Hornik
   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} {} substr (@var{s}, @var{offset})
  21 ## @deftypefnx {Function File} {} substr (@var{s}, @var{offset}, @var{len})
  22 ## Return the substring of @var{s} which starts at character number
  23 ## @var{offset} and is @var{len} characters long.
  24 ##
  25 ## Position numbering for offsets begins with 1.  If @var{offset} is negative,
  26 ## extraction starts that far from the end of the string.
  27 ##
  28 ## If @var{len} is omitted, the substring extends to the end of @var{S}.  A
  29 ## negative value for @var{len} extracts to within @var{len} characters of
  30 ## the end of the string
  31 ##
  32 ## Examples:
  33 ##
  34 ## @example
  35 ## @group
  36 ## substr ("This is a test string", 6, 9)
  37 ##      @result{} "is a test"
  38 ## substr ("This is a test string", -11)
  39 ##      @result{} "test string"
  40 ## substr ("This is a test string", -11, -7)
  41 ##      @result{} "test"
  42 ## @end group
  43 ## @end example
  44 ##
  45 ## This function is patterned after the equivalent function in Perl.
  46 ## @end deftypefn
  47
  48 ## Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
  49 ## Adapted-By: jwe
  50
  51 function t = substr (s, offset, len)
  52
  53   if (nargin < 2 || nargin > 3)
  54     print_usage ();
  55   endif
  56
  57   if (! ischar (s))
  58     error ("substr: S must be a string or string array");
  59   elseif (! isscalar (offset) || (nargin == 3 && ! isscalar (len)))
  60     error ("substr: OFFSET and LEN must be scalar integers");
  61   endif
  62
  63   offset = fix (offset);
  64   nc = columns (s);
  65   if (abs (offset) > nc || offset == 0)
  66     error ("substr: OFFSET = %d out of range", offset);
  67   endif
  68
  69   if (offset <= 0)
  70     offset += nc + 1;
  71   endif
  72
  73   if (nargin == 2)
  74     eos = nc;
  75   else
  76     len = fix (len);
  77     if (len < 0)
  78       eos = nc + len;
  79     else
  80       eos = offset + len - 1;
  81     endif
  82   endif
  83
  84   if (eos > nc)
  85     error ("substr: length LEN = %d out of range", len);
  86   elseif (offset > eos && len != 0)
  87     error ("substr: No overlap with chosen values of OFFSET and LEN");
  88   endif
  89
  90   t = s(:, offset:eos);
  91
  92 endfunction
  93
  94
  95 %!assert (substr ("This is a test string", 6, 9), "is a test");
  96 %!assert (substr ("This is a test string", -11), "test string");
  97 %!assert (substr ("This is a test string", -11, 4), "test");
  98 %!assert (substr ("This is a test string", -11, -7), "test");
  99 %!assert (substr ("This is a test string", 1, -7), "This is a test");
 100 %!assert (isempty (substr ("This is a test string", 1, 0)));
 101
 102 %% Test input validation
 103 %!error substr ()
 104 %!error substr ("foo", 2, 3, 4)
 105 %!error substr (ones (5, 1), 1, 1)
 106 %!error substr ("foo", ones(2,2))
 107 %!error substr ("foo", 1, ones(2,2))
 108 %!error substr ("foo", 0)
 109 %!error substr ("foo", 5)
 110 %!error substr ("foo", 1, 5)
 111 %!error substr ("foo", -1, 5)
 112 %!error substr ("foo", 2, -5)
 113