New Functions: nargoutchk.m, validatestring.m, addtodate.m

[Bill Denney]

Hi,

Attached is a changeset with the functions nargoutchk.m, 
validatestring.m, and addtodate.m.

Have a good day,

Bill

# HG changeset patch
# User address@hidden
# Date 1205715344 14400
# Node ID c2fd7b04ccd25494fea13e188fc688b0ce674400
# Parent  d7f2e316ba22a9ace07aaeafa207c7f552173b14
nargoutchk.m, validatestring.m, addtodate.m: new functions

diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/ChangeLog
--- a/scripts/ChangeLog Sat Mar 15 10:42:07 2008 -0400
+++ b/scripts/ChangeLog Sun Mar 16 20:55:44 2008 -0400
@@ -1,3 +1,8 @@ 2008-03-15  Bill Denney  <address@hidden
+2008-03-16  Bill Denney  <address@hidden>
+
+       * strings/validatestring.m, general/nargoutchk.m, 
+       time/addtodate.m: new functions
+
 2008-03-15  Bill Denney  <address@hidden>
 
        * general/genvarname.m: new function
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/general/Makefile.in
--- a/scripts/general/Makefile.in       Sat Mar 15 10:42:07 2008 -0400
+++ b/scripts/general/Makefile.in       Sun Mar 16 20:55:44 2008 -0400
@@ -41,10 +41,10 @@ SOURCES = __isequal__.m __splinen__.m ac
   interp3.m interpn.m interpft.m is_duplicate_entry.m isa.m \
   isdefinite.m isdir.m isequal.m isequalwithequalnans.m isscalar.m \
   issquare.m issymmetric.m isvector.m logical.m logspace.m lookup.m \
-  mod.m nargchk.m nextpow2.m nthroot.m num2str.m perror.m pol2cart.m \
-  polyarea.m postpad.m prepad.m quadl.m randperm.m rat.m rem.m \
-  repmat.m rot90.m rotdim.m shift.m shiftdim.m sortrows.m sph2cart.m \
-  strerror.m structfun.m sub2ind.m trapz.m tril.m triu.m
+  mod.m nargchk.m nargoutchk.m nextpow2.m nthroot.m num2str.m perror.m \
+  pol2cart.m polyarea.m postpad.m prepad.m quadl.m randperm.m rat.m \
+  rem.m repmat.m rot90.m rotdim.m shift.m shiftdim.m sortrows.m \
+  sph2cart.m strerror.m structfun.m sub2ind.m trapz.m tril.m triu.m
 
 DISTFILES = $(addprefix $(srcdir)/, Makefile.in $(SOURCES))
 
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/general/nargchk.m
--- a/scripts/general/nargchk.m Sat Mar 15 10:42:07 2008 -0400
+++ b/scripts/general/nargchk.m Sun Mar 16 20:55:44 2008 -0400
@@ -25,6 +25,7 @@
 ##
 ## This is useful for checking to see that the number of arguments supplied
 ## to a function is within an acceptable range.
