[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.
Return the name of the subr x. The result is undefined if x is not a subr.
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
+ 1arguments if
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_UNDEFINEDfor 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
applythe list is directly from the
applyargument, 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_gsubrdo not fit one of the predefined patterns, then
scm_c_define_gsubrwill return a compiled closure object instead of a subr object.