Next: , Previous: Closures, Up: Non-immediate Datatypes

A.2.5.5 Subrs

[FIXME: this needs to be further subbed, but texinfo has no subsubsub]

A subr is a pointer to a C function, packaged up as a Scheme object to make it callable by Scheme code. In addition to the function pointer, the subr also contains a pointer to the name of the function, and information about the number of arguments accepted by the C function, for the sake of error checking.

There is no single type predicate macro that recognizes subrs, as distinct from other kinds of procedures. The closest thing is scm_procedure_p; see Procedures.

— Macro: char * SCM_SNAME (x)

Return the name of the subr x. The result is undefined if x is not a subr.

— Function: SCM scm_c_define_gsubr (char *name, int req, int opt, int rest, SCM (*function)())

Create a new subr object named name, based on the C function function, make it visible to Scheme the value of as a global variable named name, and return the subr object.

The subr object accepts req required arguments, opt optional arguments, and a rest argument iff rest is non-zero. The C function function should accept req + opt arguments, or req + opt + 1 arguments if rest is non-zero.

When a subr object is applied, it must be applied to at least req arguments, or else Guile signals an error. function receives the subr's first req arguments as its first req arguments. If there are fewer than opt arguments remaining, then function receives the value SCM_UNDEFINED for any missing optional arguments.

If rst is non-zero, then any arguments after the first req + opt are packaged up as a list and passed as function's last argument. function must not modify that list. (Because when subr is called through apply the list is directly from the apply argument, which the caller will expect to be unchanged.)

Note that subrs can actually only accept a predefined set of combinations of required, optional, and rest arguments. For example, a subr can take one required argument, or one required and one optional argument, but a subr can't take one required and two optional arguments. It's bizarre, but that's the way the interpreter was written. If the arguments to scm_c_define_gsubr do not fit one of the predefined patterns, then scm_c_define_gsubr will return a compiled closure object instead of a subr object.