Chapter 12

The Built-In Functions


Reflective Operations on Functions

The following functions provide information on and manipulate other functions.

generic-function-methods [Function]


Returns the methods of a generic function.

Signature:

generic-function-methods generic-function sequence

Arguments:
generic-function

An instance of <generic-function>.

Values:
sequence

An instance of <sequence>. Each element in the sequence is an instance of <method>.

Description:

Returns a sequence of all of the methods in generic-function. The order of the methods in the sequence is not significant. The sequence returned should never be destructively modified. Doing so may cause unpredictable behavior.

If generic-function is sealed, an implementation may choose not to return a sequence of methods, but instead signal an error of type <sealed-object-error>.

add-method [Function]


Adds a method to a generic function.

Signature:

add-method generic-function method new-method old-method

Arguments:
generic-function

An instance of <generic-function>.

method

An instance of <method>.

Values:
new-method

An instance of <method>.

old-method

#f or an instance of <method>.

Description:

Adds method to generic-function, thereby modifying the generic-function.

Programs do not commonly call add-method directly. It is called by define method.

If you add a method to a generic function, and the generic function already has a method with the exact same specializers, then the old method is replaced with the new one.

A single method may be added to any number of generic functions.

add-method returns two values. The first is the new method. The second will be either the method in generic-function that is being replaced by method, or it will be #f if no method is being replaced.

add-method may signal an error of type <sealed-object-error> if adding the method or replacing an existing method would cause a sealing violation.

If generic-function is sealed, or if method is in a sealed domain of generic-function, then an error of type <sealed-object-error> is signaled.

generic-function-mandatory-keywords [Function]


Returns the mandatory keywords of a generic function, if any.

Signature:

generic-function-mandatory-keywords generic-function keywords

Arguments:
generic-function

An instance of <generic-function>.

Values:
keywords

The object #f or an instance of <collection>.

Description:

If generic-function accepts keyword arguments, generic-function-mandatory-keywords returns a collection of the mandatory keywords for generic-function. This collection will be empty if the generic function accepts keywords but does not have any mandatory keywords. generic-function-mandatory-keywords returns #f if generic-function does not accept keyword arguments.

The collection returned should never be destructively modified. Doing so may cause unpredictable behavior.

function-specializers [Function]


Returns the specializers of a function.

Signature:

function-specializers function sequence

Arguments:
function

An instance of <function>.

Values:
sequence

An instance of <sequence>. The elements of the sequence are instances of <type>.

Description:

Returns a sequence of the specializers for function. The length of the sequence will equal the number of required arguments of function. The first element of the sequence will be the specializer of the first argument of function, the second will be the specializer of the second argument, and so on.

The sequence returned should never be destructively modified. Doing so may cause unpredictable behavior.

function-arguments [Function]


Returns information about the arguments accepted by a function.

Signature:

function-arguments function required-number rest-boolean kwd-sequence

Arguments:
function

An instance of <function>.

Values:
required-number

An instance of <integer>.

rest-boolean

An instance of <boolean>.

kwd-sequence

Either #f or the symbol #"all" or an instance of <collection> whose elements are instances of <keyword>.

Description:

Returns three values:

  • required-number is the number of required arguments accepted by the function.
  • rest-boolean indicates whether the function accepts a variable number of arguments.
  • kwd-sequence indicates whether the function accepts keyword arguments. If the value is #f then the function does not accept keyword arguments. Otherwise, the function does accept keyword arguments, and the value is either a collection of the keywords that are permissible for any call to the function, or the symbol #"all" if all keywords are permitted by the function.

Note that particular calls to a generic function may accept additional keywords not included in the third value returned by function-arguments, by virtue of their being recognized by applicable methods.

function-return-values [Function]


Returns information about the values returned by a function.

Signature:

function-return-values function return-value-types rest-return-value

Arguments:
function

An instance of <function>.

Values:
return-value-types

An instance of <sequence>. The elements of the sequence are instances of <type>.

rest-return-value

An instance of <type> or #f.

Description:

Returns two values:

  • return-value-types is a sequence of the types of values returned by the function. The length of the sequence equals the number of required return values of the function. The first element of the sequence is the type of the first return value, the second is the type of the second return value, etc. This sequence returned should never be destructively modified. Doing so may cause unpredictable behavior.
  • rest-return-value indicates whether the function returns a variable number of values and, if so, the type of values that may be returned after the required return values. If the function does not return a variable number of values, #f is returned; otherwise a type is returned.

applicable-method? [Function]


Tests if a function is applicable to sample arguments.

Signature:

applicable-method? function #rest sample-args boolean

Arguments:
function

An instance of <function>.

sample-args

Instances of <object>.

Values:
boolean

An instance of <boolean>.

Description:

Returns true if function is a method that would be applicable to sample-args or if it is a generic function that contains a method that would be applicable to sample-args.

Note that if function is a generic function, then calling it with the sample-args may still signal an error, even if applicable-method? returns true. This is because the generic function may contain methods that are ambiguous relative to the sample-args. See "Method Specificity" on page 96 for a complete description of ambiguous methods.

If function is a sealed generic function, applicable-method? may signal an error of type <sealed-object-error>.

sorted-applicable-methods [Function]


Returns all the methods in a generic function that are applicable to sample arguments, sorted in order of specificity.

Signature:

sorted-applicable-methods generic-function #rest sample-args
sorted-methods unsorted-methods

Arguments:
generic-function

An instance of <generic-function>.

sample-args

Instances of <object>.

Values:
sorted-methods

An instance of <sequence>. Elements of the sequence are instances of <method>.

unsorted-methods

An instance of <sequence>. Elements of the collection are instances of <method>.

Description:

Returns two sequences that, taken together, contain the methods in generic-function that are applicable to the sample-args. sorted-methods contains methods that are more specific than every method that follows them. unsorted-methods begins at the first point of ambiguity; it contains the methods that cannot be sorted.

The sequences returned should never be destructively modified. Doing so may cause unpredictable behavior.

If generic-function is sealed, an implementation may choose not to return two sequences of methods, but instead signal an error of type <sealed-object-error>.

find-method [Function]


Returns the method in a generic function that has particular specializers.

Signature:

find-method generic-function specializers found-method

Arguments:
generic-function

An instance of <generic-function>.

specializers

An instance of <sequence>. Elements of the sequence are instances of <type>.

Values:
found-method

#f or an instance of <method>.

Description:

Returns the method in generic-function that has the specializers in specializers as its specializers. The specializers must match exactly for a method to be returned.

If generic-function is sealed, an implementation may choose to signal an error of type <sealed-object-error> rather than return a value.

remove-method [Function]


Removes a method from a generic function.

Signature:

remove-method generic-function method method

Arguments:
generic-function

An instance of <generic-function>.

method

An instance of <method>.

Values:
method

An instance of <method>.

Description:

Removes method from generic-function and returns method.

This operation modifies the generic-function.

If generic-function is sealed, or if method is in a sealed domain of generic-function, then an error of type <sealed-object-error> is signaled.