Added EXAMPLES to return.n

1 files changed, 96 insertions, 1 deletions

diff --git a/doc/return.n b/doc/return.n
index 50407e9..7afe66c 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -6,7 +6,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.5 2003/09/02 16:48:22 dgp Exp $
+'\" RCS: @(#) $Id: return.n,v 1.6 2003/09/02 18:51:31 dgp Exp $
 '\" 
 .so man.macros
 .TH return n 8.5 Tcl "Tcl Built-In Commands"
@@ -201,6 +201,101 @@ for the \fB-level\fR option (including the default value of 1)
 will cause the return code of the \fBreturn\fR command itself
 to be TCL_RETURN, triggering a return from the enclosing procedure.
 
+.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.
+    return		
+    puts "line 2"    ;# This line will not be printed.
+}
+.CE
+
+Next, an example of using \fBreturn\fR to set the value
+returned by the procedure.
+
+.CS
+proc returnX {} {return X}
+puts [returnX]    ;# prints "X"
+.CE
+
+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)} {
+        return -code error \\
+                "expected non-negative integer,\\
+                 but got \\"$n\\""
+    }
+    if {$n < 2} {
+        return 1
+    }
+    set m [expr {$n - 1}]
+    set code [catch {factorial $m} factor]
+    if {$code != 0} {
+        return -code $code $factor
+    }
+    set product [expr {$n * $factor}]
+    if {$product < 0} {
+        return -code error \\
+                "overflow computing factorial of $n"
+    }
+    return $product
+}
+.CE
+
+Next, a procedure replacement for \fBbreak\fR.
+
+.CS
+proc myBreak {} {
+    return -code break
+}
+.CE
+
+With the \fB-level 0\fR option, \fBreturn\fR itself can serve
+as a replacement for \fBbreak\fR.
+
+.CS
+interp alias {} Break {} return -level 0 -code break
+.CE
+
+An example of using \fBcatch\fR and \fBreturn -options\fR to
+re-raise a caught error:
+
+.CS
+proc doSomething {} {
+    set resource [allocate]
+    catch {
+        # Long script of operations
+        # that might raise an error
+    } result options
+    deallocate $resource
+    return -options $options $result
+}
+.CE
+
+Finally an example of advanced use of the \fBreturn\fR options
+to create a procedure replacement for \fBreturn\fR itself:
+
+.CS
+proc myReturn {args} {
+    set result ""
+    if {[llength $args] % 2} {
+        set result [lindex $args end]
+        set args [lrange $args 0 end-1]
+    }
+    set options [dict create -level 1]
+    eval [list dict replace $options] $args
+    dict incr options -level
+    return -options $options $result
+}
+.CE
+
 .SH "SEE ALSO"
 break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)