return-from

return-from Special Operator

Syntax:

return-from name [result] →

Arguments and Values:

name—a block tag; not evaluated.

result—a form; evaluated. The default is nil.

Description:

Returns control and multiple values₂ from a lexically enclosing block.

A block form named name must lexically enclose the occurrence of return-from; any values yielded by the evaluation of result are immediately returned from the innermost such lexically enclosing block.

The transfer of control initiated by return-from is performed as described in Section 5.2 (Transfer of Control to an Exit Point).

Examples:

(block alpha (return-from alpha) 1) → NIL 
(block alpha (return-from alpha 1) 2) → 1 
(block alpha (return-from alpha (values 1 2)) 3) → 1, 2 
(let ((a 0)) 
  (dotimes (i 10) (incf a) (when (oddp i) (return))) 
  a) → 2 
Data and Control 

**return-from** 
(defun temp (x) 
  (if x (return-from temp ’dummy)) 
  \44) → TEMP 
(temp nil) → 44 
(temp t) → DUMMY 
(block out 
  (flet ((exit (n) (return-from out n))) 
    (block out (exit 1))) 
  \2) → 1 
(block nil 
  (unwind-protect (return-from nil 1) 
    (return-from nil 2))) 
→ 2 
(dolist (flag ’(nil t)) 
  (block nil 
    (let ((x 5)) 
      (declare (special x)) 
      (unwind-protect (return-from nil) 
	(print x)))) 
  (print ’here)) 
▷ 5 
▷ HERE 
▷ 5 
▷ HERE 
→ NIL 
(dolist (flag ’(nil t)) 
  (block nil 
    (let ((x 5)) 
      (declare (special x)) 
      (unwind-protect 
	   (if flag (return-from nil)) 
	(print x)))) 
  (print ’here)) 
▷ 5 
▷ HERE 
▷ 5 
▷ HERE 
→ NIL 
The following has undefined consequences because the **block** *form* exits normally before the **return-from** *form* is attempted. 
(funcall (block nil #’(lambda () (return-from nil)))) is an error. 

See Also:

block, return, Section 3.1 (Evaluation)

Expanded Reference: return-from

Basic usage

return-from immediately exits the named block and returns the given value. If no value is specified, NIL is returned.

(block alpha
  (return-from alpha 42)
  (print "not reached"))
=> 42

(block alpha
  (return-from alpha)
  (print "not reached"))
=> NIL

Returning from a named function

Functions defined with defun establish an implicit block with the function's name, which return-from can target.

(defun first-negative (list)
  (dolist (x list)
    (when (minusp x)
      (return-from first-negative x)))
  nil)

(first-negative '(3 7 -2 5))
=> -2
(first-negative '(3 7 5))
=> NIL

Returning multiple values

return-from can transfer multiple values from a block.

(block calc
  (return-from calc (values 1 2 3)))
=> 1
=> 2
=> 3

Exiting through nested blocks

return-from targets the innermost lexically enclosing block with the matching name.

(block outer
  (+ 1 (block inner
          (return-from outer 10)
          20))
  30)
=> 10

Using return-from inside a flet

Since return-from uses lexical scope, a local function defined by flet can exit its enclosing block.

(block exit-point
  (flet ((maybe-exit (x)
           (when (> x 10)
             (return-from exit-point :too-big))))
    (maybe-exit 5)
    (maybe-exit 15)
    :done))
=> :TOO-BIG

Interaction with unwind-protect

When return-from causes a non-local exit, the cleanup forms of any intervening unwind-protect are executed.

(block outer
  (unwind-protect
      (return-from outer :exiting)
    (format t "cleanup runs~%")))
.. cleanup runs
..
=> :EXITING