octave_packages/m/general/nargoutchk.m

   1 ## Copyright (C) 2008-2012 Bill Denney
   2 ## Copyright (C) 2012 Carnë Draug
   3 ##
   4 ## This file is part of Octave.
   5 ##
   6 ## Octave is free software; you can redistribute it and/or modify it
   7 ## under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 3 of the License, or (at
   9 ## your option) any later version.
  10 ##
  11 ## Octave is distributed in the hope that it will be useful, but
  12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 ## General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with Octave; see the file COPYING.  If not, see
  18 ## <http://www.gnu.org/licenses/>.
  19
  20 ## -*- texinfo -*-
  21 ## @deftypefn  {Function File} {} nargoutchk (@var{minargs}, @var{maxargs})
  22 ## @deftypefnx {Function File} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs})
  23 ## @deftypefnx {Function File} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string")
  24 ## @deftypefnx {Function File} {@var{msgstruct} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct")
  25 ## Check for correct number of output arguments.
  26 ##
  27 ## On the first form, returns an error unless the number of arguments in its
  28 ## caller is between the values of @var{minargs} and @var{maxargs}.  It does
  29 ## nothing otherwise.  Note that this function evaluates the value of
  30 ## @code{nargout} on the caller so its value must have not been tampered with.
  31 ##
  32 ## Both @var{minargs} and @var{maxargs} need to be a numeric scalar.  Zero, Inf
  33 ## and negative are all valid, and they can have the same value.
  34 ##
  35 ## For backward compatibility reasons, the other forms return an appropriate
  36 ## error message string (or structure) if the number of outputs requested is
  37 ## invalid.
  38 ##
  39 ## This is useful for checking to see that the number of output
  40 ## arguments supplied to a function is within an acceptable range.
  41 ## @seealso{nargchk, narginchk, error, nargout, nargin}
  42 ## @end deftypefn
  43
  44 ## Author: Bill Denney <bill@denney.ws>
  45 ## Author: Carnë Draug <carandraug+dev@gmail.com>
  46
  47 function msg = nargoutchk (minargs, maxargs, nargs, outtype)
  48
  49   ## before matlab's 2011b, nargoutchk would return an error message (just the
  50   ## message in a string). With 2011b, it no longer returns anything, it simply
  51   ## gives an error if the args number is incorrect.
  52   ## To try to keep compatibility with both versions, check nargout and nargin
  53   ## to guess if the caller is expecting a value (old syntax) or none (new syntax)
  54
  55   if (nargout == 1 && (nargin == 3 || nargin == 4))
  56
  57     if (minargs > maxargs)
  58       error ("nargoutchk: MINARGS must be <= MAXARGS");
  59     elseif (nargin == 3)
  60       outtype = "string";
  61     elseif (! any (strcmpi (outtype, {"string" "struct"})))
  62       error ("nargoutchk: output type must be either string or struct");
  63     elseif (! (isscalar (minargs) && isscalar (maxargs) && isscalar (nargs)))
  64       error ("nargoutchk: MINARGS, MAXARGS, and NARGS must be scalars");
  65     endif
  66
  67     msg = struct ("message", "", "identifier", "");
  68     if (nargs < minargs)
  69       msg.message = "not enough output arguments";
  70       msg.identifier = "Octave:nargoutchk:not-enough-outputs";
  71     elseif (nargs > maxargs)
  72       msg.message = "too many output arguments";
  73       msg.identifier = "Octave:nargoutchk:too-many-outputs";
  74     endif
  75
  76     if (strcmpi (outtype, "string"))
  77       msg = msg.message;
  78     elseif (isempty (msg.message))
  79       ## Compatability: Matlab returns a 0x1 empty struct when nargchk passes
  80       msg = resize (msg, 0, 1);
  81     endif
  82
  83   elseif (nargout == 0 && nargin == 2)
  84
  85     if (!isnumeric (minargs) || !isscalar (minargs))
  86       error ("minargs must be a numeric scalar");
  87     elseif (!isnumeric (maxargs) || !isscalar (maxargs))
  88       error ("maxargs must be a numeric scalar");
  89     elseif (minargs > maxargs)
  90       error ("minargs cannot be larger than maxargs")
  91     endif
  92
  93     args = evalin ("caller", "nargout;");
  94
  95     if (args < minargs)
  96       error ("Not enough output arguments.");
  97     elseif (args > maxargs)
  98       error ("Too many output arguments.");
  99     endif
 100
 101   else
 102     print_usage;
 103   endif
 104
 105 endfunction
 106
 107 ## Tests
 108 %!shared stnul, stmin, stmax
 109 %!  stnul = resize (struct ("message", "", "identifier", ""), 0, 1);
 110 %!  stmin = struct ("message", "not enough output arguments",
 111 %!                  "identifier", "Octave:nargoutchk:not-enough-outputs");
 112 %!  stmax = struct ("message", "too many output arguments",
 113 %!                  "identifier", "Octave:nargoutchk:too-many-outputs");
 114 %!assert (nargoutchk (0, 1, 0), "")
 115 %!assert (nargoutchk (0, 1, 1), "")
 116 %!assert (nargoutchk (1, 1, 0), "not enough output arguments")
 117 %!assert (nargoutchk (0, 1, 2), "too many output arguments")
 118 %!assert (nargoutchk (0, 1, 2, "string"), "too many output arguments")
 119 ## Struct outputs
 120 %!assert (isequal (nargoutchk (0, 1, 0, "struct"), stnul))
 121 %!assert (isequal (nargoutchk (0, 1, 1, "struct"), stnul))
 122 %!assert (nargoutchk (1, 1, 0, "struct"), stmin)
 123 %!assert (nargoutchk (0, 1, 2, "struct"), stmax)
 124