manpagez: man pages & more
info guile
Home | html | info | man
[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.13.7 Returning and Accepting Multiple Values

Scheme allows a procedure to return more than one value to its caller. This is quite different to other languages which only allow single-value returns. Returning multiple values is different from returning a list (or pair or vector) of values to the caller, because conceptually not one compound object is returned, but several distinct values.

The primitive procedures for handling multiple values are values and call-with-values. values is used for returning multiple values from a procedure. This is done by placing a call to values with zero or more arguments in tail position in a procedure body. call-with-values combines a procedure returning multiple values with a procedure which accepts these values as parameters.

Scheme Procedure: values arg1 … argN
C Function: scm_values (args)

Delivers all of its arguments to its continuation. Except for continuations created by the call-with-values procedure, all continuations take exactly one value. The effect of passing no value or more than one value to continuations that were not created by call-with-values is unspecified.

For scm_values, args is a list of arguments and the return is a multiple-values object which the caller can return. In the current implementation that object shares structure with args, so args should not be modified subsequently.

C Function: scm_c_value_ref (values, idx)

Returns the value at the position specified by idx in values. Note that values will ordinarily be a multiple-values object, but it need not be. Any other object represents a single value (itself), and is handled appropriately.

Scheme Procedure: call-with-values producer consumer

Calls its producer argument with no values and a continuation that, when passed some values, calls the consumer procedure with those values as arguments. The continuation for the call to consumer is the continuation of the call to call-with-values.

(call-with-values (lambda () (values 4 5))
                  (lambda (a b) b))
⇒ 5

(call-with-values * -)
⇒ -1

In addition to the fundamental procedures described above, Guile has a module which exports a syntax called receive, which is much more convenient. This is in the (ice-9 receive) and is the same as specified by SRFI-8 (see section SRFI-8 - receive).

(use-modules (ice-9 receive))
library syntax: receive formals expr body …

Evaluate the expression expr, and bind the result values (zero or more) to the formal arguments in formals. formals is a list of symbols, like the argument list in a lambda (see section Lambda: Basic Procedure Creation). After binding the variables, the expressions in body … are evaluated in order, the return value is the result from the last expression.

For example getting results from partition in SRFI-1 (see section SRFI-1 - List library),

(receive (odds evens)
    (partition odd? '(7 4 2 8 3))
  (display odds)
  (display " and ")
  (display evens))
-| (7 3) and (4 2 8)

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on February 3, 2012 using texi2html 5.0.