Name

ecl_nth_value, ecl_nvalues — Accessing output values

Functions and macros

cl_object ecl_nvalues( cl_env_ptr env);

cl_object ecl_nth_value( cl_env_ptr env, int n);

Description

Common Lisp functions may return zero, one or more values. In ECL, the first two cases do not require any special manipulation, as the C function returns either NIL or the first (zeroth) value directly. However, if one wishes to access additional values from a function, one needs to use these two macros or functions

  • ecl_nvalues(env) returns the number of values that the function actually outputs. The single argument is the lisp environment. This value is larger or equal to 0 and smaller than ECL_MULTIPLE_VALUES_LIMIT.

  • Once we know the number of return values, they can be directly accessed using the function ecl_nth_value(env,n), where n is a number larger than or equal to 1, and smaller than ECL_MULTIPLE_VALUES_LIMIT, which must correspond to a valid output value. No checking is done.

Note that in both cases these macros and functions have to be used right after the Lisp function was called. This is so because other Lisp functions might destroy the content of the return stack.

Example

A C/C++ exceprt

cl_env_ptr env = ecl_process_env();
cl_object a = ecl_make_fixnum(13);
cl_object b = ecl_make_fixnum(6);
cl_object modulus = cl_floor(2, a, b);
cl_object remainder = ecl_nth_value(env, 1);

The somewhat equivalent Common Lisp code

(multiple-value-bind (modulus equivalent)
    (floor 13 6))