or - short-circuiting conditional, return the first true value

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

SYNOPSIS

(or test ...)

DESCRIPTION

The test expressions are evaluated from left to right until one returns a true value or the last test is reached. In the former case, the or expression returns the value without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values are returned.

If there are no tests, #f is returned.

IMPLEMENTATION NOTES

Chez Scheme, Loko Scheme
The source-level optimizer can rewrite code that uses multiple values in one of the test expressions in such a way that the values are no longer in a single-value context. This can mean that code which would otherwise raise an exception will run without error, but with possibly unexpected results. This is not a bug and is permitted by R6RS.
Vicare Scheme
The test expressions are statically checked to see that they return a single value.

RETURN VALUES

Returns the value of the first true expression. In Scheme everything is true except for the false value (#f or #false in R7RS).

The last test expression is in tail context if the or expression itself is.

EXAMPLES

(or (= 2 2) (> 2 1))  => #t
(or (= 2 2) (< 2 1))  => #t
(or #f #f #f)         => #f
(or '(b c) (/ 3 0))   => (b c)
(or)                  => #f

APPLICATION USAGE

The or syntax is very common in almost all programming languages. It is sometimes called or and other times && or something else. It is used when several expressions should be tested but evaluation should not continue past the first true value.

When expressions are more complicated it is better to use cond(3scm).

COMPATIBILITY

The or syntax is widely compatible across Lisp systems.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
Zero or more than one value was returned by a non-tail test expression. Implementations may also handle this in another way, as long as the safety guarantees of R6RS § 5.6 are upheld.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

SEE ALSO

and(3scm), cond(3scm), if(3scm)

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

Short-circuiting evaluation was invented in the 1950s by John McCarthy, the creator of Lisp.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

Markup created by unroff 1.0sc,    March 04, 2023.