# HG changeset patch
# User Andrew Janke <andrew@apjanke.net>
# Date 1579364911 18000
#      Sat Jan 18 11:28:31 2020 -0500
# Node ID e2f5ff5c1f01f8d31cf98fe4c6933c4095f2d032
# Parent  27a5cc0614f1724f854133cc333954d624e9f08a
Validator functions implementation (bug #57627).

- NEWS: Announce new functions.

- scripts/help/__unimplemented__.m: Remove new functions from list.

- scripts/micellaneous/module.mk: Add new functions to build system.

- scripts/micellaneous/mustBe*.m: Add validator function.

diff -r 27a5cc0614f1 -r e2f5ff5c1f01 NEWS
--- a/NEWS	Sat Jan 18 05:38:18 2020 -0800
+++ b/NEWS	Sat Jan 18 11:28:31 2020 -0500
@@ -167,6 +167,8 @@ Summary of important user-visible change
 - An undocumented function `gui_mainfcn` has been added, for compatibility
   with figures created with Matlab's GUIDE.
 
+- Several validator functions of type `mustBe*` have been added.
+
 ### Alphabetical list of new functions added in Octave 6
 
 * `commandhistory`
@@ -174,6 +176,24 @@ Summary of important user-visible change
 * `filebrowser`
 * `is_same_file`
 * `lightangle`
+* `mustBeFinite`
+* `mustBeGreaterThan`
+* `mustBeGreaterThanOrEqual`
+* `mustBeInteger`
+* `mustBeLessThan`
+* `mustBeLessThanOrEqual`
+* `mustBeMember`
+* `mustBeNegative`
+* `mustBeNonempty`
+* `mustBeNonNan`
+* `mustBeNonnegative`
+* `mustBeNonpositive`
+* `mustBeNonsparse`
+* `mustBeNonzero`
+* `mustBeNumeric`
+* `mustBeNumericOrLogical`
+* `mustBePositive`
+* `mustBeReal`
 * `namedargs2cell`
 * `newline`
 * `rescale`
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/help/__unimplemented__.m
--- a/scripts/help/__unimplemented__.m	Sat Jan 18 05:38:18 2020 -0800
+++ b/scripts/help/__unimplemented__.m	Sat Jan 18 11:28:31 2020 -0500
@@ -1013,24 +1013,6 @@ function rlist = missing_functions ()
   "mput",
   "multibandread",
   "multibandwrite",
-  "mustBeFinite",
-  "mustBeGreaterThan",
-  "mustBeGreaterThanOrEqual",
-  "mustBeInteger",
-  "mustBeLessThan",
-  "mustBeLessThanOrEqual",
-  "mustBeMember",
-  "mustBeNegative",
-  "mustBeNonempty",
-  "mustBeNonNan",
-  "mustBeNonnegative",
-  "mustBeNonpositive",
-  "mustBeNonsparse",
-  "mustBeNonzero",
-  "mustBeNumeric",
-  "mustBeNumericOrLogical",
-  "mustBePositive",
-  "mustBeReal",
   "NaT",
   "nccreate",
   "ncdisp",
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/module.mk
--- a/scripts/miscellaneous/module.mk	Sat Jan 18 05:38:18 2020 -0800
+++ b/scripts/miscellaneous/module.mk	Sat Jan 18 11:28:31 2020 -0500
@@ -52,6 +52,24 @@ FCN_FILE_DIRS += \
   %reldir%/mkdir.m \
   %reldir%/mkoctfile.m \
   %reldir%/movefile.m \
+  %reldir%/mustBeFinite \
+  %reldir%/mustBeGreaterThan \
+  %reldir%/mustBeGreaterThanOrEqual \
+  %reldir%/mustBeInteger \
+  %reldir%/mustBeLessThan \
+  %reldir%/mustBeLessThanOrEqual \
+  %reldir%/mustBeMember \
+  %reldir%/mustBeNegative \
+  %reldir%/mustBeNonempty \
+  %reldir%/mustBeNonNan \
+  %reldir%/mustBeNonnegative \
+  %reldir%/mustBeNonpositive \
+  %reldir%/mustBeNonsparse \
+  %reldir%/mustBeNonzero \
+  %reldir%/mustBeNumeric \
+  %reldir%/mustBeNumericOrLogical \
+  %reldir%/mustBePositive \
+  %reldir%/mustBeReal \
   %reldir%/namedargs2cell.m \
   %reldir%/namelengthmax.m \
   %reldir%/nargchk.m \
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeFinite.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeFinite.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,47 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeFinite (@var{x})
+##
+## Requires that input @var{x} is finite.
+##
+## Raises an error if any element of the input @var{x} is not finite, as
+## determined by @code{isfinite (x)}.
+##
+## @end deftypefn
+
+function x = mustBeFinite (x)
+  tf = isfinite (x);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (!tf);
+    error ("%s must be finite; got Infs in %d elements: indexes %s", ...
+      label, numel (ix_bad), mat2str (ix_bad));
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeGreaterThan.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeGreaterThan.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,55 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeGreaterThan (@var{x}, @var{c})
+##
+## Requires that input @var{x} is greater than @var{c}.
+##
+## Raises an error if any element of the input @var{x} is not greater than
+## @var{c}, as determined by @code{@var{x} > @var{c}}.
+##
+## @end deftypefn
+
+function x = mustBeGreaterThan (x, c)
+  tf = x > c;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ("%s must be greater than %f; got %d elements that were not: values %s", ...
+        label, c, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ("%s must be greater than %f; got %d elements that were not: indexes %s", ...
+        label, c, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeGreaterThanOrEqual.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeGreaterThanOrEqual.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeGreaterThanOrEqual (@var{x}, @var{c})
+##
+## Requires that input @var{x} is greater than or equal to @var{c}.
+##
+## Raises an error if any element of the input @var{x} is not greater than
+## or equal to @var{c}, as determined by @code{@var{x} >= @var{c}}.
+##
+## @end deftypefn
+
+function x = mustBeGreaterThanOrEqual (x, c)
+  tf = x >= c;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be greater than or equal to %f; got %d elements that were not: values %s", ...
+        label, c, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be greater than or equal to %f; got %d elements that were not: indexes %s", ...
+        label, c, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeInteger.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeInteger.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,58 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeInteger (@var{x})
+##
+## Requires that input @var{x} is integer-valued (but not necessarily
+## integer-typed).
+##
+## Raises an error if any element of the input @var{x} is not a finite,
+## real, integer-valued numeric value, as determined by various checks.
+##
+## @end deftypefn
+
+function x = mustBeInteger (x)
+  if isinteger (x) || islogical (x)
+    return
+  endif
+  but = [];
+  if ! isnumeric (x)
+    but = sprintf ("it was non-numeric (got a %s)", class (x));
+  elseif any (! isfinite (x))
+    but = "there were Inf values";
+  elseif ! isreal (x)
+    but = "it was complex";
+  elseif ! all (floor (x) == x)
+    but = "it had fractional values in some elements";
+  end
+  if ! isempty (but)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be integer-valued; but %s", label, but);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeLessThan.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeLessThan.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeLessThan (@var{x}, @var{c})
+##
+## Requires that input @var{x} is less than @var{c}.
+##
+## Raises an error if any element of the input @var{x} is not less than
+## @var{c}, as determined by @code{@var{x} < @var{c}}.
+##
+## @end deftypefn
+
+function x = mustBeLessThan (x, c)
+  tf = x < c;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be less than %f; got %d elements that were not: values %s", ...
+        label, c, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be less than %f; got %d elements that were not: indexes %s", ...
+        label, c, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeLessThanOrEqual.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeLessThanOrEqual.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeLessThanOrEqual (@var{x}, @var{c})
+##
+## Requires that input is less than or equal to a given value.
+##
+## Raises an error if any element of the input @var{x} is not less than
+## or equal to @var{c}, as determined by @code{@var{x} <= @var{c}}.
+##
+## @end deftypefn
+
+function x = mustBeLessThanOrEqual (x, c)
+  tf = x <= c;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be less than or equal to %f; got %d elements that were not: values %s", ...
+        label, c, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be less than or equal to %f; got %d elements that were not: indexes %s", ...
+        label, c, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeMember.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeMember.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,54 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeMember (@var{x}, @var{valid})
+##
+## Requires that input @var{x} is a member of a set of given valid values.
+##
+## Raises an error if any element of the input @var{x} is not a member
+## of @var{valid}, as determined by @code{ismember (@var{x})}.
+##
+## Note that char inputs may behave weirdly, because of the interaction
+## between chars and cellstrings when calling ismember() on them.  But it
+## will probably "do what you mean" if you just use it naturally.
+##
+## @end deftypefn
+
+function x = mustBeMember (x, valid)
+  tf = ismember (x, valid);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    n_bad = numel (find (! tf));
+    # TODO: Fancy inclusion of bad & valid values in the error message.
+    # Probably use mat2str() in a try/catch for that.
+    error ( ...
+      "%s must be one of the specified valid values; got %d elements that weren't", ...
+      label, n_bad);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNegative.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNegative.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNegative (@var{x})
+##
+## Requires that input @var{x} is negative.
+##
+## Raises an error if any element of the input @var{x} is not negative, as
+## determined by @code{@var{x} < 0}.
+##
+## @end deftypefn
+
+function x = mustBeNegative (x)
+  tf = x < 0;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be negative; got %d elements that were not: values %s", ...
+        label, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be negative; got %d elements that were not: indexes %s", ...
+        label, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonNan.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonNan.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,50 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonNan (@var{x})
+##
+## Requires that input @var{x} is non-NaN.
+##
+## Raises an error if any element of the input @var{x} is NaN, as determined
+## by @code{isnan (@var{x})}.
+##
+## @end deftypefn
+
+function x = mustBeNonNan (x)
+  tf = ! isnan (x);
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    errmsg = sprintf ( ...
+      "%s must be non-NaN; got %d elements that were not: indexes %s", ...
+      label, numel (ix_bad), mat2str (ix_bad));
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonempty.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonempty.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,44 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonempty (@var{x})
+##
+## Requires that input @var{x} is nonempty.
+##
+## Raises an error if the input @var{x} is not empty, as determined by
+## @code{! isempty (@var{x})}.
+##
+## @end deftypefn
+
+function x = mustBeNonempty (x)
+  if isempty (x)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be nonempty; got an empty", label);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonnegative.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonnegative.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonnegative (@var{x})
+##
+## Requires that input @var{x} is not negative.
+##
+## Raises an error if any element of the input @var{x} is negative, as
+## determined by @code{@var{x} >= 0}.
+##
+## @end deftypefn
+
+function x = mustBeNonnegative (x)
+  tf = x >= 0;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be non-negative; got %d elements that were not: values %s", ...
+        label, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be non-negative; got %d elements that were not: indexes %s", ...
+        label, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonpositive.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonpositive.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonpositive (@var{x})
+##
+## Requires that input @var{x} is not positive.
+##
+## Raises an error if any element of the input @var{x} is positive, as
+## determined by @code{@var{x} <= 0}.
+##
+## @end deftypefn
+
+function x = mustBeNonpositive (x)
+  tf = x <= 0;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be non-positive; got %d elements that were not: values %s", ...
+        label, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be non-positive; got %d elements that were not: indexes %s", ...
+        label, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonsparse.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonsparse.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,44 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonsparse (@var{x})
+##
+## Requires that input @var{x} is not sparse.
+##
+## Raises an error if the input @var{x} is sparse, as determined by
+## @code{issparse (@var{x})}.
+##
+## @end deftypefn
+
+function x = mustBeNonsparse (x)
+  if issparse (x)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be nonsparse; got a sparse array", label);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNonzero.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNonzero.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,50 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNonzero (@var{x})
+##
+## Requires that input @var{x} is not zero.
+##
+## Raises an error if any element of the input @var{x} is zero, as determined
+## by @code{@var{x} != 0}.
+##
+## @end deftypefn
+
+function x = mustBeNonzero (x)
+  tf = x != 0;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    errmsg = sprintf ( ...
+      "%s must be non-zero; got %d elements that were zero: indexes %s", ...
+      label, numel (ix_bad), mat2str (ix_bad));
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNumeric.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNumeric.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,44 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNumeric (@var{x})
+##
+## Requires that input @var{x} is numeric.
+##
+## Raises an error if the input @var{x} is not numeric, as determined by
+## @code{isnumeric (@var{x})}.
+##
+## @end deftypefn
+
+function x = mustBeNumeric (x)
+  if ! isnumeric (x)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be numeric; got a %s", label, class (x));
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeNumericOrLogical.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeNumericOrLogical.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,44 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBeNumericOrLogical (@var{x})
+##
+## Requires that input @var{x} is numeric or logical.
+##
+## Raises an error if the input @var{x} is not numeric or logical, as
+## determined by @code{isnumeric (@var{x}) || islogical (@var{x})}.
+##
+## @end deftypefn
+
+function x = mustBeNumericOrLogical (x)
+  if ! (isnumeric (x) || islogical (x))
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be numeric or logical; got a %s", label, class (x));
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBePositive.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBePositive.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,57 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{x} =} mustBePositive (@var{x})
+##
+## Requires that input @var{x} is positive.
+##
+## Raises an error if any element of the input @var{x} is not positive, as
+## determined by @code{@var{x} > 0}.
+##
+## @end deftypefn
+
+function x = mustBePositive (x)
+  tf = x > 0;
+  tf = tf(:);
+  if ! all (tf)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    ix_bad = find (! tf);
+    try
+      bad = x(ix_bad);
+      errmsg = sprintf ( ...
+        "%s must be positive; got %d elements that were not: values %s", ...
+        label, numel (ix_bad), mat2str (bad));
+    catch err
+      errmsg = sprintf ( ...
+        "%s must be positive; got %d elements that were not: indexes %s", ...
+        label, numel (ix_bad), mat2str (ix_bad));
+    end_try_catch
+    error (errmsg);
+  endif
+endfunction
diff -r 27a5cc0614f1 -r e2f5ff5c1f01 scripts/miscellaneous/mustBeReal.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/miscellaneous/mustBeReal.m	Sat Jan 18 11:28:31 2020 -0500
@@ -0,0 +1,44 @@
+########################################################################
+##
+## Copyright (C) 2019-2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## 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
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {@code{x} =} mustBeReal (@code{x})
+##
+## Requires that input is real.
+##
+## Raises an error if the input @code{x} is not real, as determined by
+## @code{isreal (x)}.
+##
+## @end deftypefn
+
+function x = mustBeReal (x)
+  if ! isreal (x)
+    label = inputname (1);
+    if isempty (label)
+      label = "input";
+    endif
+    error ("%s must be real; got a complex value", label);
+  endif
+endfunction