+## @seealso{nargoutchk,error,nargin,nargout}
 ## @end deftypefn
 
 ## Author: jwe
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/general/nargoutchk.m
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/general/nargoutchk.m      Sun Mar 16 20:55:44 2008 -0400
@@ -0,0 +1,84 @@
+## Copyright (C) 2008 Bill Denney
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} address@hidden =} nargoutchk (@var{minargs}, 
@var{maxargs}, @var{nargs})
+## @deftypefnx {Function File} address@hidden =} nargoutchk (@var{minargs}, 
@var{maxargs}, @var{nargs}, "string")
+## @deftypefnx {Function File} address@hidden =} nargoutchk (@var{minargs}, 
@var{maxargs}, @var{nargs}, "struct")
+## Return an appropriate error message string (or structure) if the
+## number of outputs requested is invalid.
+##
+## This is useful for checking to see that the number of arguments supplied
+## to a function is within an acceptable range.
+## @seealso{nargchk, error, nargout, nargin}
+## @end deftypefn
+
+## Author: Bill Denney <address@hidden>
+
+function msg = nargoutchk (mina, maxa, narg, outtype)
+
+  if ((nargin < 3) || (nargin > 4))
+    print_usage ();
+  elseif mina > maxa
+    error ("nargoutchk: minargs must be <= maxargs");
+  elseif (nargin == 3)
+    outtype = "string";
+  elseif ! any (strcmpi (outtype, {"string" "struct"}))
+    error ("nargoutchk: output type must be either string or struct");
+  elseif ! (isscalar (mina) && isscalar (maxa) && isscalar (narg))
+    error ("nargoutchk: mina, maxa, and narg must be scalars");
+  endif
+
+  msg = struct ("message", "", "identifier", "");
+  if narg < mina
+    msg.message = "Not enough output arguments.";
+    msg.identifier = "Octave:nargoutchk:notEnoughOutputs";
+  elseif narg > maxa
+    msg.message = "Too many output arguments.";
+    msg.identifier = "Octave:nargoutchk:tooManyOutputs";
+  endif
+
+  if strcmpi (outtype, "string")
+    msg = ["nargoutchk: " msg.message];
+  else
+    if isempty (msg.message)
+      msg = struct([]);
+    endif
+    ## FIXME: remove the error below if error is modified to accept
+    ## struct inputs
+    error ("nargoutchk: error does not yet support struct inputs.")
+  endif
+
+endfunction
+
+## Tests
+%!shared stmin, stmax
+%!  stmin = struct ("message", "Not enough output arguments.",
+%!                  "identifier", "Octave:nargoutchk:notEnoughOutputs");
+%!  stmax = struct ("message", "Too many output arguments.",
+%!                  "identifier", "Octave:nargoutchk:tooManyOutputs");
+%!assert (nargoutchk (0, 1, 0), "")
+%!assert (nargoutchk (0, 1, 1), "")
+%!assert (nargoutchk (1, 1, 0), "Not enough output arguments.")
+%!assert (nargoutchk (0, 1, 2), "Too many output arguments.")
+%!assert (nargoutchk (0, 1, 2, "string"), "Too many output arguments.")
+## Struct outputs
+#%!assert (nargoutchk (0, 1, 0, "struct"), struct([]))
+#%!assert (nargoutchk (0, 1, 1, "struct"), struct([]))
+#%!assert (nargoutchk (1, 1, 0, "struct"), stmin)
+#%!assert (nargoutchk (0, 1, 2, "struct"), stmax)
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/strings/Makefile.in
--- a/scripts/strings/Makefile.in       Sat Mar 15 10:42:07 2008 -0400
+++ b/scripts/strings/Makefile.in       Sun Mar 16 20:55:44 2008 -0400
@@ -1,6 +1,6 @@
 # Makefile for octave's scripts/strings directory
 #
-# Copyright (C) 1994, 1995, 1996, 1997, 2002, 2005, 2006, 2007
+# Copyright (C) 1994, 1995, 1996, 1997, 2002, 2005, 2006, 2007, 2008
 #               John W. Eaton
 #
 # This file is part of Octave.
@@ -38,7 +38,7 @@ SOURCES = base2dec.m bin2dec.m blanks.m 
   lower.m mat2str.m rindex.m split.m str2double.m str2mat.m \
   str2num.m strcat.m cstrcat.m strcmpi.m strfind.m strjust.m strmatch.m \
   strncmpi.m strrep.m strtok.m strtrim.m strtrunc.m strvcat.m \
