# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1318097330 25200
# Node ID 42d5ff896e8554387abec821efc0801aad8a20ca
# Parent  27da11c63d98d8b19633c1bb635806101c7e2f39
substr.m: Expand function to accept negative values for length argument.

* substr.m: Expand function to accept negative values for length argument.
Improve input validation and add more tests.  Update docstring.

diff --git a/scripts/strings/substr.m b/scripts/strings/substr.m
--- a/scripts/strings/substr.m
+++ b/scripts/strings/substr.m
@@ -17,25 +17,32 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} substr (@var{s}, @var{offset}, @var{len})
+## @deftypefn  {Function File} {} substr (@var{s}, @var{offset})
+## @deftypefnx {Function File} {} substr (@var{s}, @var{offset}, @var{len})
 ## Return the substring of @var{s} which starts at character number
 ## @var{offset} and is @var{len} characters long.
 ##
-## If @var{offset} is negative, extraction starts that far from the end of
-## the string.  If @var{len} is omitted, the substring extends to the end
-## of S.
+## Position numbering for offsets begins with 1.  If @var{offset} is negative,
+## extraction starts that far from the end of the string.
+## 
+## If @var{len} is omitted, the substring extends to the end of @var{S}.  A
+## negative value for @var{len} extracts to within @var{len} characters of
+## the end of the string
 ##
-## For example:
+## Examples:
 ##
 ## @example
 ## @group
 ## substr ("This is a test string", 6, 9)
 ##      @result{} "is a test"
+## substr ("This is a test string", -11)
+##      @result{} "test string"
+## substr ("This is a test string", -11, -7)
+##      @result{} "test"
 ## @end group
 ## @end example
 ##
-## This function is patterned after AWK@.  You can get the same result by
-## @code{@var{s}(@var{offset} : (@var{offset} + @var{len} - 1))}.
+## This function is patterned after the equivalent function in Perl.
 ## @end deftypefn
 
 ## Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
@@ -47,34 +54,60 @@
     print_usage ();
   endif
 
-  if (ischar (s))
-    nc = columns (s);
-    if (abs (offset) > 0 && abs (offset) <= nc)
-      if (offset <= 0)
-        offset += nc + 1;
-      endif
-      if (nargin == 2)
-        eos = nc;
-      else
-        eos = offset + len - 1;
-      endif
-      if (eos <= nc)
-        t = s (:, offset:eos);
-      else
-        error ("substr: length = %d out of range", len);
-      endif
+  if (! ischar (s))
+    error ("substr: S must be a string or string array");
+  elseif (! isscalar (offset) || (nargin == 3 && ! isscalar (len)))
+    error ("substr: OFFSET and LEN must be scalar integers");
+  endif
+
+  offset = fix (offset);
+  nc = columns (s);
+  if (abs (offset) > nc || offset == 0)
+    error ("substr: OFFSET = %d out of range", offset);
+  endif
+
+  if (offset <= 0)
+    offset += nc + 1;
+  endif
+
+  if (nargin == 2)
+    eos = nc;
+  else
+    len = fix (len);
+    if (len < 0)
+      eos = nc + len;
     else
-      error ("substr: OFFSET = %d out of range", offset);
+      eos = offset + len - 1;
     endif
-  else
-    error ("substr: expecting string argument");
   endif
 
+  if (eos > nc)
+    error ("substr: length LEN = %d out of range", len);
+  elseif (offset > eos && len != 0)
+    error ("substr: No overlap with chosen values of OFFSET and LEN");
+  endif
+
+  t = s(:, offset:eos);
+
 endfunction
 
-%!assert(strcmp (substr ("This is a test string", 6, 9), "is a test"));
+
+%!assert (substr ("This is a test string", 6, 9), "is a test");
+%!assert (substr ("This is a test string", -11), "test string");
+%!assert (substr ("This is a test string", -11, 4), "test");
+%!assert (substr ("This is a test string", -11, -7), "test");
+%!assert (substr ("This is a test string", 1, -7), "This is a test");
+%!assert (substr ("This is a test string", 1, 0), "");
 
-%!error substr ();
+%% Test input validation
+%!error substr ()
+%!error substr ("foo", 2, 3, 4)
+%!error substr (ones (5, 1), 1, 1)
+%!error substr ("foo", ones(2,2))
+%!error substr ("foo", 1, ones(2,2))
+%!error substr ("foo", 0)
+%!error substr ("foo", 5)
+%!error substr ("foo", 1, 5)
+%!error substr ("foo", -1, 5)
+%!error substr ("foo", 2, -5)
 
-%!error substr ("foo", 2, 3, 4);
-