Mercurial > octave
changeset 27972:8f33435cfb00
doc: * doc/interpreter/func.txi: Reorder nodes for clarity.
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Wed, 22 Jan 2020 00:26:59 +0900 |
parents | ec769a7ab9fb |
children | 8a07553faf2b |
files | doc/interpreter/func.txi |
diffstat | 1 files changed, 94 insertions(+), 94 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/func.txi Tue Jan 21 09:20:15 2020 -0600 +++ b/doc/interpreter/func.txi Wed Jan 22 00:26:59 2020 +0900 @@ -31,11 +31,11 @@ @menu * Introduction to Function and Script Files:: * Defining Functions:: +* Returning from a Function:: * Multiple Return Values:: +* Variable-length Return Lists:: * Variable-length Argument Lists:: * Ignoring Arguments:: -* Variable-length Return Lists:: -* Returning from a Function:: * Default Arguments:: * Function Files:: * Script Files:: @@ -276,6 +276,54 @@ @DOCSTRING(silent_functions) +@node Returning from a Function +@section Returning from a Function + +The body of a user-defined function can contain a @code{return} statement. +This statement returns control to the rest of the Octave program. It +looks like this: + +@example +return +@end example + +Unlike the @code{return} statement in C, Octave's @code{return} +statement cannot be used to return a value from a function. Instead, +you must assign values to the list of return variables that are part of +the @code{function} statement. The @code{return} statement simply makes +it easier to exit a function from a deeply nested loop or conditional +statement. + +Here is an example of a function that checks to see if any elements of a +vector are nonzero. + +@example +@group +function retval = any_nonzero (v) + retval = 0; + for i = 1:length (v) + if (v (i) != 0) + retval = 1; + return; + endif + endfor + printf ("no nonzero elements found\n"); +endfunction +@end group +@end example + +Note that this function could not have been written using the +@code{break} statement to exit the loop once a nonzero value is found +without adding extra logic to avoid printing the message if the vector +does contain a nonzero element. + +@deftypefn {} {} return +When Octave encounters the keyword @code{return} inside a function or +script, it returns control to the caller immediately. At the top level, +the return statement is ignored. A @code{return} statement is assumed +at the end of every function definition. +@end deftypefn + @node Multiple Return Values @section Multiple Return Values @@ -415,6 +463,50 @@ @DOCSTRING(inputParser) @anchor{XREFvarargin} @anchor{XREFvarargout} + +@node Variable-length Return Lists +@section Variable-length Return Lists +@cindex variable-length return lists +@cindex @code{varargout} + +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 +variable number of output arguments the special output parameter name +@code{varargout} is used. As with @code{varargin}, @code{varargout} is +a cell array that will contain the requested output arguments. + +As an example the following function sets the first output argument to +1, the second to 2, and so on. + +@example +@group +function varargout = one_to_n () + for i = 1:nargout + varargout@{i@} = i; + endfor +endfunction +@end group +@end example + +@noindent +When called this function returns values like this + +@example +@group +[a, b, c] = one_to_n () + @result{} a = 1 + @result{} b = 2 + @result{} c = 3 +@end group +@end example + +If @code{varargin} (@code{varargout}) does not appear as the last +element of the input (output) parameter list, then it is not special, +and is handled the same as any other parameter name. + +@DOCSTRING(deal) + @node Variable-length Argument Lists @section Variable-length Argument Lists @cindex variable-length argument lists @@ -585,98 +677,6 @@ @end example @DOCSTRING(isargout) - -@node Variable-length Return Lists -@section Variable-length Return Lists -@cindex variable-length return lists -@cindex @code{varargout} - -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 -variable number of output arguments the special output parameter name -@code{varargout} is used. As with @code{varargin}, @code{varargout} is -a cell array that will contain the requested output arguments. - -As an example the following function sets the first output argument to -1, the second to 2, and so on. - -@example -@group -function varargout = one_to_n () - for i = 1:nargout - varargout@{i@} = i; - endfor -endfunction -@end group -@end example - -@noindent -When called this function returns values like this - -@example -@group -[a, b, c] = one_to_n () - @result{} a = 1 - @result{} b = 2 - @result{} c = 3 -@end group -@end example - -If @code{varargin} (@code{varargout}) does not appear as the last -element of the input (output) parameter list, then it is not special, -and is handled the same as any other parameter name. - -@DOCSTRING(deal) - -@node Returning from a Function -@section Returning from a Function - -The body of a user-defined function can contain a @code{return} statement. -This statement returns control to the rest of the Octave program. It -looks like this: - -@example -return -@end example - -Unlike the @code{return} statement in C, Octave's @code{return} -statement cannot be used to return a value from a function. Instead, -you must assign values to the list of return variables that are part of -the @code{function} statement. The @code{return} statement simply makes -it easier to exit a function from a deeply nested loop or conditional -statement. - -Here is an example of a function that checks to see if any elements of a -vector are nonzero. - -@example -@group -function retval = any_nonzero (v) - retval = 0; - for i = 1:length (v) - if (v (i) != 0) - retval = 1; - return; - endif - endfor - printf ("no nonzero elements found\n"); -endfunction -@end group -@end example - -Note that this function could not have been written using the -@code{break} statement to exit the loop once a nonzero value is found -without adding extra logic to avoid printing the message if the vector -does contain a nonzero element. - -@deftypefn {} {} return -When Octave encounters the keyword @code{return} inside a function or -script, it returns control to the caller immediately. At the top level, -the return statement is ignored. A @code{return} statement is assumed -at the end of every function definition. -@end deftypefn - @node Default Arguments @section Default Arguments @cindex default arguments