Skip to main content

return

return Macro

Syntax:

return [result] →

Arguments and Values:

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

Description:

Returns, as if by return-from, from the block named nil.

Examples:

(block nil (return) 1) → NIL 
(block nil (return 1) 2) → 1 
(block nil (return (values 1 2)) 3) → 1, 2 
(block nil (block alpha (return 1) 2)) → 1 
(block alpha (block nil (return 1)) 2) → 2 
(block nil (block nil (return 1) 2)) → 1

See Also:

block, return-from, Section 3.1 (Evaluation)

Notes:

(return) ≡ (return-from nil)

(return form) ≡ (return-from nil form)

The implicit blocks established by macros such as do are often named nil, so that return can be used to exit from such forms.

Expanded Reference: return​

Basic usage​

return is shorthand for (return-from nil ...). It exits the innermost block named NIL.

(block nil
  (return 42)
  (print "not reached"))
=> 42

Returning from iteration macros​

Most iteration macros such as dolist, dotimes, do, and loop establish an implicit block named NIL, so return can be used to exit them early.

(dolist (x '(1 2 3 4 5))
  (when (> x 3)
    (return x)))
=> 4
(dotimes (i 100)
  (when (= (* i i) 49)
    (return i)))
=> 7

Default return value is NIL​

When called with no argument, return returns NIL.

(block nil
  (return)
  99)
=> NIL

Returning multiple values​

return can pass multiple values from the block.

(block nil
  (return (values :a :b :c)))
=> :A
=> :B
=> :C

return targets the innermost NIL block​

When blocks named NIL are nested, return exits only the innermost one.

(block nil
  (block nil
    (return 1))
  2)
=> 2

Using return inside a do loop​

A practical example showing early termination of a do loop to find the first triangular number above 50.

(do ((i 0 (1+ i))
     (sum 0 (+ sum i)))
    ((> i 100) sum)
  (when (> sum 50)
    (return (values i sum))))
=> 11
=> 55