-  substr.m upper.m
+  substr.m upper.m validatestring.m
 
 DISTFILES = $(addprefix $(srcdir)/, Makefile.in $(SOURCES))
 
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/strings/validatestring.m
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/strings/validatestring.m  Sun Mar 16 20:55:44 2008 -0400
@@ -0,0 +1,144 @@
+## Copyright (C) 2008 Bill Denney
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} address@hidden =} validatestring (@var{str}, 
@var{strarray})
+## @deftypefnx {Function File} address@hidden =} validatestring (@var{str}, 
@var{strarray}, @var{funname})
+## @deftypefnx {Function File} address@hidden =} validatestring (@var{str}, 
@var{strarray}, @var{funname}, @var{varname})
+## @deftypefnx {Function File} address@hidden =} validatestring (@dots{}, 
@var{position})
+## Verify that @var{str} is a string or substring of an element of
+## @var{strarray}.
+##
+## @var{str} is a character string to be tested, and @var{strarray} is a
+## cellstr of valid values.  @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}.  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, and an
+## error will be raised if the matches are not substrings of each other.
+##
+## All comparisons are case insensitive.
+## @seealso{strcmp, strcmpi}
+## @end deftypefn
+
+## Author: Bill Denney <address@hidden>
+
+function str = validatestring (str, strarray, varargin)
+
+  if (nargin < 2 || nargin > 5)
+    print_usage ();
+  endif
+
+  ## set the defaults
+  funname = "";
+  varname = "";
+  position = 0;
+  ## set the actual values
+  if ! isempty (varargin)
+    if isnumeric (varargin{end})
+      position = varargin{end};
+      varargin(end) = [];
+    endif
+  endif
+  funnameset = false ();
+  varnameset = false ();
+  for i = 1:numel (varargin)
+    if ischar (varargin{i})
+      if varnameset
+        error ("validatestring: invalid number of character inputs: %d",
+               numel (varargin));
+      elseif funnameset
+        varname = varargin{i};
+        varnameset = true ();
+      else
+        funname = varargin{i};
+        funnameset = true ();
+      endif
+    endif
+  endfor
+
+  ## Check the inputs
+  if ! ischar (str)
+    error ("validatestring: str must be a character string")
+  elseif (rows (str) != 1)
+    error ("validatestring: str must have only one row")
+  elseif ! iscellstr (strarray)
+    error ("validatestring: strarray must be a cellstr")
+  elseif ! ischar (funname)
+    error ("validatestring: funname must be a character string")
+  elseif (! isempty (funname) && (rows (funname) != 1))
+    error ("validatestring: funname must be exactly one row")
+  elseif ! ischar (varname)
+    error ("validatestring: varname must be a character string")
+  elseif (! isempty (varname) && (rows (varname) != 1))
+    error ("validatestring: varname must be exactly one row")
+  elseif (position < 0)
+    error ("validatestring: position must be >= 0")
+  endif
+
+  ## make the part of the error that will use funname, varname, and
+  ## position
+  errstr = "";
+  if (! isempty (funname))
+    errstr = sprintf ("Function: %s ", funname);
+  endif
+  if (! isempty (varname))
+    errstr = sprintf ("%sVariable: %s ", errstr, varname);
+  endif
+  if (position > 0)
+    errstr = sprintf ("%sArgument position %d ", errstr, position);
+  endif
+  if (! isempty (errstr))
+    errstr(end:end+1) = ":\n";
+  endif
+
+  matches = strncmpi (str, strarray(:), numel (str));
+  nmatches = sum (matches);
+  if (nmatches == 1)
+    str = strarray{matches};
+  elseif (nmatches == 0)
+    error ("validatestring: %s%s does not match any of\n%s", errstr, str,
+           sprintf ("%s, ", strarray{:})(1:end-1));
+  else
+    ## are the matches a substring of each other, if so, choose the
+    ## shortest.  If not, raise an error.
+    match_idx = find (matches);
+    match_l = cellfun (@length, strarray(match_idx));
+    longest_idx = find (match_l == max (match_l), 1);
+    shortest_idx = find (match_l == min (match_l), 1);
+    longest = strarray(match_idx)(longest_idx);
+    for i = 1:numel(match_idx)
+      currentmatch = strarray(match_idx(i));
+      if (! strncmpi (longest, currentmatch, length(currentmatch)))
+        error (["validatestring: %smultiple unique matches were "
+                "found for %s:\n%s"],
+               errstr, sprintf("%s, ", strarray(match_idx))(1:end-2));
+      endif
+    endfor
+    str = strarray{shortest_idx};
+  endif
+
+endfunction
+
+## Tests
+%!shared strarray
+%!  strarray = {"octave" "Oct" "octopus" "octaves"};
+%!assert (validatestring ("octave", strarray), "octave")
+%!assert (validatestring ("oct", strarray), "Oct")
+%!assert (validatestring ("octave", strarray), "octave")
+%!assert (validatestring ("octav", strarray), "octave")
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/time/Makefile.in
--- a/scripts/time/Makefile.in  Sat Mar 15 10:42:07 2008 -0400
+++ b/scripts/time/Makefile.in  Sun Mar 16 20:55:44 2008 -0400
@@ -32,8 +32,8 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 
-SOURCES = asctime.m calendar.m clock.m ctime.m date.m datenum.m \
-  datestr.m datevec.m eomday.m etime.m is_leap_year.m now.m \
+SOURCES = addtodate.m asctime.m calendar.m clock.m ctime.m date.m \
+  datenum.m datestr.m datevec.m eomday.m etime.m is_leap_year.m now.m \
   weekday.m
 
 DISTFILES = $(addprefix $(srcdir)/, Makefile.in $(SOURCES))
