Mercurial > octave
changeset 27973:8a07553faf2b
doc: Overhaul section about function argument validation (bug #57627).
* doc/interpreter/func.txi: Create new subsection "Validating Arguments" and
move description of most existing argument validation methods there in three
further subsubsections. New description for the "mustBe*" validator functions.
* scripts/miscellaneous/mustBeNonzero.m: Remove unnecessary curly braket.
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Wed, 22 Jan 2020 01:20:33 +0900 |
parents | 8f33435cfb00 |
children | c014440a2935 |
files | doc/interpreter/func.txi scripts/miscellaneous/mustBeNonzero.m |
diffstat | 2 files changed, 109 insertions(+), 39 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/func.txi Wed Jan 22 00:26:59 2020 +0900 +++ b/doc/interpreter/func.txi Wed Jan 22 01:20:33 2020 +0900 @@ -37,6 +37,7 @@ * Variable-length Argument Lists:: * Ignoring Arguments:: * Default Arguments:: +* Validating Arguments:: * Function Files:: * Script Files:: * Function Handles Anonymous Functions Inline Functions:: @@ -426,49 +427,13 @@ @DOCSTRING(nargout) -It is good practice at the head of a function to verify that it has been called -correctly. In Octave the following idiom is seen frequently - -@example -@group -if (nargin < min_#_inputs || nargin > max_#_inputs) - print_usage (); -endif -@end group -@end example - -@noindent -which stops the function execution and prints a message about the correct -way to call the function whenever the number of inputs is wrong. - -For compatibility with @sc{matlab}, @code{narginchk} and @code{nargoutchk} are -available which provide similar error checking. - -@DOCSTRING(narginchk) - -@DOCSTRING(nargoutchk) - -Besides the number of arguments, inputs can be checked for various properties. -@code{validatestring} is used for string arguments and -@code{validateattributes} for numeric arguments. - -@DOCSTRING(validatestring) - -@DOCSTRING(validateattributes) - -If none of the preceding functions is sufficient there is also the class -@code{inputParser} which can perform extremely complex input checking for -functions. - -@DOCSTRING(inputParser) - -@anchor{XREFvarargin} @anchor{XREFvarargout} - @node Variable-length Return Lists @section Variable-length Return Lists @cindex variable-length return lists @cindex @code{varargout} +@anchor{XREFvarargout} + It is possible to return a variable number of output arguments from a function using a syntax that's similar to the one used with the special @code{varargin} parameter name. To let a function return a @@ -512,6 +477,8 @@ @cindex variable-length argument lists @cindex @code{varargin} +@anchor{XREFvarargin} + Sometimes the number of input arguments is not known when the function is defined. As an example think of a function that returns the smallest of all its input arguments. For example: @@ -677,6 +644,7 @@ @end example @DOCSTRING(isargout) + @node Default Arguments @section Default Arguments @cindex default arguments @@ -740,6 +708,108 @@ @end group @end example +@node Validating Arguments +@section Validating Arguments +@cindex validating arguments + +Octave is a weakly typed programming language. Thus it is possible to +call a function with arguments, that probably cause errors or might have +undesirable side effects. For example calling a string processing function +with a huge sparse matrix. + +It is good practice at the head of a function to verify that it has been +called correctly. Octave offers several functions for this purpose. + +@menu +* Validating the number of Arguments:: +* Validating the type of Arguments:: +* Parsing Arguments:: +@end menu + +@node Validating the number of Arguments +@subsection Validating the number of Arguments + +In Octave the following idiom is seen frequently at the beginning of a +function definition: + +@example +@group +if (nargin < min_#_inputs || nargin > max_#_inputs) + print_usage (); +endif +@end group +@end example + +@noindent +which stops the function execution and prints a message about the correct +way to call the function whenever the number of inputs is wrong. + +Similar error checking is provided by @code{narginchk} and +@code{nargoutchk}. + +@DOCSTRING(narginchk) + +@DOCSTRING(nargoutchk) + +@node Validating the type of Arguments +@subsection Validating the type of Arguments + +Besides the number of arguments, inputs can be checked for various +properties. @code{validatestring} is used for string arguments and +@code{validateattributes} for numeric arguments. + +@DOCSTRING(validatestring) + +@DOCSTRING(validateattributes) + +As alternative to @code{validateattributes} there are several shorter +convenience functions to check for individual properties. + +@DOCSTRING(mustBeFinite) + +@DOCSTRING(mustBeGreaterThan) + +@DOCSTRING(mustBeGreaterThanOrEqual) + +@DOCSTRING(mustBeInteger) + +@DOCSTRING(mustBeLessThan) + +@DOCSTRING(mustBeLessThanOrEqual) + +@DOCSTRING(mustBeMember) + +@DOCSTRING(mustBeNegative) + +@DOCSTRING(mustBeNonempty) + +@DOCSTRING(mustBeNonNan) + +@DOCSTRING(mustBeNonnegative) + +@DOCSTRING(mustBeNonpositive) + +@DOCSTRING(mustBeNonsparse) + +@DOCSTRING(mustBeNonzero) + +@DOCSTRING(mustBeNumeric) + +@DOCSTRING(mustBeNumericOrLogical) + +@DOCSTRING(mustBePositive) + +@DOCSTRING(mustBeReal) + +@node Parsing Arguments +@subsection Parsing Arguments + +If none of the preceding validation functions is sufficient there is also +the class @code{inputParser} which can perform extremely complex input +checking for functions. + +@DOCSTRING(inputParser) + @node Function Files @section Function Files @cindex function file
--- a/scripts/miscellaneous/mustBeNonzero.m Wed Jan 22 00:26:59 2020 +0900 +++ b/scripts/miscellaneous/mustBeNonzero.m Wed Jan 22 01:20:33 2020 +0900 @@ -24,7 +24,7 @@ ######################################################################## ## -*- texinfo -*- -## @deftypefn {} {} {mustBeNonzero (@var{x}) +## @deftypefn {} {} mustBeNonzero (@var{x}) ## ## Requires that input @var{x} is not zero. ##