diff options
Diffstat (limited to 'doc/return.n')
| -rw-r--r-- | doc/return.n | 118 |
1 files changed, 85 insertions, 33 deletions
diff --git a/doc/return.n b/doc/return.n index 2ea381d..685e0be 100644 --- a/doc/return.n +++ b/doc/return.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: return.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $ +'\" RCS: @(#) $Id: return.n,v 1.3.18.1 2004/10/27 14:23:58 dkf Exp $ '\" .so man.macros .TH return n 7.0 Tcl "Tcl Built-In Commands" @@ -23,43 +23,45 @@ Return immediately from the current procedure (or top-level command or \fBsource\fR command), with \fIstring\fR as the return value. If \fIstring\fR is not specified then an empty string will be returned as result. - -.SH "EXCEPTIONAL RETURNS" +.SH "EXCEPTIONAL RETURN CODES" .PP +In addition to the result of a procedure, the return +code of a procedure may also be set by \fBreturn\fR +through use of the \fB-code\fR option. In the usual case where the \fB\-code\fR option isn't -specified the procedure will return normally (its completion -code will be TCL_OK). +specified the procedure will return normally. However, the \fB\-code\fR option may be used to generate an exceptional return from the procedure. \fICode\fR may have any of the following values: -.TP 10 -\fBok\fR -Normal return: same as if the option is omitted. -.TP 10 -\fBerror\fR -Error return: same as if the \fBerror\fR command were used to -terminate the procedure, except for handling of \fBerrorInfo\fR -and \fBerrorCode\fR variables (see below). -.TP 10 -\fBreturn\fR -The current procedure will return with a completion code of -TCL_RETURN, so that the procedure that invoked it will return -also. -.TP 10 -\fBbreak\fR -The current procedure will return with a completion code of -TCL_BREAK, which will terminate the innermost nested loop in -the code that invoked the current procedure. -.TP 10 -\fBcontinue\fR -The current procedure will return with a completion code of -TCL_CONTINUE, which will terminate the current iteration of -the innermost nested loop in the code that invoked the current -procedure. -.TP 10 +.TP 13 +\fBok (or 0)\fR +Normal return: same as if the option is omitted. The return code +of the procedure is 0 (\fBTCL_OK\fR). +.TP 13 +\fBerror (1)\fR +Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). +The procedure command behaves in its calling context as if it +were the command \fBerror \fIresult\fR. See below for additional +options. +.TP 13 +\fBreturn (2)\fR +The return code of the procedure is 2 (\fBTCL_RETURN\fR). The +procedure command behaves in its calling context as if it +were the command \fBreturn\fR (with no arguments). +.TP 13 +\fBbreak (3)\fR +The return code of the procedure is 3 (\fBTCL_BREAK\fR). The +procedure command behaves in its calling context as if it +were the command \fBbreak\fR. +.TP 13 +\fBcontinue (4)\fR +The return code of the procedure is 4 (\fBTCL_CONTINUE\fR). The +procedure command behaves in its calling context as if it +were the command \fBcontinue\fR. +.TP 13 \fIvalue\fR \fIValue\fR must be an integer; it will be returned as the -completion code for the current procedure. +return code for the current procedure. .LP The \fB\-code\fR option is rarely used. It is provided so that procedures that implement @@ -84,9 +86,59 @@ If the \fB\-errorcode\fR option is specified then \fIcode\fR provides a value for the \fBerrorCode\fR variable. If the option is not specified then \fBerrorCode\fR will default to \fBNONE\fR. +.SH EXAMPLES +First, a simple example of using \fBreturn\fR to return from a +procedure, interrupting the procedure body. +.CS +proc printOneLine {} { + puts "line 1" ;# This line will be printed. + \fBreturn\fR + puts "line 2" ;# This line will not be printed. +} +.CE +.PP +Next, an example of using \fBreturn\fR to set the value +returned by the procedure. +.CS +proc returnX {} {\fBreturn\fR X} +puts [returnX] ;# prints "X" +.CE +.PP +Next, a more complete example, using \fBreturn -code error\fR +to report invalid arguments. +.CS +proc factorial {n} { + if {![string is integer $n] || ($n < 0)} { + \fBreturn\fR -code error \\ + "expected non-negative integer,\\ + but got \\"$n\\"" + } + if {$n < 2} { + \fBreturn\fR 1 + } + set m [expr {$n - 1}] + set code [catch {factorial $m} factor] + if {$code != 0} { + \fBreturn\fR -code $code $factor + } + set product [expr {$n * $factor}] + if {$product < 0} { + \fBreturn\fR -code error \\ + "overflow computing factorial of $n" + } + \fBreturn\fR $product +} +.CE +.PP +Next, a procedure replacement for \fBbreak\fR. +.CS +proc myBreak {} { + \fBreturn\fR -code break +} +.CE .SH "SEE ALSO" -break(n), continue(n), error(n), proc(n) +break(n), catch(n), continue(n), error(n), proc(n), source(n), tclvars(n) .SH KEYWORDS -break, continue, error, procedure, return +break, catch, continue, error, procedure, return |