diff -r d7f2e316ba22 -r c2fd7b04ccd2 scripts/time/addtodate.m
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/time/addtodate.m  Sun Mar 16 20:55:44 2008 -0400
@@ -0,0 +1,111 @@
+## Copyright (C) 2008 Bill Denney
+##
+## 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
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} address@hidden =} addtodate (@var{d}, @var{q}, 
@var{f})
+## Add @var{q} amount of time (with units @var{f}) to the datenum, @var{d}.
+##
+## @var{f} must be one of "year", "month", "day", "hour", "minute", or
+## "second".
+## @seealso{datenum, datevec}
+## @end deftypefn
+
+## Author: Bill Denney <address@hidden>
+
+function d = addtodate (d, q, f)
+
+  if (nargin != 3)
+    print_usage ();
+  elseif ! (ischar (f) && (rows (f) == 1))
+    ## FIXME: enhance the function so that it works with cellstrs of the
+    ## same size as the output.
+    error ("addtodate: f must be a single row character string.")
+  endif
+
+  if ((numel (d) == 1) && (numel (q) > 1))
+    ## expand d to the size of q if d only has one element to make
+    ## addition later eaiser.
+    d = d.*ones (size (q));
+  endif
+
+  ## in case the user gives f as a plural, remove the s
+  if ("s" == f(end))
+    f(end) = [];
+  endif
+
+  if any (strcmpi ({"year" "month"}, f))
+    dtmp = datevec (d);
+    if strcmpi ("year", f)
+      dtmp(:,1) += q(:);
+    elseif strcmpi ("month", f)
+      dtmp(:,2) += q(:);
+      ## adjust the years and months if the date rolls over a year
+      dtmp(:,1) += floor ((dtmp(:,2)-1)/12);
+      dtmp(:,2) = mod (dtmp(:,2)-1, 12) + 1;
+    endif
+    dnew = datenum (dtmp);
+    ## make the output the right shape
+    if (numel (d) == numel (dnew))
+      d = reshape (dnew, size (d));
+    else
+      d = reshape (dnew, size (q));
+    endif
+  elseif any (strcmpi ({"day" "hour" "minute" "second"}, f))
+    mult = struct ("day", 1, "hour", 1/24, "minute", 1/1440, "second", 
1/86400);
+    d += q.*mult.(f);
+  else
+    error ("addtodate: Invalid time unit: %s", f)
+  endif
+
+endfunction
+
+## tests
+%!shared d
+%!  d = datenum (2008, 1, 1);
+## Identity
+%!assert (addtodate (d, 0, "year"), d)
+%!assert (addtodate (d, 0, "month"), d)
+%!assert (addtodate (d, 0, "day"), d)
+%!assert (addtodate (d, 0, "hour"), d)
+%!assert (addtodate (d, 0, "minute"), d)
+%!assert (addtodate (d, 0, "second"), d)
+## Add one of each
+## leap year
+%!assert (addtodate (d, 1, "year"), d+366)
+%!assert (addtodate (d, 1, "month"), d+31)
+%!assert (addtodate (d, 1, "day"), d+1)
+%!assert (addtodate (d, 1, "hour"), d+1/24)
+%!assert (addtodate (d, 1, "minute"), d+1/1440)
+%!assert (addtodate (d, 1, "second"), d+1/86400)
+## substract one of each
+%!assert (addtodate (d, -1, "year"), d-365)
+%!assert (addtodate (d, -1, "month"), d-31)
+%!assert (addtodate (d, -1, "day"), d-1)
+%!assert (addtodate (d, -1, "hour"), d-1/24)
+%!assert (addtodate (d, -1, "minute"), d-1/1440)
+%!assert (addtodate (d, -1, "second"), d-1/86400)
+## rollover
+%!assert (addtodate (d, 12, "month"), d+366)
+%!assert (addtodate (d, 13, "month"), d+366+31)
+## multiple inputs and output orientation
+%!assert (addtodate ([d d], [1 13], "month"), [d+31 d+366+31])
+%!assert (addtodate ([d;d], [1;13], "month"), [d+31;d+366+31])
+%!assert (addtodate (d, [1;13], "month"), [d+31;d+366+31])
+%!assert (addtodate (d, [1 13], "month"), [d+31 d+366+31])
+%!assert (addtodate ([d;d+1], 1, "month"), [d+31;d+1+31])
+%!assert (addtodate ([d d+1], 1, "month"), [d+31 d+1+31])