chap-5.texi

@node Data and Control Flow
@chapter Data and Control Flow
@menu
* Generalized Reference::
* Transfer of Control to an Exit Point::
* Data and Control Flow Dictionary::
@end menu

@node Generalized Reference
@section Generalized Reference

@menu
* Overview of Places and Generalized Reference::
* Kinds of Places::
* Treatment of Other Macros Based on SETF::
@end menu
@node Overview of Places and Generalized Reference
@subsection Overview of Places and Generalized Reference

A @newterm{generalized reference} is the use of a @term{form},
sometimes called a @newterm{place},
as if it were a @term{variable} that could be read and written.
The @term{value} of a @term{place} is
the @term{object} to which the @term{place} @term{form} evaluates.
The @term{value} of a @term{place} can be changed by using @symbolref{setf, SYM}.
The concept of binding a @term{place} is not defined in @clisp{},
but an @term{implementation} is permitted to extend the language by defining this concept.

@Thenextfigure{}@spc{}contains examples of the use of @symbolref{setf, SYM}.
Note that the values returned by evaluating the @term{forms} in column two
are not necessarily the same as those obtained by evaluating the
@term{forms} in column three.
In general, the exact @term{macro expansion} of a @symbolref{setf, SYM} @term{form} is not guaranteed
and can even be @term{implementation-dependent};
all that is guaranteed is
that the expansion is an update form that works
for that particular @term{implementation},
that the left-to-right evaluation of @term{subforms} is preserved,
and
that the ultimate result of evaluating @symbolref{setf, SYM} is the value
or values being stored.


@float Figure,fig5.1
@cartouche
@multitable{@f{(symbol-value x)}}{@f{(rplaca x datum)}}{@f{(setf (symbol-value x) datum)}}
@headitem Access function @tab Update Function @tab Update using @symbolref{setf, SYM}
@item @f{x} @tab @f{(setq x datum)} @tab @f{(setf x datum)}
@item @f{(car x)} @tab @f{(rplaca x datum)} @tab @f{(setf (car x) datum)}
@item @f{(symbol-value x)} @tab @f{(set x datum)} @tab @f{(setf (symbol-value x) datum)}
@end multitable
@end cartouche
@caption{Examples of setf}
@end float


@Thenextfigure{}@spc{}shows @term{operators} relating to
@term{places} and @term{generalized reference}.



@float Figure,fig5.2
@cartouche
@multitable{define-setf-expander}{get-setf-expansion}{rotatef}

@item assert @tab defsetf @tab push
@item ccase @tab get-setf-expansion @tab remf
@item ctypecase @tab getf @tab rotatef
@item decf @tab incf @tab setf
@item define-modify-macro @tab pop @tab shiftf
@item define-setf-expander @tab psetf @tab
@end multitable
@end cartouche
@caption{Operators relating to places and generalized reference.}
@end float



Some of the @term{operators} above manipulate @term{places}
and some manipulate @term{setf expanders}.
A @term{setf expansion} can be derived from any @term{place}.
New @term{setf expanders} can be defined by using @symbolref{defsetf, SYM}
and @symbolref{define-setf-expander, SYM}.

@node Evaluation of Subforms to Places
@subsubsection Evaluation of Subforms to Places

The following rules apply to the @term{evaluation} of @term{subforms} in a
@term{place}:


@enumerate 1
@item
The evaluation ordering of @term{subforms} within a @term{place}
is determined by the order specified by the second value returned by
@symbolref{get-setf-expansion, SYM}.
For all @term{places} defined by this specification
(@eg{} @symbolref{getf, SYM}, @symbolref{ldb, SYM}, @mat{@ldots{}}),
this order of evaluation is left-to-right.
@cindex order of evaluation
@cindex evaluation order
When a @term{place} is derived from a macro expansion,
this rule is applied after the macro is expanded to find the appropriate @term{place}.

@term{Places} defined by using @symbolref{defmacro, SYM} or
@symbolref{define-setf-expander, SYM}
use the evaluation order defined by those definitions.
For example, consider the following:

@lisp
 (defmacro wrong-order (x y) `(getf ,y ,x))
@end lisp


This following @term{form} evaluates @f{place2} first and
then @f{place1} because that is the order they are evaluated in
the macro expansion:

@lisp
 (push value (wrong-order place1 place2))
@end lisp


@item
For the @term{macros} that manipulate @term{places}
(@symbolref{push, SYM},
@symbolref{pushnew, SYM},
@symbolref{remf, SYM},
@symbolref{incf, SYM},
@symbolref{decf, SYM},
@symbolref{shiftf, SYM},
@symbolref{rotatef, SYM},
@symbolref{psetf, SYM},
@symbolref{setf, SYM},
@symbolref{pop, SYM}, and those defined by @symbolref{define-modify-macro, SYM})
the @term{subforms} of the macro call are evaluated exactly once
in left-to-right order, with the @term{subforms} of the @term{places}
evaluated in the order specified in (1).

@symbolref{push, SYM}, @symbolref{pushnew, SYM}, @symbolref{remf, SYM},
@symbolref{incf, SYM}, @symbolref{decf, SYM}, @symbolref{shiftf, SYM}, @symbolref{rotatef, SYM},
@symbolref{psetf, SYM}, @symbolref{pop, SYM} evaluate all @term{subforms} before modifying
any of the @term{place} locations.
@symbolref{setf, SYM} (in the case when @symbolref{setf, SYM} has more than two arguments)
performs its operation on each pair in sequence. For example, in

@lisp
 (setf place1 value1 place2 value2 ...)
@end lisp

the @term{subforms} of @f{place1} and @f{value1} are evaluated, the location
specified by
@f{place1} is modified to contain the value returned by
@f{value1}, and
then the rest of the @symbolref{setf, SYM} form is processed in a like manner.

@item
For @symbolref{check-type, SYM}, @symbolref{ctypecase, SYM}, and @symbolref{ccase, SYM},
@term{subforms} of the @term{place} are evaluated once as in (1),
but might be evaluated again if the
type check fails in the case of @symbolref{check-type, SYM}
or none of the cases hold in
@symbolref{ctypecase, SYM} and @symbolref{ccase, SYM}.

@item
For @symbolref{assert, SYM}, the order of evaluation of the generalized
references is not specified.
@cindex order of evaluation
@cindex evaluation order
@end enumerate

Rules 2, 3 and 4 cover all @term{standardized} @term{macros} that manipulate @term{places}.

@node Examples of Evaluation of Subforms to Places
@subsubsection Examples of Evaluation of Subforms to Places


@lisp
 (let ((ref2 (list '())))
   (push (progn (princ "1") 'ref-1)
         (car (progn (princ "2") ref2))))
@OUT{} 12
@EV{} (REF1)

 (let (x)
    (push (setq x (list 'a))
          (car (setq x (list 'b))))
     x)
@EV{} (((A) . B))
@end lisp


@symbolref{push, SYM} first evaluates @tt{(setq x (list 'a)) @EV{}@spc{}(a)},
then evaluates @tt{(setq x (list 'b)) @EV{}@spc{}(b)},
then modifies the @term{car} of this latest value to be @tt{((a) . b)}.



@node Setf Expansions
@subsubsection Setf Expansions

Sometimes it is possible to avoid evaluating @term{subforms} of a
@term{place} multiple times or in the wrong order.  A
@term{setf expansion}
for a given access form can be expressed as an ordered collection of five @term{objects}:


@table @asis
@item @id{@b{List of temporary variables}}


a list of symbols naming temporary variables to be bound
sequentially, as if by @symbolref{let*, SYM}, to @term{values}
resulting from value forms.

@item @id{@b{List of value forms}}


a list of forms (typically, @term{subforms} of the
@term{place}) which when evaluated
yield the values to which the corresponding temporary
variables should be bound.

@item @id{@b{List of store variables}}


a list of symbols naming temporary store variables which are
to hold the new values that will be assigned to the
@term{place}.

@item @id{@b{Storing form}}


a form which can reference both the temporary and the store variables,
and which changes the @term{value} of the @term{place}
and guarantees to return as its values the values of the store variables,
which are the correct values for @symbolref{setf, SYM} to return.

@item @id{@b{Accessing form}}


a @term{form} which can reference the temporary variables,
and which returns the @term{value} of the @term{place}.
@end table


The value returned by the accessing form is
affected by execution of the storing form, but either of these
forms might be evaluated any number of times.

It is possible
to do more than one @symbolref{setf, SYM} in parallel via
@symbolref{psetf, SYM}, @symbolref{shiftf, SYM}, and @symbolref{rotatef, SYM}.
Because of this, the
@term{setf expander}
must produce new temporary
and store variable names every time.  For examples of how to do this,
see @symbolref{gensym, SYM}.

For each @term{standardized} accessor function @param{F},
unless it is explicitly documented otherwise,
it is @term{implementation-dependent} whether the ability to
use an @param{F} @term{form} as a @symbolref{setf, SYM} @term{place}
is implemented by a @term{setf expander} or a @term{setf function}.
Also, it follows from this that it is @term{implementation-dependent}
whether the name @f{(setf @param{F})} is @term{fbound}.

@node Examples of Setf Expansions
@subsubsection Examples of Setf Expansions


Examples of the contents of the constituents of @term{setf expansions}
follow.

For a variable @param{x}:


@float Figure,fig5.3
@cartouche
@multitable{@f{(setq @param{x} g0001)}}{;list of temporary variables}

@item @f{()} @tab ;list of temporary variables
@item @f{()} @tab ;list of value forms
@item @f{(g0001)} @tab ;list of store variables
@item @f{(setq @param{x} g0001)} @tab ;storing form
@item @param{x} @tab ;accessing form
@end multitable
@end cartouche
@caption{Sample Setf Expansion of a Variable}
@end float


For @tt{(car @param{exp})}:


@float Figure,fig5.4
@cartouche
@multitable{@f{(progn (rplaca g0002 g0003) g0003)}}{;list of temporary variables}

@item @f{(g0002)} @tab ;list of temporary variables
@item @f{(@param{exp})} @tab ;list of value forms
@item @f{(g0003)} @tab ;list of store variables
@item @f{(progn (rplaca g0002 g0003) g0003)} @tab ;storing form
@item @f{(car g0002)} @tab ;accessing form
@end multitable
@end cartouche
@caption{Sample Setf Expansion of a CAR Form}
@end float


For @f{(subseq @param{seq} @param{s} @param{e})}:


@float Figure,fig5.5
@cartouche
@multitable{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}{xxxxxxxxxxxxxxxxxxxxxxxxxxxx}

@item @f{(g0004 g0005 g0006)} @tab ;list of temporary variables
@item @f{(@param{seq} @param{s} @param{e})} @tab ;list of value forms
@item @f{(g0007)} @tab ;list of store variables
@item @f{(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007)} @span{} @tab
@item  @tab ;storing form
@item @f{(subseq g0004 g0005 g0006)} @tab ; accessing form
@end multitable
@end cartouche
@caption{Sample Setf Expansion of a SUBSEQ Form}
@end float


In some cases, if a @term{subform} of a @term{place} is itself
a @term{place}, it is necessary to expand the @term{subform}
in order to compute some of the values in the expansion of the outer
@term{place}.  For @f{(ldb @param{bs} (car @param{exp}))}:


@float Figure,fig5.6
@cartouche
@multitable{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}{xxxxxxxxxxxxxxxxxxxxxxxxxxxx}

@item @f{(g0001 g0002)} @tab ;list of temporary variables
@item @f{(@param{bs} @param{exp})} @tab ;list of value forms
@item @f{(g0003)} @tab ;list of store variables
@item @f{(progn (rplaca g0002 (dpb g0003 g0001 (car g0002))) g0003)} @span{} @tab
@item  @tab ;storing form
@item @f{(ldb g0001 (car g0002))} @tab ; accessing form
@end multitable
@end cartouche
@caption{Sample Setf Expansion of a LDB Form}
@end float






@node Kinds of Places
@subsection Kinds of Places

Several kinds of @term{places} are defined by @clisp{};
this section enumerates them.
This set can be extended by @term{implementations} and by @term{programmer code}.

@node Variable Names as Places
@subsubsection Variable Names as Places

The name of a @term{lexical variable} or @term{dynamic variable}
can be used as a @term{place}.


@node Function Call Forms as Places
@subsubsection Function Call Forms as Places

A @term{function form} can be used as a @term{place} if it falls
into one of the following categories:


@itemize @bullet{}

@item
A function call form whose first element is the name of
any one of the functions in @thenextfigure{}.


@editornote{KMP: Note that what are in some places still called `condition accessors'
are deliberately omitted from this table, and are not labeled as
accessors in their entries.  I have not yet had time to do a full
search for these items and eliminate stray references to them as `accessors',
which they are not, but I will do that at some point.}


@float Figure,fig5.7
@cartouche
@multitable{caaaar}{compiler-macro-function}{logical-pathname-translations}

@item aref @tab cdadr @tab get
@item bit @tab cdar @tab gethash
@item caaaar @tab cddaar @tab logical-pathname-translations
@item caaadr @tab cddadr @tab macro-function
@item caaar @tab cddar @tab ninth
@item caadar @tab cdddar @tab nth
@item caaddr @tab cddddr @tab readtable-case
@item caadr @tab cdddr @tab rest
@item caar @tab cddr @tab row-major-aref
@item cadaar @tab cdr @tab sbit
@item cadadr @tab char @tab schar
@item cadar @tab class-name @tab second
@item caddar @tab compiler-macro-function @tab seventh
@item cadddr @tab documentation @tab sixth
@item caddr @tab eighth @tab slot-value
@item cadr @tab elt @tab subseq
@item car @tab fdefinition @tab svref
@item cdaaar @tab fifth @tab symbol-function
@item cdaadr @tab fill-pointer @tab symbol-plist
@item cdaar @tab find-class @tab symbol-value
@item cdadar @tab first @tab tenth
@item cdaddr @tab fourth @tab third
@end multitable
@end cartouche
@caption{Functions that setf can be used with---1}
@end float


In the case of @symbolref{subseq, SYM}, the replacement value must be a @term{sequence}
whose elements might be contained by the sequence argument to @symbolref{subseq, SYM},
but does not have to be a @term{sequence} of the same @term{type}
as the @term{sequence} of which the subsequence is specified.
If the length of the replacement value does not equal the length of
the subsequence to be replaced, then the shorter length determines
the number of elements to be stored, as for @symbolref{replace, SYM}.


@item
A function call form whose first element is the name of
a selector function constructed by @symbolref{defstruct, SYM}.
The function name must refer to the global function definition,
rather than a locally defined @term{function}.

@item
A function call form whose first element is the name of
any one of the functions in @thenextfigure{},
provided that the supplied argument
to that function is in turn a @term{place} form;
in this case the new @term{place} has stored back into it the
result of applying the supplied ``update'' function.


@float Figure,fig5.8
@cartouche
@multitable{@symbolref{mask-field, SYM}}{Argument that is a @param{place}}{@term{implementation-dependent}}
@headitem Function name @tab Argument that is a @param{place} @tab Update function used
@item @symbolref{ldb, SYM} @tab second @tab @symbolref{dpb, SYM}
@item @symbolref{mask-field, SYM} @tab second @tab @symbolref{deposit-field, SYM}
@item @symbolref{getf, SYM} @tab first @tab @term{implementation-dependent}
@end multitable
@end cartouche
@caption{Functions that setf can be used with---2}
@end float

During the @symbolref{setf, SYM} expansion of these @term{forms}, it is necessary to call
@symbolref{get-setf-expansion, SYM}
in order to figure out how the inner, nested generalized variable must be treated.

The information from
@symbolref{get-setf-expansion, SYM}
is used as follows.

@table @asis
@item @id{@symbolref{ldb, SYM}}


In a form such as:

@tt{(setf (ldb @param{byte-spec} @param{place-form}) @param{value-form})}

the place referred to by the @param{place-form} must always be both @term{read}
and @i{written};  note that the update is to the generalized variable
specified by @param{place-form}, not to any object @oftype{integer}.

Thus this @symbolref{setf, SYM} should generate code to do the following:


@enumerate 1
@item Evaluate @param{byte-spec} (and bind it into a temporary variable).
@item Bind the temporary variables for @param{place-form}.
@item Evaluate @param{value-form}  (and bind
its value or values into the store variable).
@item Do the @term{read} from @param{place-form}.
@item Do the @term{write} into @param{place-form} with
the given bits of the @term{integer}
fetched in step 4 replaced with the value from step 3.
@end enumerate

If the evaluation of @param{value-form}
in step 3 alters what is found in @param{place-form},
such as setting different bits of @term{integer},
then the change of the bits denoted by
@param{byte-spec} is to that
altered @term{integer},
because step 4 is done after the @param{value-form}
evaluation.  Nevertheless, the
evaluations required for @term{binding}
the temporary variables are done in steps 1 and
2, and thus the expected left-to-right evaluation order is seen.
For example:

@lisp
 (setq integer #x69) @EV{} #x69
 (rotatef (ldb (byte 4 4) integer)
          (ldb (byte 4 0) integer))
 integer @EV{} #x96
;;; This example is trying to swap two independent bit fields
;;; in an integer.  Note that the generalized variable of
;;; interest here is just the (possibly local) program variable
;;; integer.
@end lisp


@item @id{@symbolref{mask-field, SYM}}


This case is the same as @symbolref{ldb, SYM} in all essential aspects.

@item @id{@symbolref{getf, SYM}}


In a form such as:

@f{(setf (getf @param{place-form} @param{ind-form}) @param{value-form})}

the place referred to by @param{place-form} must always be both @term{read}
and @i{written};  note that the update is to the generalized variable
specified by @param{place-form}, not necessarily to the particular
@term{list}
that is the property list in question.

Thus this @symbolref{setf, SYM} should generate code to do the following:

@enumerate 1
@item
Bind the temporary variables for @param{place-form}.
@item
Evaluate @param{ind-form} (and bind it into a temporary variable).
@item
Evaluate @param{value-form} (and bind
its value or values into the store variable).
@item
Do the @term{read} from @param{place-form}.
@item
Do the @term{write} into @param{place-form} with a possibly-new property list
obtained by combining the values from steps 2, 3, and 4.
(Note that the phrase ``possibly-new property list'' can mean that
the former property list is somehow destructively re-used, or it can
mean partial or full copying of it.
Since either copying or destructive re-use can occur,
the treatment of the resultant value for the
possibly-new property list must proceed as if it were a different copy
needing to be stored back into the generalized variable.)
@end enumerate

If the evaluation of @param{value-form}
in step 3 alters what is found in
@param{place-form}, such as setting a different named property in the list,
then the change of the property denoted by @param{ind-form}
is to that
altered list, because step 4 is done after the
@param{value-form}
evaluation.  Nevertheless, the
evaluations required for @term{binding}
the temporary variables  are done in steps 1 and
2,  and thus the expected left-to-right evaluation order is seen.

For example:

@lisp
 (setq s (setq r (list (list 'a 1 'b 2 'c 3)))) @EV{} ((a 1 b 2 c 3))
 (setf (getf (car r) 'b)
       (progn (setq r nil) 6)) @EV{} 6
 r @EV{} NIL
 s @EV{} ((A 1 B 6 C 3))
;;; Note that the (setq r nil) does not affect the actions of
;;; the SETF because the value of R had already been saved in
;;; a temporary variable as part of the step 1. Only the CAR
;;; of this value will be retrieved, and subsequently modified
;;; after the value computation.
@end lisp

@end table
@end itemize




@node VALUES Forms as Places
@subsubsection VALUES Forms as Places

A @symbolref{values, A} @term{form} can be used as a @term{place},
provided that each of its @term{subforms} is also a @term{place} form.

A form such as

@tt{(setf (values @param{place-1} @dots{} @param{place-n}) @param{values-form})}

does the following:


@enumerate 1
@item The @term{subforms} of each nested @param{place} are evaluated
in left-to-right order.
@item The @param{values-form} is evaluated, and the first store
variable from each @param{place} is bound to its return values as if by
@symbolref{multiple-value-bind, SYM}.
@item If the @term{setf expansion} for any @param{place}
involves more than one store variable, then the additional
store variables are bound to @nil{}.
@item The storing forms for each @param{place} are evaluated in
left-to-right order.
@end enumerate


The storing form in the @term{setf expansion} of @symbolref{values, A}
returns as @term{multiple values}@sub{2} the values of the store
variables in step 2.  That is, the number of values returned is the
same as the number of @term{place} forms.  This may be more or fewer
values than are produced by the @param{values-form}.


@node THE Forms as Places
@subsubsection THE Forms as Places

A @symbolref{the, SYM} @term{form} can be used as a @term{place},
in which case the declaration is transferred to the @param{newvalue} form,
and the resulting @symbolref{setf, SYM} is analyzed.  For example,

@lisp
 (setf (the integer (cadr x)) (+ y 3))
@end lisp

is processed as if it were

@lisp
 (setf (cadr x) (the integer (+ y 3)))
@end lisp



@node APPLY Forms as Places
@subsubsection APPLY Forms as Places

The following situations involving @symbolref{setf, SYM} of @symbolref{apply, SYM} must be supported:


@itemize @bullet{}
@item @f{(setf (apply #'aref @param{array}
@starparam{subscript}
@param{more-subscripts})
@param{new-element})}
@item @f{(setf (apply #'bit @param{array}
@starparam{subscript}
@param{more-subscripts})
@param{new-element})}
@item @f{(setf (apply #'sbit @param{array}
@starparam{subscript}
@param{more-subscripts})
@param{new-element})}
@end itemize


In all three cases, the @term{element} of @param{array} designated
by the concatenation of @param{subscripts} and @param{more-subscripts}
(@ie{} the same @term{element} which would be @term{read} by the call to
@term{apply} if it were not part of a @symbolref{setf, SYM} @term{form})
is changed to have the @term{value} given by @param{new-element}.
For these usages, the function name (@symbolref{aref, SYM}, @symbolref{bit, A}, or @symbolref{sbit, SYM})
must refer to the global function definition, rather than a locally defined
@term{function}.

No other @term{standardized} @term{function} is required to be supported,
but an @term{implementation} may define such support.
An @term{implementation} may also define support
for @term{implementation-defined} @term{operators}.

If a user-defined @term{function} is used in this context,
the following equivalence is true, except that care is taken
to preserve proper left-to-right evaluation of argument @term{subforms}:

@lisp
 (setf (apply #'@param{name} @starparam{arg}) @param{val})
 @EQ{} (apply #'(setf @param{name}) @param{val} @starparam{arg})
@end lisp



@node Setf Expansions and Places
@subsubsection Setf Expansions and Places

Any @term{compound form} for which the @term{operator} has a
@term{setf expander}
defined can be used as a @term{place}.
The
@term{operator}
must refer to the global function definition,
rather than a locally defined @term{function} or @term{macro}.



@node Macro Forms as Places
@subsubsection Macro Forms as Places

A @term{macro form} can be used as a @term{place},
in which case @clisp{}@spc{}expands the @term{macro form}
as if by @symbolref{macroexpand-1, SYM}
and then uses the @term{macro expansion} in place of the original @term{place}.
Such @term{macro expansion} is attempted only after exhausting all other possibilities
other than expanding into a call to a function named @f{(setf @param{reader})}.


@node Symbol Macros as Places
@subsubsection Symbol Macros as Places

A reference to a @term{symbol} that has been @term{established} as a @term{symbol macro}
can be used as a @term{place}.  In this case,
@symbolref{setf, SYM} expands the reference and then analyzes the resulting @term{form}.


@node Other Compound Forms as Places
@subsubsection Other Compound Forms as Places

For any other @term{compound form} for which the @term{operator} is a
@term{symbol} @param{f},
the @symbolref{setf, SYM} @term{form} expands into a call
to the @term{function} named @f{(setf @param{f})}.
The first @term{argument} in the newly constructed @term{function form}
is @param{newvalue} and the
remaining @term{arguments} are the remaining @term{elements} of
@param{place}.
This expansion occurs regardless of whether @param{f} or @f{(setf @param{f})}
is defined as a @term{function} locally, globally, or not at all.
For example,

@f{(setf (@param{f} @param{arg1} @param{arg2} ...) @param{new-value})}

expands into a form with the same effect and value as

@lisp
 (let ((#:temp-1 arg1)          ;force correct order of evaluation
       (#:temp-2 arg2)
       ...
       (#:temp-0 @param{new-value}))
   (funcall (function (setf @param{f})) #:temp-0 #:temp-1 #:temp-2...))
@end lisp


A @term{function} named @f{(setf @param{f})} must return its first argument
as its only value in order to preserve the semantics of @symbolref{setf, SYM}.




@node Treatment of Other Macros Based on SETF
@subsection Treatment of Other Macros Based on SETF


For each of the ``read-modify-write'' @term{operators} in @thenextfigure{},
and for any additional @term{macros}
defined by the @term{programmer} using @symbolref{define-modify-macro, SYM},
an exception is made to the normal rule of left-to-right evaluation of arguments.
Evaluation of @term{argument} @term{forms} occurs in left-to-right order,
with the exception that for the @param{place} @term{argument}, the actual
@term{read} of the ``old value'' from that @param{place} happens
after all of the @term{argument} @term{form} @term{evaluations},
and just before a ``new value'' is computed and @i{written} back into the @param{place}.

Specifically, each of these @term{operators} can be viewed as involving a
@term{form} with the following general syntax:

@lisp
 (@term{operator} @starparam{preceding-form} @param{place} @starparam{following-form})
@end lisp


The evaluation of each such @term{form} proceeds like this:


@enumerate 1
@item @term{Evaluate} each of the @param{preceding-forms}, in left-to-right order.
@item @term{Evaluate} the @term{subforms} of the @param{place},
in the order specified by the second value of the @term{setf expansion}
for that @param{place}.
@item @term{Evaluate} each of the @param{following-forms}, in left-to-right order.
@item @term{Read} the old value from @param{place}.
@item Compute the new value.
@item Store the new value into @param{place}.
@end enumerate



@float Figure,fig5.9
@cartouche
@multitable{decf}{push}{pushnew}

@item decf @tab pop @tab pushnew
@item incf @tab push @tab remf
@end multitable
@end cartouche
@caption{Read-Modify-Write Macros}
@end float




@node Transfer of Control to an Exit Point
@section Transfer of Control to an Exit Point

When a transfer of control is initiated by @symbolref{go, SYM},
@symbolref{return-from, SYM}, or @symbolref{throw, SYM}
the following events occur in order to accomplish the transfer of control.
Note that for @symbolref{go, SYM},
the @term{exit point} is the @term{form} within the @symbolref{tagbody, SYM}
that is being executed at the time the @symbolref{go, SYM} is performed;
for @symbolref{return-from, SYM},
the @term{exit point} is the corresponding
@symbolref{block, SYM} @term{form};
and for @symbolref{throw, SYM},
the @term{exit point} is the corresponding
@symbolref{catch, SYM} @term{form}.


@enumerate 1
@item
Intervening @term{exit points} are ``abandoned''
(@ie{} their @term{extent} ends
and it is no longer valid to attempt to transfer control through them).

@item
The cleanup clauses of any intervening @symbolref{unwind-protect, SYM} clauses
are evaluated.

@item
Intervening dynamic @term{bindings} of @symbolref{special, SYM} variables,
@term{catch tags}, @term{condition handlers}, and @term{restarts}
are undone.

@item
The @term{extent} of the @term{exit point} being invoked ends,
and control is passed to the target.
@end enumerate


The extent of an exit being ``abandoned'' because it is being passed over
ends as soon as the transfer of control is initiated. That is,
event 1 occurs at the beginning of the initiation of the transfer of
control.
The consequences are undefined if an attempt is made to transfer control
to an @term{exit point} whose @term{dynamic extent} has ended.

Events 2 and 3 are actually performed interleaved, in the order
corresponding to the reverse order in which they were established.
The effect of this is that the cleanup clauses of an @symbolref{unwind-protect, SYM}
see the same dynamic @term{bindings}
of variables and @term{catch tags} as were
visible when the @symbolref{unwind-protect, SYM} was entered.

Event 4 occurs at the end of the transfer of control.

@node Data and Control Flow Dictionary
@section Data and Control Flow Dictionary

@menu
* apply::
* defun::
* fdefinition::
* fboundp::
* fmakunbound::
* flet; labels; macrolet::
* funcall::
* function (Special Operator)::
* function-lambda-expression::
* functionp::
* compiled-function-p::
* call-arguments-limit::
* lambda-list-keywords::
* lambda-parameters-limit::
* defconstant::
* defparameter; defvar::
* destructuring-bind::
* let; let*::
* progv::
* setq::
* psetq::
* block::
* catch::
* go::
* return-from::
* return::
* tagbody::
* throw::
* unwind-protect::
* nil (Constant Variable)::
* not (Function)::
* t (Constant Variable)::
* eq::
* eql (Function)::
* equal::
* equalp::
* identity::
* complement::
* constantly::
* every; some; notevery; notany::
* and (Macro)::
* cond::
* if::
* or (Macro)::
* when; unless::
* case; ccase; ecase::
* typecase; ctypecase; etypecase::
* multiple-value-bind::
* multiple-value-call::
* multiple-value-list::
* multiple-value-prog1::
* multiple-value-setq::
* values (Accessor)::
* values-list::
* multiple-values-limit::
* nth-value::
* prog; prog*::
* prog1; prog2::
* progn::
* define-modify-macro::
* defsetf::
* define-setf-expander::
* get-setf-expansion::
* setf; psetf::
* shiftf::
* rotatef::
* control-error::
* program-error::
* undefined-function::
@end menu

@node apply
@syindexanchor{apply, SYM}
@subsection apply (Function)
@cindex apply


@subsubheading Syntax:

@DefunWithValues{apply, function @rest{} @plus{args}, @starparam{result}}

@subsubheading Arguments and Values:

@param{function}---a @term{function designator}.

@param{args}---a @term{spreadable argument list designator}.

@param{results}---the @term{values} returned by @param{function}.

@subsubheading Description:

@term{Applies} the @param{function} to the @param{args}.

When the @param{function} receives its arguments via @keyref{rest}, it is
permissible (but not required) for the @term{implementation} to @term{bind}
the @term{rest parameter}
to an @term{object} that shares structure with the last argument to @symbolref{apply, SYM}.
Because a @term{function} can neither detect whether it was called via @symbolref{apply, SYM}
nor whether (if so) the last argument to @symbolref{apply, SYM} was a @term{constant},
@term{conforming programs} must neither rely on the @term{list} structure
of a @term{rest list} to be freshly consed, nor modify that @term{list} structure.

@symbolref{setf, SYM} can be used with @symbolref{apply, SYM} in certain circumstances;
see @ref{APPLY Forms as Places}.

@subsubheading Examples:

@lisp
 (setq f '+) @EV{} +
 (apply f '(1 2)) @EV{} 3
 (setq f #'-) @EV{} #<FUNCTION ->
 (apply f '(1 2)) @EV{} -1
 (apply #'max 3 5 '(2 7 3)) @EV{} 7
 (apply 'cons '((+ 2 3) 4)) @EV{} ((+ 2 3) . 4)
 (apply #'+ '()) @EV{} 0

 (defparameter *some-list* '(a b c))
 (defun strange-test (&rest x) (eq x *some-list*))
 (apply #'strange-test *some-list*) @EV{} @term{implementation-dependent}

 (defun bad-boy (&rest x) (rplacd x 'y))
 (bad-boy 'a 'b 'c) has undefined consequences.
 (apply #'bad-boy *some-list*) has undefined consequences.
@end lisp


@lisp
 (defun foo (size &rest keys &key double &allow-other-keys)
   (let ((v (apply #'make-array size :allow-other-keys t keys)))
     (if double (concatenate (type-of v) v v) v)))
 (foo 4 :initial-contents '(a b c d) :double t)
    @EV{} #(A B C D A B C D)
@end lisp


@subsubheading See Also:

@ref{funcall},
@ref{fdefinition},
@ref{function (Special Operator)},
@ref{Evaluation},
@ref{APPLY Forms as Places}


@node defun
@syindexanchor{defun, SYM}
@subsection defun (Macro)
@cindex defun



@subsubheading Syntax:

@DefmacWithValuesNewline{defun, function-name lambda-list @DeclsAndDoc{} @starparam{form}, function-name}

@subsubheading Arguments and Values:

@param{function-name}---a @term{function name}.

@param{lambda-list}---an @term{ordinary lambda list}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{documentation}---a @term{string}; @noeval{}.

@param{forms}---an @term{implicit progn}.

@param{block-name}---the @term{function block name} of the @param{function-name}.

@subsubheading Description:

Defines a new @term{function} named @param{function-name} in the @term{global environment}.
The body of the @term{function} defined by @symbolref{defun, SYM} consists
of @param{forms}; they are executed as an @term{implicit progn}
when the @term{function} is called.
@symbolref{defun, SYM} can be used
to define a new @term{function},
to install a corrected version of an incorrect definition,
to redefine an already-defined @term{function},
or to redefine a @term{macro} as a @term{function}.

@symbolref{defun, SYM} implicitly puts a @symbolref{block, SYM} named @param{block-name}
around the body @param{forms}
(but not the @term{forms} in the @param{lambda-list})
of the @term{function} defined.

@param{Documentation} is attached as a @term{documentation string}
to @param{name} (as kind @symbolref{function, SO})
and to the @term{function} @term{object}.

Evaluating @symbolref{defun, SYM} causes @param{function-name} to be a global name
for the @term{function} specified by the @term{lambda expression}

@lisp
 (lambda @param{lambda-list}
   @DeclsAndDoc{}
   (block @param{block-name} @starparam{form}))
@end lisp


processed in the @term{lexical environment} in which @symbolref{defun, SYM} was executed.

(None of the arguments are evaluated at macro expansion time.)

@symbolref{defun, SYM} is not required to perform any compile-time side effects.
In particular, @symbolref{defun, SYM} does not make the @term{function} definition available
at compile time.  An @term{implementation} may choose to store information
about the @term{function} for the purposes of compile-time error-checking
(such as checking the number of arguments on calls),
or to enable the @term{function} to be expanded inline.

@subsubheading Examples:

@lisp
 (defun recur (x)
  (when (> x 0)
    (recur (1- x)))) @EV{} RECUR
 (defun ex (a b &optional c (d 66) &rest keys &key test (start 0))
    (list a b c d keys test start)) @EV{} EX
 (ex 1 2) @EV{} (1 2 NIL 66 NIL NIL 0)
 (ex 1 2 3 4 :test 'equal :start 50)
@EV{} (1 2 3 4 (:TEST EQUAL :START 50) EQUAL 50)
 (ex :test 1 :start 2) @EV{} (:TEST 1 :START 2 NIL NIL 0)

 ;; This function assumes its callers have checked the types of the
 ;; arguments, and authorizes the compiler to build in that assumption.
 (defun discriminant (a b c)
   (declare (number a b c))
   "Compute the discriminant for a quadratic equation."
   (- (* b b) (* 4 a c))) @EV{} DISCRIMINANT
 (discriminant 1 2/3 -2) @EV{} 76/9

 ;; This function assumes its callers have not checked the types of the
 ;; arguments, and performs explicit type checks before making any assumptions.
 (defun careful-discriminant (a b c)
   "Compute the discriminant for a quadratic equation."
   (check-type a number)
   (check-type b number)
   (check-type c number)
   (locally (declare (number a b c))
     (- (* b b) (* 4 a c)))) @EV{} CAREFUL-DISCRIMINANT
 (careful-discriminant 1 2/3 -2) @EV{} 76/9
@end lisp


@subsubheading See Also:

@ref{flet},
@ref{labels},
@ref{block},
@ref{return-from},
@ref{declare},
@ref{documentation},
@ref{Evaluation},
@ref{Ordinary Lambda Lists},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading Notes:
@symbolref{return-from, SYM} can be used to return
prematurely from a @term{function} defined by @symbolref{defun, SYM}.

Additional side effects might take place when additional information
(typically debugging information)
about the function definition is recorded.



@node fdefinition
@syindexanchor{fdefinition, SYM}
@subsection fdefinition (Accessor)
@cindex fdefinition



@subsubheading Syntax:

@DefunWithValues{fdefinition, function-name, definition}
@Defsetf{fdefinition, function-name, new-definition}

@subsubheading Arguments and Values:

@param{function-name}---a @term{function name}.
In the non-@symbolref{setf, SYM} case,
the @term{name} must be @term{fbound} in the @term{global environment}.

@param{definition}---Current global function definition named by @param{function-name}.

@param{new-definition}---a @term{function}.

@subsubheading Description:

@symbolref{fdefinition, SYM} @term{accesses} the current global function definition
named by @param{function-name}.  The definition may be a
@term{function} or may be an @term{object} representing a
@term{special form} or @term{macro}.
The value returned by @symbolref{fdefinition, SYM} when @symbolref{fboundp, SYM} returns true
but the @param{function-name} denotes a @term{macro} or
@term{special form} is not well-defined, but @symbolref{fdefinition, SYM} does not signal an error.

@subsubheading Exceptional Situations:

@Shouldchecktype{function-name, a @term{function name}}

An error @oftype{undefined-function} is signaled
in the non-@symbolref{setf, SYM} case if @param{function-name} is not @term{fbound}.

@subsubheading See Also:

@ref{fboundp},
@ref{fmakunbound},
@ref{macro-function},
@ref{special-operator-p},
@ref{symbol-function}

@subsubheading Notes:

@symbolref{fdefinition, SYM} cannot @term{access} the value of a lexical function name
produced by @symbolref{flet, SYM} or @symbolref{labels, SYM}; it can @term{access} only
the global function value.

@symbolref{setf, SYM} can be used with
@symbolref{fdefinition, SYM} to replace a global function
definition when the @param{function-name}'s function definition
does not represent a @term{special form}.
@symbolref{setf, SYM} of @symbolref{fdefinition, SYM}
requires a @term{function} as the new value.
It is an error to set the @symbolref{fdefinition, SYM} of a @param{function-name}
to a @term{symbol}, a @term{list}, or the value returned
by @symbolref{fdefinition, SYM} on the name of a @term{macro}
or @term{special form}.


@node fboundp
@syindexanchor{fboundp, SYM}
@subsection fboundp (Function)
@cindex fboundp


@subsubheading Syntax:

@DefunWithValues{fboundp, name, generalized-boolean}

@subsubheading Pronunciation:

@pronounced{@stress{ef}@Stress{ba\.und}p@harde{}}

@subsubheading Arguments and Values:

@param{name}---a @term{function name}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

@Predicate{name, @term{fbound}}

@subsubheading Examples:

@lisp
 (fboundp 'car) @EV{} @term{true}
 (fboundp 'nth-value) @EV{} @term{false}
 (fboundp 'with-open-file) @EV{} @term{true}
 (fboundp 'unwind-protect) @EV{} @term{true}
 (defun my-function (x) x) @EV{} MY-FUNCTION
 (fboundp 'my-function) @EV{} @term{true}
 (let ((saved-definition (symbol-function 'my-function)))
   (unwind-protect (progn (fmakunbound 'my-function)
                          (fboundp 'my-function))
     (setf (symbol-function 'my-function) saved-definition)))
@EV{} @term{false}
 (fboundp 'my-function) @EV{} @term{true}
 (defmacro my-macro (x) `',x) @EV{} MY-MACRO
 (fboundp 'my-macro) @EV{} @term{true}
 (fmakunbound 'my-function) @EV{} MY-FUNCTION
 (fboundp 'my-function) @EV{} @term{false}
 (flet ((my-function (x) x))
   (fboundp 'my-function)) @EV{} @term{false}
@end lisp


@subsubheading Exceptional Situations:

@Shouldchecktype{name, a @term{function name}}

@subsubheading See Also:

@ref{symbol-function}, @ref{fmakunbound}, @ref{fdefinition}

@subsubheading Notes:

It is permissible to call @symbolref{symbol-function, SYM} on any @term{symbol}
that is @term{fbound}.

@symbolref{fboundp, SYM} is sometimes used to ``guard''
an access to the @term{function cell}, as in:
@lisp
(if (fboundp x) (symbol-function x))
@end lisp


Defining a @term{setf expander} @param{F} does not cause the @term{setf function}
@f{(setf @param{F})} to become defined.


@node fmakunbound
@syindexanchor{fmakunbound, SYM}
@subsection fmakunbound (Function)
@cindex fmakunbound


@subsubheading Syntax:

@DefunWithValues{fmakunbound, name, name}

@subsubheading Pronunciation:

@pronounced{@stress{ef}@Stress{mak}@schwa{} n@stress{ba\.und}}
or @pronounced{@stress{ef}@Stress{m@harda{} k}@schwa{} n@stress{ba\.und}}

@subsubheading Arguments and Values:

@param{name}---a @term{function name}.

@subsubheading Description:

Removes the @term{function} or @term{macro} definition, if any, of @param{name}
in the @term{global environment}.

@subsubheading Examples:

@lisp
(defun add-some (x) (+ x 19)) @EV{} ADD-SOME
 (fboundp 'add-some) @EV{} @term{true}
 (flet ((add-some (x) (+ x 37)))
    (fmakunbound 'add-some)
    (add-some 1)) @EV{} 38
 (fboundp 'add-some) @EV{} @term{false}
@end lisp


@subsubheading Exceptional Situations:

@Shouldchecktype{name, a @term{function name}}

The consequences are undefined if @param{name} is a @term{special operator}.

@subsubheading See Also:

@ref{fboundp}, @ref{makunbound}


@node flet; labels; macrolet
@syindexanchor{flet, SYM}
@syindexanchor{labels, SYM}
@syindexanchor{macrolet, SYM}
@subsection flet, labels, macrolet (Special Operator)
@cindex flet
@cindex labels
@cindex macrolet
@anchor{flet}
@anchor{labels}
@anchor{macrolet}



@subsubheading Syntax:

@DefspecWithValuesNewline{flet, @vtop{@hbox{@paren{@starparen{@param{function-name} @param{lambda-list} @LocalDeclsAndDoc{} @starparam{local-form}}}} @hbox{@starparam{declaration} @starparam{form}}}, @starparam{result}}

@DefspecWithValuesNewline{labels, @vtop{@hbox{@paren{@starparen{@param{function-name} @param{lambda-list} @LocalDeclsAndDoc{} @starparam{local-form}}}} @hbox{@starparam{declaration} @starparam{form}}}, @starparam{result}}

@DefspecWithValuesNewline{macrolet, @vtop{@hbox{@paren{@starparen{@param{name} @param{lambda-list} @LocalDeclsAndDoc{} @starparam{local-form}}}} @hbox{@starparam{declaration} @starparam{form}}}, @starparam{result}}

@subsubheading Arguments and Values:

@param{function-name}---a @term{function name}.

@param{name}---a @term{symbol}.

@param{lambda-list}---a @term{lambda list};
for @symbolref{flet, SYM} and @symbolref{labels, SYM},
it is an @term{ordinary lambda list};
for @symbolref{macrolet, SYM},
it is a @term{macro lambda list}.

@param{local-declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{local-documentation}---a @term{string}; @noeval{}.

@param{local-forms}, @param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} of the @param{forms}.

@subsubheading Description:

@symbolref{flet, SYM}, @symbolref{labels, SYM}, and @symbolref{macrolet, SYM}
define local @term{functions} and @term{macros}, and execute
@param{forms} using the local definitions.
@param{Forms} are executed  in order of occurrence.

The body forms (but not the @term{lambda list})
of each @term{function} created by @symbolref{flet, SYM} and @symbolref{labels, SYM}
and each @term{macro} created by @symbolref{macrolet, SYM}
are enclosed in an @term{implicit block} whose name
is the @term{function block name} of the @param{function-name} or @param{name},
as appropriate.

The scope of the @param{declarations}
between
the list of local function/macro definitions and the body @param{forms}
in @symbolref{flet, SYM} and @symbolref{labels, SYM}
does not include the bodies of the
locally defined @term{functions}, except that for @symbolref{labels, SYM},
any @symbolref{inline, SYM}, @symbolref{notinline, SYM}, or @symbolref{ftype, SYM} declarations
that refer to the locally defined functions do apply to the local function
bodies. That is, their @term{scope}
is the same as the function name that they
affect.
The scope of these @param{declarations}
does not include the bodies of the macro expander
functions defined by @symbolref{macrolet, SYM}.


@table @asis
@item @id{@bf{flet}}


@symbolref{flet, SYM} defines locally named @term{functions} and executes a series of
@param{forms} with these definition @term{bindings}.  Any number of
such local @term{functions} can be defined.

The @term{scope} of the name @term{binding} encompasses only the body.
Within the
body of @symbolref{flet, SYM},
@param{function-names} matching those defined
by @symbolref{flet, SYM}
refer to the locally defined @term{functions}
rather than to
the global function definitions of the same name.
Also, within the scope of @symbolref{flet, SYM},
global @term{setf expander} definitions of the @param{function-name}
defined by @symbolref{flet, SYM} do not apply.
Note that this applies to
@tt{(defsetf @i{f} ...)}, not
@tt{(defmethod (setf @i{f}) ...)}.

The names of @term{functions} defined by @symbolref{flet, SYM}
are in the @term{lexical environment}; they retain
their local definitions only within the body of @symbolref{flet, SYM}.
The function definition bindings are visible only in
the body of @symbolref{flet, SYM}, not the definitions themselves.  Within the
function definitions, local function names
that match those being
defined refer to @term{functions} or
@term{macros} defined outside the @symbolref{flet, SYM}.
@symbolref{flet, SYM} can locally @term{shadow} a global function name,
and the new definition can refer to the global definition.

Any @param{local-documentation} is attached to the corresponding local @param{function}
(if one is actually created) as a @term{documentation string}.

@item @id{@bf{labels}}


@symbolref{labels, SYM} is equivalent to @symbolref{flet, SYM} except that
the scope of the defined function names for @symbolref{labels, SYM}
encompasses the function definitions themselves as well as the body.

@item @id{@bf{macrolet}}


@symbolref{macrolet, SYM}
establishes local @term{macro} definitions,
using the same format used by @symbolref{defmacro, SYM}.

Within the body of @symbolref{macrolet, SYM},
global @term{setf expander} definitions of the @param{names} defined by the
@symbolref{macrolet, SYM} do not apply; rather, @symbolref{setf, SYM} expands the
@term{macro form} and recursively process the resulting @term{form}.

The macro-expansion functions defined by @symbolref{macrolet, SYM}
are defined in the
@term{lexical environment} in which the @symbolref{macrolet, SYM} form appears.
Declarations and @symbolref{macrolet, SYM} and
@symbolref{symbol-macrolet, SYM} definitions
affect the local macro definitions in a @symbolref{macrolet, SYM}, but the
consequences are undefined if the local macro definitions reference
any local @term{variable} or @term{function} @term{bindings} that are visible in that
@term{lexical environment}.

Any @param{local-documentation} is attached to the corresponding local @param{macro function}
as a @term{documentation string}.
@end table


@subsubheading Examples:

@lisp
 (defun foo (x flag)
   (macrolet ((fudge (z)
                 ;The parameters x and flag are not accessible
                 ; at this point; a reference to flag would be to
                 ; the global variable of that name.
                 @bq{}@spc{}(if flag (* ,z ,z) ,z)))
    ;The parameters x and flag are accessible here.
     (+ x
        (fudge x)
        (fudge (+ x 1)))))
 @EQ{}
 (defun foo (x flag)
   (+ x
      (if flag (* x x) x)
      (if flag (* (+ x 1) (+ x 1)) (+ x 1))))
@end lisp

after macro expansion.  The occurrences of @f{x} and @f{flag} legitimately
refer to the parameters of the function @f{foo} because those parameters are
visible at the site of the macro call which produced the expansion.


@lisp
 (flet ((flet1 (n) (+ n n)))
    (flet ((flet1 (n) (+ 2 (flet1 n))))
      (flet1 2))) @EV{} 6

 (defun dummy-function () 'top-level) @EV{} DUMMY-FUNCTION
 (funcall #'dummy-function) @EV{} TOP-LEVEL
 (flet ((dummy-function () 'shadow))
      (funcall #'dummy-function)) @EV{} SHADOW
 (eq (funcall #'dummy-function) (funcall 'dummy-function))
@EV{} @term{true}
 (flet ((dummy-function () 'shadow))
   (eq (funcall #'dummy-function)
       (funcall 'dummy-function)))
@EV{} @term{false}

 (defun recursive-times (k n)
   (labels ((temp (n)
              (if (zerop n) 0 (+ k (temp (1- n))))))
     (temp n))) @EV{} RECURSIVE-TIMES
 (recursive-times 2 3) @EV{} 6

 (defmacro mlets (x &environment env)
    (let ((form `(babbit ,x)))
      (macroexpand form env))) @EV{} MLETS
 (macrolet ((babbit (z) `(+ ,z ,z))) (mlets 5)) @EV{} 10
@end lisp


@lisp
 (flet ((safesqrt (x) (sqrt (abs x))))
  ;; The safesqrt function is used in two places.
   (safesqrt (apply #'+ (map 'list #'safesqrt '(1 2 3 4 5 6)))))
@EV{} 3.291173
@end lisp


@lisp
 (defun integer-power (n k)
   (declare (integer n))
   (declare (type (integer 0 *) k))
   (labels ((expt0 (x k a)
              (declare (integer x a) (type (integer 0 *) k))
              (cond ((zerop k) a)
                    ((evenp k) (expt1 (* x x) (floor k 2) a))
                    (t (expt0 (* x x) (floor k 2) (* x a)))))
            (expt1 (x k a)
              (declare (integer x a) (type (integer 0 *) k))
              (cond ((evenp k) (expt1 (* x x) (floor k 2) a))
                    (t (expt0 (* x x) (floor k 2) (* x a))))))
    (expt0 n k 1))) @EV{} INTEGER-POWER
@end lisp


@lisp
 (defun example (y l)
   (flet ((attach (x)
            (setq l (append l (list x)))))
     (declare (inline attach))
     (dolist (x y)
       (unless (null (cdr x))
         (attach x)))
     l))

 (example '((a apple apricot) (b banana) (c cherry) (d) (e))
          '((1) (2) (3) (4 2) (5) (6 3 2)))
@EV{} ((1) (2) (3) (4 2) (5) (6 3 2) (A APPLE APRICOT) (B BANANA) (C CHERRY))
@end lisp


@subsubheading See Also:

@ref{declare},
@ref{defmacro},
@ref{defun},
@ref{documentation},
@ref{let},
@ref{Evaluation},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading Notes:

It is not possible to define recursive @term{functions} with @symbolref{flet, SYM}.
@symbolref{labels, SYM} can be used to define mutually recursive @term{functions}.

If a @symbolref{macrolet, SYM} @term{form} is a @term{top level form},
the body @param{forms} are also processed as @term{top level forms}.
See @ref{File Compilation}.



@node funcall
@syindexanchor{funcall, SYM}
@subsection funcall (Function)
@cindex funcall


@subsubheading Syntax:

@DefunWithValues{funcall, function @rest{} args, @starparam{result}}

@subsubheading Arguments and Values:

@param{function}---a @term{function designator}.

@param{args}---@term{arguments} to the @param{function}.

@param{results}---the @term{values} returned by the @param{function}.

@subsubheading Description:

@symbolref{funcall, SYM} applies @param{function} to @param{args}.
If @param{function} is a @term{symbol},
it is coerced to a @term{function} as if by
finding its @term{functional value} in the @term{global environment}.

@subsubheading Examples:

@lisp
 (funcall #'+ 1 2 3) @EV{} 6
 (funcall 'car '(1 2 3)) @EV{} 1
 (funcall 'position 1 '(1 2 3 2 1) :start 1) @EV{} 4
 (cons 1 2) @EV{} (1 . 2)
 (flet ((cons (x y) `(kons ,x ,y)))
   (let ((cons (symbol-function '+)))
     (funcall #'cons
              (funcall 'cons 1 2)
              (funcall cons 1 2))))
@EV{} (KONS (1 . 2) 3)
@end lisp


@subsubheading Exceptional Situations:

An error @oftype{undefined-function} should be signaled if @param{function}
is a @term{symbol} that does not have a global definition as a @term{function}
or that has a global definition as a @term{macro} or a @term{special operator}.

@subsubheading See Also:

@ref{Evaluation}

@subsubheading Notes:

@lisp
 (funcall @param{function} @param{arg1} @param{arg2} ...)
 @EQ{} (apply @param{function} @param{arg1} @param{arg2} ... nil)
 @EQ{} (apply @param{function} (list @param{arg1} @param{arg2} ...))
@end lisp


The difference between @symbolref{funcall, SYM} and an ordinary function call is that
in the former case the @param{function} is obtained by ordinary @term{evaluation}
of a @term{form}, and in the latter case it is obtained by the special
interpretation of the function position that normally occurs.


@node function (Special Operator)
@syindexanchor{function, SO}
@subsection function (Special Operator)
@cindex function



@subsubheading Syntax:

@DefspecWithValues{function, name, function}

@subsubheading Arguments and Values:

@param{name}---a @term{function name} or @term{lambda expression}.

@param{function}---a @term{function} @term{object}.

@subsubheading Description:

The @term{value} of @symbolref{function, SO} is the @term{functional value} of @param{name}
in the current @term{lexical environment}.

If @param{name} is a @term{function name}, the functional definition of that name
is that
established by the innermost lexically enclosing
@symbolref{flet, SYM}, @symbolref{labels, SYM}, or @symbolref{macrolet, SYM} @term{form},
if there is one.  Otherwise the global functional definition of the
@term{function name}
is returned.

If @param{name} is a @term{lambda expression}, then a @term{lexical closure}
is returned.  In situations where a @term{closure} over the same set of
@term{bindings} might be produced more than once, the various resulting
@term{closures} might or might not be @symbolref{eq, SYM}.

It is an error to use @symbolref{function, SO} on a @term{function name}
that does not denote a @term{function} in the lexical environment in
which the @symbolref{function, SO} form appears.
Specifically, it is an error to use @symbolref{function, SO} on a @term{symbol}
that denotes a @term{macro} or @term{special form}.
An implementation may choose not to signal this error for
performance reasons, but implementations are forbidden from
defining the failure to signal an error as a useful behavior.

@subsubheading Examples:

@lisp
 (defun adder (x) (function (lambda (y) (+ x y))))
@end lisp

The result of @f{(adder 3)} is a function that adds @f{3} to its argument:

@lisp
 (setq add3 (adder 3))
 (funcall add3 5) @EV{} 8
@end lisp

This works because @symbolref{function, SO} creates a @term{closure} of
the @term{lambda expression} that is able to refer to the @term{value} @f{3}
of the variable @f{x} even after control has returned from the function @f{adder}.

@subsubheading See Also:

@ref{defun},
@ref{fdefinition},
@ref{flet},
@ref{labels},
@ref{symbol-function},
@ref{Symbols as Forms},
@ref{Sharpsign Single-Quote},
@ref{Printing Other Objects}

@subsubheading Notes:

The notation @tt{#'@param{name}} may be used as an abbreviation
for @tt{(function @param{name})}.


@node function-lambda-expression
@syindexanchor{function-lambda-expression, SYM}
@subsection function-lambda-expression (Function)
@cindex function-lambda-expression



@subsubheading Syntax:

@DefunWithValuesNewline{function-lambda-expression, function, lambda-expression\, closure-p\, name}

@subsubheading Arguments and Values:

@param{function}---a @term{function}.

@param{lambda-expression}---a @term{lambda expression} or @nil{}.

@param{closure-p}---a @term{generalized boolean}.

@param{name}---an @term{object}.

@subsubheading Description:

Returns information about @param{function} as follows:

The @term{primary value}, @param{lambda-expression},
is @param{function}'s defining @term{lambda expression},
or @nil{}@spc{}if the information is not available.  The @term{lambda expression}
may have been pre-processed in some ways, but it should remain a suitable
argument to @symbolref{compile, SYM} or @symbolref{function, SO}.
Any @term{implementation} may legitimately return @nil{}
as the @param{lambda-expression} of any @param{function}.

The @term{secondary value}, @param{closure-p},
is @nil{}@spc{}if @param{function}'s definition was enclosed
in the @term{null lexical environment} or something @term{non-nil} if
@param{function}'s definition might have been enclosed in some
@term{non-null lexical environment}.
Any @term{implementation} may legitimately return @term{true}
as the @param{closure-p} of any @param{function}.

The @term{tertiary value}, @param{name},
is the ``name'' of @param{function}.
The name is intended for debugging only and is not necessarily one that would
be valid for use as a name in @symbolref{defun, SYM} or @symbolref{function, SO}, for example.
By convention, @nil{}@spc{}is used to mean that @param{function} has no name.
Any @term{implementation} may legitimately return @nil{}
as the @param{name} of any @param{function}.

@subsubheading Examples:

The following examples illustrate some possible return values, but
are not intended to be exhaustive:

@lisp
 (function-lambda-expression #'(lambda (x) x))
@EV{} NIL, @term{false}, NIL
@OV{} NIL, @term{true}, NIL
@OV{} (LAMBDA (X) X), @term{true}, NIL
@OV{} (LAMBDA (X) X), @term{false}, NIL

 (function-lambda-expression
    (funcall #'(lambda () #'(lambda (x) x))))
@EV{} NIL, @term{false}, NIL
@OV{} NIL, @term{true}, NIL
@OV{} (LAMBDA (X) X), @term{true}, NIL
@OV{} (LAMBDA (X) X), @term{false}, NIL

 (function-lambda-expression
    (funcall #'(lambda (x) #'(lambda () x)) nil))
@EV{} NIL, @term{true}, NIL
@OV{} (LAMBDA () X), @term{true}, NIL
@NV{} NIL, @term{false}, NIL
@NV{} (LAMBDA () X), @term{false}, NIL

 (flet ((foo (x) x))
   (setf (symbol-function 'bar) #'foo)
   (function-lambda-expression #'bar))
@EV{} NIL, @term{false}, NIL
@OV{} NIL, @term{true}, NIL
@OV{} (LAMBDA (X) (BLOCK FOO X)), @term{true}, NIL
@OV{} (LAMBDA (X) (BLOCK FOO X)), @term{false}, FOO
@OV{} (SI::BLOCK-LAMBDA FOO (X) X), @term{false}, FOO

 (defun foo ()
   (flet ((bar (x) x))
     #'bar))
 (function-lambda-expression (foo))
@EV{} NIL, @term{false}, NIL
@OV{} NIL, @term{true}, NIL
@OV{} (LAMBDA (X) (BLOCK BAR X)), @term{true}, NIL
@OV{} (LAMBDA (X) (BLOCK BAR X)), @term{true}, (:INTERNAL FOO 0 BAR)
@OV{} (LAMBDA (X) (BLOCK BAR X)), @term{false}, "BAR in FOO"
@end lisp


@subsubheading Notes:

Although @term{implementations} are free to return ``@nil{}, @term{true}, @nil{}'' in all cases,
they are encouraged to return a @term{lambda expression} as the @term{primary value}
in the case where the argument was created by a call to @symbolref{compile, SYM}
or @symbolref{eval, SYM} (as opposed to being created by @term{loading} a @term{compiled file}).



@node functionp
@syindexanchor{functionp, SYM}
@subsection functionp (Function)
@cindex functionp



@subsubheading Syntax:

@DefunWithValues{functionp, object, generalized-boolean}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

@TypePredicate{object, function}

@subsubheading Examples:

@lisp
 (functionp 'append) @EV{} @term{false}
 (functionp #'append) @EV{} @term{true}
 (functionp (symbol-function 'append)) @EV{} @term{true}
 (flet ((f () 1)) (functionp #'f)) @EV{} @term{true}
 (functionp (compile nil '(lambda () 259))) @EV{} @term{true}
 (functionp nil) @EV{} @term{false}
 (functionp 12) @EV{} @term{false}
 (functionp '(lambda (x) (* x x))) @EV{} @term{false}
 (functionp #'(lambda (x) (* x x))) @EV{} @term{true}
@end lisp


@subsubheading Notes:

@lisp
 (functionp @param{object}) @EQ{} (typep @param{object} 'function)
@end lisp




@node compiled-function-p
@syindexanchor{compiled-function-p, SYM}
@subsection compiled-function-p (Function)
@cindex compiled-function-p


@subsubheading Syntax:

@DefunWithValues{compiled-function-p, object, generalized-boolean}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

@TypePredicate{object, compiled-function}

@subsubheading Examples:

@lisp
 (defun f (x) x) @EV{} F
 (compiled-function-p #'f)
@EV{} @term{false}
@OV{} @term{true}
 (compiled-function-p 'f) @EV{} @term{false}
 (compile 'f) @EV{} F
 (compiled-function-p #'f) @EV{} @term{true}
 (compiled-function-p 'f) @EV{} @term{false}
 (compiled-function-p (compile nil '(lambda (x) x)))
@EV{} @term{true}
 (compiled-function-p #'(lambda (x) x))
@EV{} @term{false}
@OV{} @term{true}
 (compiled-function-p '(lambda (x) x)) @EV{} @term{false}
@end lisp


@subsubheading See Also:

@ref{compile},
@ref{compile-file},
@ref{compiled-function}

@subsubheading Notes:

@lisp
 (compiled-function-p @param{object}) @EQ{} (typep @param{object} 'compiled-function)
@end lisp



@node call-arguments-limit
@syindexanchor{call-arguments-limit, SYM}
@subsection call-arguments-limit (Constant Variable)
@cindex call-arguments-limit


@subsubheading Constant Value:

An integer not smaller than @f{50} and at least as great as
the @term{value} of @symbolref{lambda-parameters-limit, SYM},
the exact magnitude of which is @term{implementation-dependent}.

@subsubheading Description:

The upper exclusive bound on the number of @term{arguments} that
may be passed to a @term{function}.

@subsubheading See Also:

@ref{lambda-parameters-limit}, @ref{multiple-values-limit}


@node lambda-list-keywords
@syindexanchor{lambda-list-keywords, SYM}
@subsection lambda-list-keywords (Constant Variable)
@cindex lambda-list-keywords


@subsubheading Constant Value:

a @term{list}, the @term{elements} of which are @term{implementation-dependent},
but which must contain at least the @term{symbols}
@keyref{allow-other-keys},
@keyref{aux},
@keyref{body},
@keyref{environment},
@keyref{key},
@keyref{optional},
@keyref{rest},
and
@keyref{whole}.

@subsubheading Description:

A @term{list} of all the @term{lambda list keywords} used
in the @term{implementation}, including the additional ones
used only by @term{macro} definition @term{forms}.

@subsubheading See Also:

@ref{defun},
@ref{flet},
@ref{defmacro},
@ref{macrolet},
@ref{The Evaluation Model}


@node lambda-parameters-limit
@syindexanchor{lambda-parameters-limit, SYM}
@subsection lambda-parameters-limit (Constant Variable)
@cindex lambda-parameters-limit


@subsubheading Constant Value:

@term{implementation-dependent}, but not smaller than @f{50}.

@subsubheading Description:

A positive @term{integer} that is the upper exclusive bound on
the number of @term{parameter} @term{names} that can appear
in a single @term{lambda list}.

@subsubheading See Also:

@ref{call-arguments-limit}

@subsubheading Notes:

Implementors are encouraged to make the @term{value} of
@symbolref{lambda-parameters-limit, SYM} as large as possible.


@node defconstant
@syindexanchor{defconstant, SYM}
@subsection defconstant (Macro)
@cindex defconstant


@subsubheading Syntax:

@DefmacWithValues{defconstant, name initial-value @brac{documentation}, name}

@subsubheading Arguments and Values:

@param{name}---a @term{symbol}; @noeval{}.

@param{initial-value}---a @term{form}; @eval{}.

@param{documentation}---a @term{string}; @noeval{}.

@subsubheading Description:

@symbolref{defconstant, SYM}
causes the global variable named by @param{name} to be
given a value that is the result of evaluating @param{initial-value}.

A constant defined by @symbolref{defconstant, SYM} can be redefined
with @symbolref{defconstant, SYM}.
However, the consequences are undefined if an attempt is made to assign
a @term{value} to the @term{symbol} using another operator, or to
assign it to a @term{different}
@term{value} using a subsequent
@symbolref{defconstant, SYM}.

If @param{documentation} is supplied, it is attached to @param{name} as a
@term{documentation string} of kind @t{variable}.

@symbolref{defconstant, SYM}
normally appears as a @term{top level form}, but it is meaningful
for it to appear as a @term{non-top-level form}.
However, the compile-time side
effects described below
only take place when @symbolref{defconstant, SYM} appears as a
@term{top level form}.

The consequences are undefined if there are any
@term{bindings}
of the variable named by @param{name} at the time @symbolref{defconstant, SYM}
is executed or if the value is not @symbolref{eql, F} to the value of
@param{initial-value}.

The consequences are undefined when constant @term{symbols} are rebound
as either lexical or dynamic variables.  In other words, a reference to a
@term{symbol} declared with @symbolref{defconstant, SYM} always refers to its global value.

The side effects of the execution of @symbolref{defconstant, SYM} must
be equivalent to at least the side effects of the execution of the following
code:

@lisp
 (setf (symbol-value '@i{name}) @i{initial-value})
 (setf (documentation '@i{name} 'variable) '@i{documentation})
@end lisp


If a @symbolref{defconstant, SYM} @term{form} appears as a @term{top level form},
the @term{compiler} must recognize that @param{name} names
a @term{constant variable}.  An implementation may choose to
evaluate the value-form at compile time, load time, or both.
Therefore, users must ensure that the @param{initial-value}
can be @term{evaluated} at compile time
(regardless of whether or not references to @param{name}
appear in the file) and that it always @term{evaluates}
to the same value.

@editornote{KMP: Does ``same value'' here mean eql or similar?}
@reviewer{Moon: Probably depends on whether load time is compared to compile time,
or two compiles.}

@subsubheading Examples:
@lisp
 (defconstant this-is-a-constant 'never-changing "for a test") @EV{} THIS-IS-A-CONSTANT
this-is-a-constant @EV{} NEVER-CHANGING
 (documentation 'this-is-a-constant 'variable) @EV{} "for a test"
 (constantp 'this-is-a-constant) @EV{} @term{true}
@end lisp


@subsubheading See Also:

@ref{declaim},
@ref{defparameter},
@ref{defvar},
@ref{documentation},
@ref{proclaim},
@ref{Constant Variables},
@ref{Compilation}


@node defparameter; defvar
@syindexanchor{defparameter, SYM}
@syindexanchor{defvar, SYM}
@subsection defparameter, defvar (Macro)
@cindex defparameter
@cindex defvar
@anchor{defparameter}
@anchor{defvar}


@subsubheading Syntax:

@DefmacWithValues{defparameter, name         initial-value @brac{documentation} , name}
@DefmacWithValues{defvar, name @ttbrac{initial-value @brac{documentation}}, name}

@subsubheading Arguments and Values:

@param{name}---a @term{symbol}; @noeval{}.


@param{initial-value}---a @term{form};
for @symbolref{defparameter, SYM}, it is always @term{evaluated},
but for @symbolref{defvar, SYM} it is @term{evaluated}
only if @param{name} is not already @term{bound}.

@param{documentation}---a @param{string}; @noeval{}.

@subsubheading Description:

@symbolref{defparameter, SYM} and @symbolref{defvar, SYM} @term{establish} @param{name}
as a @term{dynamic variable}.

@symbolref{defparameter, SYM} unconditionally
@term{assigns} the @param{initial-value} to the @term{dynamic variable} named @param{name}.
@symbolref{defvar, SYM}, by contrast, @term{assigns} @param{initial-value} (if supplied)
to the @term{dynamic variable} named @param{name}
only if @param{name} is not already @term{bound}.

If no @param{initial-value} is supplied,
@symbolref{defvar, SYM} leaves the @term{value cell} of
the @term{dynamic variable} named @param{name} undisturbed;
if @param{name} was previously @term{bound}, its old @term{value} persists,
and if it was previously @term{unbound}, it remains @term{unbound}.

If @param{documentation} is supplied, it is attached to @param{name} as a
@term{documentation string} of kind @t{variable}.

@symbolref{defparameter, SYM} and @symbolref{defvar, SYM} normally appear as a @term{top level form},
but it is meaningful for them to appear as @term{non-top-level forms}.  However,
the compile-time side effects described below only take place when
they appear as @term{top level forms}.

@subsubheading Examples:

@lisp
 (defparameter *p* 1) @EV{} *P*
 *p* @EV{} 1
 (constantp '*p*) @EV{} @term{false}
 (setq *p* 2) @EV{} 2
 (defparameter *p* 3) @EV{} *P*
 *p* @EV{} 3

 (defvar *v* 1) @EV{} *V*
 *v* @EV{} 1
 (constantp '*v*) @EV{} @term{false}
 (setq *v* 2) @EV{} 2
 (defvar *v* 3) @EV{} *V*
 *v* @EV{} 2

 (defun foo ()
   (let ((*p* 'p) (*v* 'v))
     (bar))) @EV{} FOO
 (defun bar () (list *p* *v*)) @EV{} BAR
 (foo) @EV{} (P V)
@end lisp


The principal operational distinction between @symbolref{defparameter, SYM} and @symbolref{defvar, SYM}
is that @symbolref{defparameter, SYM} makes an unconditional assignment to @param{name},
while @symbolref{defvar, SYM} makes a conditional one.  In practice, this means that
@symbolref{defparameter, SYM} is useful in situations where loading or reloading the definition
would want to pick up a new value of the variable, while @symbolref{defvar, SYM} is used in
situations where the old value would want to be retained if the file were loaded or reloaded.
For example, one might create a file which contained:

@lisp
 (defvar *the-interesting-numbers* '())
 (defmacro define-interesting-number (name n)
   `(progn (defvar ,name ,n)
           (pushnew ,name *the-interesting-numbers*)
           ',name))
 (define-interesting-number *my-height* 168) ;cm
 (define-interesting-number *my-weight* 13)  ;stones
@end lisp


Here the initial value, @f{()}, for the variable @f{*the-interesting-numbers*}
is just a seed that we are never likely to want to reset to something else
once something has been grown from it.  As such, we have used @symbolref{defvar, SYM}
to avoid having the @f{*interesting-numbers*} information reset if the file is
loaded a second time.  It is true that the two calls to
@code{define-interesting-number} here would be reprocessed, but
if there were additional calls in another file, they would not be and that
information would be lost.  On the other hand, consider the following code:

@lisp
 (defparameter *default-beep-count* 3)
 (defun beep (&optional (n *default-beep-count*))
   (dotimes (i n) (si:%beep 1000. 100000.) (sleep 0.1)))
@end lisp


Here we could easily imagine editing the code to change the initial value of
@f{*default-beep-count*}, and then reloading the file to pick up the new value.
In order to make value updating easy, we have used @symbolref{defparameter, SYM}.

On the other hand, there is potential value to using @symbolref{defvar, SYM} in this
situation.  For example, suppose that someone had predefined an alternate
value for @f{*default-beep-count*}, or had loaded the file and then manually
changed the value.  In both cases, if we had used @symbolref{defvar, SYM} instead of
@symbolref{defparameter, SYM}, those user preferences would not be overridden by
(re)loading the file.

The choice of whether to use @symbolref{defparameter, SYM} or @symbolref{defvar, SYM} has
visible consequences to programs, but is nevertheless often made for subjective
reasons.

@subsubheading Side Effects:

If a @symbolref{defvar, SYM} or @symbolref{defparameter, SYM} @term{form} appears as a @term{top level form},
the @term{compiler} must recognize that the @param{name} has been
proclaimed @symbolref{special, SYM}.  However, it must neither @term{evaluate}
the @param{initial-value} @term{form} nor @term{assign} the
@term{dynamic variable} named @param{name} at compile time.

There may be additional (@term{implementation-defined}) compile-time or
run-time side effects, as long as such effects do not interfere with the
correct operation of @term{conforming programs}.

@subsubheading Affected By:

@symbolref{defvar, SYM} is affected by whether @param{name} is already @term{bound}.

@subsubheading See Also:

@ref{declaim},
@ref{defconstant},
@ref{documentation},
@ref{Compilation}

@subsubheading Notes:

It is customary to name @term{dynamic variables} with an @term{asterisk}
at the beginning and end of the name.  e.g., @f{*foo*} is a good name for
a @term{dynamic variable}, but not for a @term{lexical variable};
@f{foo} is a good name for a @term{lexical variable},
but not for a @term{dynamic variable}.
This naming convention is observed for all @term{defined names} in @clisp{};
however, neither @term{conforming programs} nor @term{conforming implementations}
are obliged to adhere to this convention.

The intent of the permission for additional side effects is to allow
@term{implementations} to do normal ``bookkeeping'' that accompanies
definitions.  For example, the @term{macro expansion} of a @symbolref{defvar, SYM}
or @symbolref{defparameter, SYM} @term{form} might include code that arranges to
record the name of the source file in which the definition occurs.

@symbolref{defparameter, SYM} and @symbolref{defvar, SYM} might be defined as follows:

@lisp
 (defmacro defparameter (name initial-value
                         &optional (documentation nil documentation-p))
   `(progn (declaim (special ,name))
           (setf (symbol-value ',name) ,initial-value)
           ,(when documentation-p
              `(setf (documentation ',name 'variable) ',documentation))
           ',name))
 (defmacro defvar (name &optional
                        (initial-value nil initial-value-p)
                        (documentation nil documentation-p))
   `(progn (declaim (special ,name))
           ,(when initial-value-p
              `(unless (boundp ',name)
                 (setf (symbol-value ',name) ,initial-value)))
           ,(when documentation-p
              `(setf (documentation ',name 'variable) ',documentation))
           ',name))
@end lisp



@node destructuring-bind
@syindexanchor{destructuring-bind, SYM}
@subsection destructuring-bind (Macro)
@cindex destructuring-bind



@subsubheading Syntax:

@DefmacWithValuesNewline{destructuring-bind, lambda-list expression @starparam{declaration} @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{lambda-list}---a @term{destructuring lambda list}.

@param{expression}---a @term{form}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} returned by the @term{forms}.

@subsubheading Description:

@symbolref{destructuring-bind, SYM} binds the variables specified in @param{lambda-list}
to the corresponding values in the tree structure resulting from the evaluation
of @param{expression}; then @symbolref{destructuring-bind, SYM} evaluates @param{forms}.

The @param{lambda-list} supports destructuring as described in
@ref{Destructuring Lambda Lists}.

@subsubheading Examples:
@lisp
 (defun iota (n) (loop for i from 1 to n collect i))       ;helper
 (destructuring-bind ((a &optional (b 'bee)) one two three)
     `((alpha) ,@@(iota 3))
   (list a b three two one)) @EV{} (ALPHA BEE 3 2 1)
@end lisp


@subsubheading Exceptional Situations:

If the result of evaluating the @param{expression} does not match the
destructuring pattern, an error @oftype{error} should be signaled.

@subsubheading See Also:

@ref{macrolet}, @ref{defmacro}



@node let; let*
@syindexanchor{let, SYM}
@syindexanchor{let*, SYM}
@subsection let, let* (Special Operator)
@cindex let
@cindex let*
@anchor{let}



@subsubheading Syntax:

@DefspecWithValues{let, @paren{@star{@VarValue{}}} @starparam{declaration} @starparam{form}, @starparam{result}}

@DefspecWithValues{let*, @paren{@star{@VarValue{}}} @starparam{declaration} @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{var}---a @term{symbol}.

@param{init-form}---a @term{form}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{form}---a @term{form}.

@param{results}---the @term{values} returned by the @term{forms}.

@subsubheading Description:

@symbolref{let, SYM} and @symbolref{let*, SYM}
create new variable @term{bindings} and
execute a series of @param{forms} that use these @term{bindings}.
@symbolref{let, SYM} performs the @term{bindings} in parallel and
@symbolref{let*, SYM} does them sequentially.

The form

@lisp
 (let ((@param{var1} @param{init-form-1})
       (@param{var2} @param{init-form-2})
       ...
       (@param{varm} @param{init-form-m}))
   @param{declaration1}
   @param{declaration2}
   ...
   @param{declarationp}
   @param{form1}
   @param{form2}
   ...
   @param{formn})
@end lisp

first evaluates the expressions @param{init-form-1}, @param{init-form-2}, and so on,
in that order, saving the resulting values.
Then all of the variables @param{varj} are bound to the corresponding
values; each @term{binding} is lexical unless
there is a @symbolref{special, SYM} declaration to the contrary.
The expressions @param{formk} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of a @symbolref{let, SYM}
is an @term{implicit progn}).

@symbolref{let*, SYM}
is similar to @symbolref{let, SYM}, but the @term{bindings} of variables
are performed sequentially rather than in parallel.
The expression for the @param{init-form} of a
@param{var} can refer to @param{vars}
previously bound in the @symbolref{let*, SYM}.

The form

@lisp
 (let* ((@param{var1} @param{init-form-1})
        (@param{var2} @param{init-form-2})
        ...
        (@param{varm} @param{init-form-m}))
   @param{declaration1}
   @param{declaration2}
   ...
   @param{declarationp}
   @param{form1}
   @param{form2}
   ...
   @param{formn})
@end lisp

first evaluates the expression @param{init-form-1}, then binds the variable
@param{var1} to that value; then it evaluates @param{init-form-2} and binds
@param{var2}, and so on.
The expressions @param{formj} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of @symbolref{let*, SYM} is an implicit @symbolref{progn, SYM}).

For both @symbolref{let, SYM} and @symbolref{let*, SYM},
if there is not an @param{init-form} associated with a @param{var},
@param{var} is initialized to @nil{}.

The special form @symbolref{let, SYM}
has the property that the @term{scope}
of the name binding does not include any
initial value form.
For @symbolref{let*, SYM}, a variable's @term{scope} also includes the
remaining initial value forms for subsequent variable bindings.

@subsubheading Examples:

@lisp
 (setq a 'top) @EV{} TOP
 (defun dummy-function () a) @EV{} DUMMY-FUNCTION
 (let ((a 'inside) (b a))
    (format nil "~S ~S ~S" a b (dummy-function))) @EV{} "INSIDE TOP TOP"
 (let* ((a 'inside) (b a))
    (format nil "~S ~S ~S" a b (dummy-function))) @EV{} "INSIDE INSIDE TOP"
 (let ((a 'inside) (b a))
    (declare (special a))
    (format nil "~S ~S ~S" a b (dummy-function))) @EV{} "INSIDE TOP INSIDE"
@end lisp


@medbreak{}
The code

@lisp
 (let (x)
   (declare (integer x))
   (setq x (gcd y z))
   ...)
@end lisp

is incorrect; although @f{x} is indeed set before it is used,
and is set to a value of the declared type @term{integer}, nevertheless
@f{x} initially takes on the value @nil{}@spc{}in violation of the type
declaration.

@subsubheading See Also:

@ref{progv}



@node progv
@syindexanchor{progv, SYM}
@subsection progv (Special Operator)
@cindex progv


@subsubheading Syntax:

@DefspecWithValues{progv, @param{symbols} @param{values} @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{symbols}---a @term{list} of @term{symbols}; @eval{}.

@param{values}---a @term{list} of @term{objects}; @eval{}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} returned by the @term{forms}.

@subsubheading Description:

@symbolref{progv, SYM} creates new dynamic variable @term{bindings} and
executes each @param{form} using those @term{bindings}.
Each @param{form} is evaluated in  order.

@symbolref{progv, SYM} allows @term{binding} one or more dynamic
variables whose names may be determined at run time.
Each @param{form} is evaluated in order
with the dynamic variables whose names are in
@param{symbols} bound to corresponding @param{values}.
If too few @param{values}
are supplied, the remaining @term{symbols} are bound and then
made to have no value. If too many @param{values} are
supplied, the excess values are ignored.
The @term{bindings} of the dynamic variables are undone on
exit from @symbolref{progv, SYM}.

@subsubheading Examples:
@lisp
 (setq *x* 1) @EV{} 1
 (progv '(*x*) '(2) *x*) @EV{} 2
 *x* @EV{} 1

Assuming *x* is not globally special,

 (let ((*x* 3))
    (progv '(*x*) '(4)
      (list *x* (symbol-value '*x*)))) @EV{} (3 4)
@end lisp


@subsubheading See Also:

@ref{Evaluation}

@subsubheading Notes:

Among other things, @symbolref{progv, SYM} is useful when writing
interpreters for languages embedded in @Lisp{}; it provides a handle
on the mechanism for @term{binding} @term{dynamic variables}.


@node setq
@syindexanchor{setq, SYM}
@subsection setq (Special Form)
@cindex setq


@subsubheading Syntax:

@DefspecWithValues{setq, @stardown{pair}, result}

@auxbnf{pair, var form}

@subsubheading Pronunciation:

@pronounced{@Stress{set}@stress{ky@uumlaut{}}}

@subsubheading Arguments and Values:

@param{var}---a @term{symbol} naming a @term{variable} other than a @term{constant variable}.

@param{form}---a @term{form}.

@param{result}---the @term{primary value} of the last @param{form},
or @nil{}@spc{}if no @param{pairs} were supplied.

@subsubheading Description:

Assigns values to @term{variables}.

@f{(setq @i{var1} @i{form1} @i{var2} @i{form2} ...)}
is the simple variable assignment statement of @Lisp{}.
First @param{form1} is evaluated
and the result is stored in the variable @param{var1}, then @param{form2}
is evaluated and the result stored in @param{var2}, and so forth.
@symbolref{setq, SYM} may be used for assignment of both lexical
and dynamic variables.

If any @param{var} refers to a @term{binding}
made by @symbolref{symbol-macrolet, SYM},
then that @param{var} is treated as if @symbolref{setf, SYM}
(not @symbolref{setq, SYM}) had been used.

@subsubheading Examples:

@lisp
 ;; A simple use of SETQ to establish values for variables.
 (setq a 1 b 2 c 3) @EV{} 3
 a @EV{} 1
 b @EV{} 2
 c @EV{} 3

 ;; Use of SETQ to update values by sequential assignment.
 (setq a (1+ b) b (1+ a) c (+ a b)) @EV{} 7
 a @EV{} 3
 b @EV{} 4
 c @EV{} 7

 ;; This illustrates the use of SETQ on a symbol macro.
 (let ((x (list 10 20 30)))
   (symbol-macrolet ((y (car x)) (z (cadr x)))
     (setq y (1+ z) z (1+ y))
     (list x y z)))
@EV{} ((21 22 30) 21 22)
@end lisp


@subsubheading Side Effects:

The @term{primary value} of each @param{form} is assigned to the corresponding @param{var}.

@subsubheading See Also:

@ref{psetq},
@ref{set},
@ref{setf}


@node psetq
@syindexanchor{psetq, SYM}
@subsection psetq (Macro)
@cindex psetq


@subsubheading Syntax:

@DefmacWithValues{psetq, @stardown{pair}, @nil{}}

@auxbnf{pair, var form}

@subsubheading Pronunciation:

@symbolref{psetq, SYM}: @pronounced{:p@harde{}@Stress{set}@stress{ky@uumlaut{}}}

@subsubheading Arguments and Values:

@param{var}---a @term{symbol} naming a @term{variable} other than a @term{constant variable}.

@param{form}---a @term{form}.

@subsubheading Description:

Assigns values to @term{variables}.

This is just like @symbolref{setq, SYM}, except that the assignments
happen ``in parallel.''  That is, first all of the forms are
evaluated, and only then are the variables set to the resulting values.
In this way, the assignment to one variable does not affect the value
computation of another in the way that would occur with @symbolref{setq, SYM}'s
sequential assignment.

If any @param{var} refers to a @term{binding}
made by @symbolref{symbol-macrolet, SYM},
then that @param{var} is treated as if @symbolref{psetf, SYM} (not @symbolref{psetq, SYM})
had been used.

@subsubheading Examples:

@lisp
 ;; A simple use of PSETQ to establish values for variables.
 ;; As a matter of style, many programmers would prefer SETQ
 ;; in a simple situation like this where parallel assignment
 ;; is not needed, but the two have equivalent effect.
 (psetq a 1 b 2 c 3) @EV{} NIL
 a @EV{} 1
 b @EV{} 2
 c @EV{} 3

 ;; Use of PSETQ to update values by parallel assignment.
 ;; The effect here is very different than if SETQ had been used.
 (psetq a (1+ b) b (1+ a) c (+ a b)) @EV{} NIL
 a @EV{} 3
 b @EV{} 2
 c @EV{} 3

 ;; Use of PSETQ on a symbol macro.
 (let ((x (list 10 20 30)))
   (symbol-macrolet ((y (car x)) (z (cadr x)))
     (psetq y (1+ z) z (1+ y))
     (list x y z)))
@EV{} ((21 11 30) 21 11)

 ;; Use of parallel assignment to swap values of A and B.
 (let ((a 1) (b 2))
   (psetq a b  b a)
   (values a b))
@EV{} 2, 1
@end lisp


@subsubheading Side Effects:

The values of @param{forms} are assigned to @param{vars}.

@subsubheading See Also:

@ref{psetf},
@ref{setq}


@node block
@syindexanchor{block, SYM}
@subsection block (Special Operator)
@cindex block


@subsubheading Syntax:

@DefspecWithValues{block, @param{name} @star{@param{form}}, @starparam{result}}

@subsubheading Arguments and Values:

@param{name}---a @term{symbol}.

@param{form}---a @term{form}.

@param{results}---the @term{values} of the @term{forms} if a @term{normal return} occurs,
or else, if an @term{explicit return} occurs, the @term{values} that were transferred.

@subsubheading Description:

@symbolref{block, SYM} @term{establishes} a @term{block} named @param{name}
and then evaluates @param{forms} as an @term{implicit progn}.

The @term{special operators} @symbolref{block, SYM} and @symbolref{return-from, SYM} work together to
provide a structured, lexical, non-local exit facility.  At any point lexically
contained within @term{forms}, @symbolref{return-from, SYM} can be used with the
given @param{name} to return control and values from the @symbolref{block, SYM}
@term{form}, except when an intervening @term{block} with the same name
has been @term{established}, in which case the outer @term{block} is
shadowed by the inner one.

The @term{block} named @term{name} has
@term{lexical scope} and @term{dynamic extent}.

Once established, a @term{block} may only be exited once,
whether by @term{normal return} or @term{explicit return}.

@subsubheading Examples:

@lisp
 (block empty) @EV{} NIL
 (block whocares (values 1 2) (values 3 4)) @EV{} 3, 4
 (let ((x 1))
   (block stop (setq x 2) (return-from stop) (setq x 3))
   x) @EV{} 2
 (block early (return-from early (values 1 2)) (values 3 4)) @EV{} 1, 2
 (block outer (block inner (return-from outer 1)) 2) @EV{} 1
 (block twin (block twin (return-from twin 1)) 2) @EV{} 2
 ;; Contrast behavior of this example with corresponding example of CATCH.
 (block b
   (flet ((b1 () (return-from b 1)))
     (block b (b1) (print 'unreachable))
     2)) @EV{} 1
@end lisp


@subsubheading See Also:

@ref{return}, @ref{Evaluation}

@subsubheading Notes:


@node catch
@syindexanchor{catch, SYM}
@subsection catch (Special Operator)
@cindex catch


@subsubheading Syntax:

@DefspecWithValues{catch, @param{tag} @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{tag}---a @term{catch tag}; @eval{}.

@param{forms}---an @term{implicit progn}.

@param{results}---if the @param{forms} exit normally,
the @term{values} returned by the @param{forms};
if a throw occurs to the @param{tag},
the @term{values} that are thrown.

@subsubheading Description:

@symbolref{catch, SYM} is used as the destination of a non-local
control transfer by @symbolref{throw, SYM}.
@param{Tags} are used to find the @symbolref{catch, SYM}
to which a @symbolref{throw, SYM} is transferring control.
@f{(catch 'foo @i{form})} catches a
@f{(throw 'foo @i{form})} but not a
@f{(throw 'bar @i{form})}.

The order of execution of @symbolref{catch, SYM} follows:
@cindex order of evaluation
@cindex evaluation order


@enumerate 1
@item @param{Tag} is evaluated.
It serves as the name of the
@symbolref{catch, SYM}.

@item @param{Forms} are then evaluated as an implicit @symbolref{progn, SYM},
and the results of the last @param{form} are returned unless a
@symbolref{throw, SYM} occurs.

@item If a @symbolref{throw, SYM} occurs
during the execution of one of the @param{forms}, control
is transferred  to the @symbolref{catch, SYM} @term{form} whose @param{tag}
is @symbolref{eq, SYM} to
the tag argument of the @symbolref{throw, SYM}
and which is the most recently established @symbolref{catch, SYM} with that
@param{tag}.
No further evaluation of @param{forms} occurs.

@item The @param{tag} @term{established}
by @symbolref{catch, SYM} is @term{disestablished}
just before the results are returned.
@end enumerate


If during the execution of one of the @param{forms}, a @symbolref{throw, SYM}
is executed whose tag is @symbolref{eq, SYM} to the @symbolref{catch, SYM} tag,
then the values specified by the @symbolref{throw, SYM} are
returned as the result of the dynamically most recently established
@symbolref{catch, SYM} form with that tag.

The mechanism for @symbolref{catch, SYM} and @symbolref{throw, SYM} works even
if @symbolref{throw, SYM} is not within the lexical scope of @symbolref{catch, SYM}.
@symbolref{throw, SYM} must occur within the @term{dynamic extent}
of the @term{evaluation} of the body of a @symbolref{catch, SYM} with a corresponding @param{tag}.

@subsubheading Examples:
@lisp
 (catch 'dummy-tag 1 2 (throw 'dummy-tag 3) 4) @EV{} 3
 (catch 'dummy-tag 1 2 3 4) @EV{} 4
 (defun throw-back (tag) (throw tag t)) @EV{} THROW-BACK
 (catch 'dummy-tag (throw-back 'dummy-tag) 2) @EV{} T

 ;; Contrast behavior of this example with corresponding example of BLOCK.
 (catch 'c
   (flet ((c1 () (throw 'c 1)))
     (catch 'c (c1) (print 'unreachable))
     2)) @EV{} 2
@end lisp


@subsubheading Exceptional Situations:
An error @oftype{control-error} is signaled
if @symbolref{throw, SYM} is done
when there is no suitable @symbolref{catch, SYM} @param{tag}.
@subsubheading See Also:

@ref{throw}, @ref{Evaluation}

@subsubheading Notes:

It is customary for @term{symbols} to be used
as @param{tags}, but any @term{object} is permitted.
However, numbers should not be
used because the comparison is done using @symbolref{eq, SYM}.

@symbolref{catch, SYM} differs from @symbolref{block, SYM} in that
@symbolref{catch, SYM}
tags have dynamic @term{scope} while
@symbolref{block, SYM} names have @term{lexical scope}.


@node go
@syindexanchor{go, SYM}
@subsection go (Special Operator)
@cindex go


@subsubheading Syntax:

@DefspecNoReturn{go, tag}

@subsubheading Arguments and Values:

@param{tag}---a @term{go tag}.

@subsubheading Description:

@symbolref{go, SYM} transfers control to the point in the body
of an enclosing @symbolref{tagbody, SYM} form labeled by a
tag @symbolref{eql, F} to @param{tag}.
If there is no such @param{tag}  in the body, the
bodies of lexically containing @symbolref{tagbody, SYM} @term{forms}
(if any) are examined as well.
If several tags are @symbolref{eql, F}
to @param{tag}, control is transferred to
whichever matching @param{tag}
is contained in the innermost @symbolref{tagbody, SYM} form that
contains the @symbolref{go, SYM}.
The consequences are undefined
if there is no matching @param{tag} lexically visible
to the point of the @symbolref{go, SYM}.

The transfer of control initiated by @symbolref{go, SYM} is performed
as described in @ref{Transfer of Control to an Exit Point}.

@subsubheading Examples:
@lisp
 (tagbody
   (setq val 2)
   (go lp)
   (incf val 3)
   lp (incf val 4)) @EV{} NIL
 val @EV{} 6
@end lisp



The following is in error because there is a normal exit
of the @symbolref{tagbody, SYM} before the
@symbolref{go, SYM} is executed.

@lisp
 (let ((a nil))
   (tagbody t (setq a #'(lambda () (go t))))
   (funcall a))
@end lisp


The following is in error because the @symbolref{tagbody, SYM} is passed over
before the @symbolref{go, SYM} @term{form} is executed.

@lisp
 (funcall (block nil
            (tagbody a (return #'(lambda () (go a))))))
@end lisp


@subsubheading See Also:

@ref{tagbody}


@node return-from
@syindexanchor{return-from, SYM}
@subsection return-from (Special Operator)
@cindex return-from


@subsubheading Syntax:

@DefspecNoReturn{return-from, @param{name} @brac{@param{result}}}

@subsubheading Arguments and Values:

@param{name}---a @term{block tag}; @noeval{}.

@param{result}---a @term{form}; @eval{}.
@Default{@nil{}}

@subsubheading Description:

Returns control and @term{multiple values}@sub{2} from a lexically enclosing @term{block}.

A @symbolref{block, SYM} @term{form} named @param{name} must lexically enclose
the occurrence of @symbolref{return-from, SYM};  any @term{values} @term{yielded}
by the @term{evaluation} of @param{result} are immediately returned from
the innermost such lexically enclosing @term{block}.

The transfer of control initiated by @symbolref{return-from, SYM} is performed
as described in @ref{Transfer of Control to an Exit Point}.

@subsubheading Examples:

@lisp
 (block alpha (return-from alpha) 1) @EV{} NIL
 (block alpha (return-from alpha 1) 2) @EV{} 1
 (block alpha (return-from alpha (values 1 2)) 3) @EV{} 1, 2
 (let ((a 0))
    (dotimes (i 10) (incf a) (when (oddp i) (return)))
    a) @EV{} 2
 (defun temp (x)
    (if x (return-from temp 'dummy))
    44) @EV{} TEMP
 (temp nil) @EV{} 44
 (temp t) @EV{} DUMMY
 (block out
   (flet ((exit (n) (return-from out n)))
     (block out (exit 1)))
   2) @EV{} 1
 (block nil
   (unwind-protect (return-from nil 1)
     (return-from nil 2)))
@EV{} 2
 (dolist (flag '(nil t))
   (block nil
     (let ((x 5))
       (declare (special x))
       (unwind-protect (return-from nil)
         (print x))))
   (print 'here))
@OUT{} 5
@OUT{} HERE
@OUT{} 5
@OUT{} HERE
@EV{} NIL
 (dolist (flag '(nil t))
   (block nil
     (let ((x 5))
       (declare (special x))
       (unwind-protect
           (if flag (return-from nil))
         (print x))))
   (print 'here))
@OUT{} 5
@OUT{} HERE
@OUT{} 5
@OUT{} HERE
@EV{} NIL
@end lisp


The following has undefined consequences because the @symbolref{block, SYM} @term{form}
exits normally before the @symbolref{return-from, SYM} @term{form} is attempted.

@lisp
 (funcall (block nil #'(lambda () (return-from nil)))) is an error.
@end lisp



@subsubheading See Also:

@ref{block},
@ref{return},
@ref{Evaluation}


@node return
@syindexanchor{return, SYM}
@subsection return (Macro)
@cindex return


@subsubheading Syntax:

@DefmacNoReturn{return, @brac{@param{result}}}

@subsubheading Arguments and Values:

@param{result}---a @term{form}; @eval{}.
@Default{@nil{}}

@subsubheading Description:

Returns, as if by @symbolref{return-from, SYM}, from the @term{block} named @nil{}.

@subsubheading Examples:

@lisp
 (block nil (return) 1) @EV{} NIL
 (block nil (return 1) 2) @EV{} 1
 (block nil (return (values 1 2)) 3) @EV{} 1, 2
 (block nil (block alpha (return 1) 2)) @EV{} 1
 (block alpha (block nil (return 1)) 2) @EV{} 2
 (block nil (block nil (return 1) 2)) @EV{} 1
@end lisp


@subsubheading See Also:

@ref{block},
@ref{return-from},
@ref{Evaluation}

@subsubheading Notes:

@lisp
 (return) @EQ{} (return-from nil)
 (return @param{form}) @EQ{} (return-from nil @param{form})
@end lisp


The @term{implicit blocks} @term{established} by @term{macros} such as @symbolref{do, SYM}
are often named @nil{}, so that @symbolref{return, SYM} can be used to exit from
such @term{forms}.


@node tagbody
@syindexanchor{tagbody, SYM}
@subsection tagbody (Special Operator)
@cindex tagbody


@subsubheading Syntax:

@DefspecWithValues{tagbody, @star{@curly{@param{tag} | @param{statement}}}, @nil{}}

@subsubheading Arguments and Values:

@param{tag}---a @term{go tag}; @noeval{}.

@param{statement}---a @term{compound form}; @evalspecial{}.

@subsubheading Description:

Executes zero or more @i{statements} in a
@term{lexical environment}
that provides for control transfers to labels indicated by the @param{tags}.

The @param{statements} in a @symbolref{tagbody, SYM} are @term{evaluated} in order
from left to right, and their @term{values} are discarded.  If at any time
there are no remaining @param{statements}, @symbolref{tagbody, SYM} returns @nil{}.
However, if @f{(go @param{tag})} is @term{evaluated}, control jumps to the
part of the body labeled with the @param{tag}.  (Tags are compared with @symbolref{eql, F}.)

A @param{tag} established by @symbolref{tagbody, SYM} has @term{lexical scope}
and has @term{dynamic extent}.  Once @symbolref{tagbody, SYM} has been exited,
it is no longer valid to @symbolref{go, SYM} to a @param{tag} in its body.
It is permissible for @symbolref{go, SYM} to jump to a @symbolref{tagbody, SYM} that is
not the innermost @symbolref{tagbody, SYM} containing that @symbolref{go, SYM};
the @param{tags} established by a @symbolref{tagbody, SYM} only shadow
other @param{tags} of like name.

The determination of which elements of the body are @param{tags}
and which are @param{statements} is made prior to any @term{macro expansion}
of that element.  If a @param{statement} is a @term{macro form} and
its @term{macro expansion} is an @term{atom}, that @term{atom} is treated
as a @param{statement}, not a @param{tag}.

@subsubheading Examples:

@lisp
 (let (val)
    (tagbody
      (setq val 1)
      (go point-a)
      (incf val 16)
     point-c
      (incf val 04)
      (go point-b)
      (incf val 32)
     point-a
      (incf val 02)
      (go point-c)
      (incf val 64)
     point-b
      (incf val 08))
    val)
@EV{} 15
 (defun f1 (flag)
   (let ((n 1))
     (tagbody
       (setq n (f2 flag #'(lambda () (go out))))
      out
       (prin1 n))))
@EV{} F1
 (defun f2 (flag escape)
   (if flag (funcall escape) 2))
@EV{} F2
 (f1 nil)
@OUT{} 2
@EV{} NIL
 (f1 t)
@OUT{} 1
@EV{} NIL
@end lisp


@subsubheading See Also:

@ref{go}

@subsubheading Notes:

The @term{macros} in @thenextfigure{}@spc{}have @i{implicit tagbodies}.


@float Figure,fig5.10
@cartouche
@multitable{do-all-symbols}{do-external-symbols}{dotimes}

@item do @tab do-external-symbols @tab dotimes
@item do* @tab do-symbols @tab prog
@item do-all-symbols @tab dolist @tab prog*
@end multitable
@end cartouche
@caption{Macros that have implicit tagbodies.}
@end float



@node throw
@syindexanchor{throw, SYM}
@subsection throw (Special Operator)
@cindex throw


@subsubheading Syntax:

@DefspecNoReturn{throw, tag result-form}

@subsubheading Arguments and Values:

@param{tag}---a @term{catch tag}; @eval{}.

@param{result-form}---a @term{form}; @evalspecial{}.

@subsubheading Description:

@symbolref{throw, SYM} causes a non-local control transfer
to a @symbolref{catch, SYM} whose tag is @symbolref{eq, SYM} to @param{tag}.

@param{Tag} is evaluated first to produce an @term{object}
called the throw tag; then @param{result-form} is evaluated,
and its results are saved. If the @param{result-form} produces
multiple values, then all the values are saved.
The most recent outstanding @symbolref{catch, SYM}
whose @param{tag} is @symbolref{eq, SYM} to the throw tag
is exited; the saved results are returned as the value or
values of @symbolref{catch, SYM}.

The transfer of control initiated by @symbolref{throw, SYM} is performed
as described in @ref{Transfer of Control to an Exit Point}.

@subsubheading Examples:

@lisp
 (catch 'result
    (setq i 0 j 0)
    (loop (incf j 3) (incf i)
          (if (= i 3) (throw 'result (values i j))))) @EV{} 3, 9

@end lisp


@lisp
 (catch nil
   (unwind-protect (throw nil 1)
     (throw nil 2))) @EV{} 2
@end lisp


The consequences of the following are undefined
because the @symbolref{catch, SYM} of @f{b}
is passed over by the first @symbolref{throw, SYM},
hence portable programs must assume that
its @term{dynamic extent} is terminated.
The @term{binding} of the @term{catch tag} is not yet @term{disestablished}
and therefore it is the target of the second @symbolref{throw, SYM}.

@lisp
 (catch 'a
   (catch 'b
     (unwind-protect (throw 'a 1)
       (throw 'b 2))))
@end lisp


The following prints ``@f{The inner catch returns :SECOND-THROW}''
and then returns @f{:outer-catch}.

@lisp
 (catch 'foo
         (format t "The inner catch returns ~s.~%"
                 (catch 'foo
                     (unwind-protect (throw 'foo :first-throw)
                         (throw 'foo :second-throw))))
         :outer-catch)
@OUT{} The inner catch returns :SECOND-THROW
@EV{} :OUTER-CATCH
@end lisp



@subsubheading Exceptional Situations:

If there is no outstanding @term{catch tag} that matches the throw tag,
no unwinding of the stack is performed,
and an error @oftype{control-error} is signaled.
When the error is signaled,
the @term{dynamic environment} is that which was
in force at the point of the @symbolref{throw, SYM}.

@subsubheading See Also:

@ref{block},
@ref{catch},
@ref{return-from},
@ref{unwind-protect},
@ref{Evaluation}

@subsubheading Notes:

@symbolref{catch, SYM} and @symbolref{throw, SYM} are normally used when the @term{exit point}
must have @term{dynamic scope} (@eg{} the @symbolref{throw, SYM} is not lexically enclosed
by the @symbolref{catch, SYM}), while @symbolref{block, SYM} and @symbolref{return, SYM} are used
when @term{lexical scope} is sufficient.


@node unwind-protect
@syindexanchor{unwind-protect, SYM}
@subsection unwind-protect (Special Operator)
@cindex unwind-protect


@subsubheading Syntax:

@DefspecWithValues{unwind-protect, @param{protected-form} @starparam{cleanup-form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{protected-form}---a @term{form}.

@param{cleanup-form}---a @term{form}.

@param{results}---the @term{values} of the @i{protected-form}.

@subsubheading Description:
@symbolref{unwind-protect, SYM} evaluates @param{protected-form}
and guarantees that @param{cleanup-forms} are executed
before @symbolref{unwind-protect, SYM} exits,
whether it terminates
normally or is aborted by a control transfer of some kind.
@symbolref{unwind-protect, SYM} is intended to be used
to make sure that
certain side effects take place after the evaluation of
@param{protected-form}.

If a @term{non-local exit} occurs during execution of @param{cleanup-forms},
no special action is taken.  The @param{cleanup-forms} of
@symbolref{unwind-protect, SYM}
are not protected by that @symbolref{unwind-protect, SYM}.

@symbolref{unwind-protect, SYM} protects against all attempts to exit
from @param{protected-form}, including
@symbolref{go, SYM},
@symbolref{handler-case, SYM},
@symbolref{ignore-errors, SYM},
@symbolref{restart-case, SYM},
@symbolref{return-from, SYM},
@symbolref{throw, SYM},
and @symbolref{with-simple-restart, SYM}.

Undoing of @term{handler} and @term{restart} @term{bindings} during an exit
happens in parallel with the undoing of the bindings of @term{dynamic variables}
and @symbolref{catch, SYM} tags, in the reverse order in which they were established.
The effect of this is that @param{cleanup-form} sees the same @term{handler}
and @term{restart} @term{bindings}, as well as @term{dynamic variable} @term{bindings}
and @symbolref{catch, SYM} tags, as were visible when the @symbolref{unwind-protect, SYM} was entered.

@subsubheading Examples:
@lisp
 (tagbody
   (let ((x 3))
     (unwind-protect
       (if (numberp x) (go out))
       (print x)))
  out
   ...)
@end lisp

When @symbolref{go, SYM} is executed, the call to @symbolref{print, SYM} is executed first,
and then the transfer of control to the tag @f{out} is completed.

@lisp
 (defun dummy-function (x)
    (setq state 'running)
    (unless (numberp x) (throw 'abort 'not-a-number))
    (setq state (1+ x))) @EV{} DUMMY-FUNCTION
 (catch 'abort (dummy-function 1)) @EV{} 2
 state @EV{} 2
 (catch 'abort (dummy-function 'trash)) @EV{} NOT-A-NUMBER
 state @EV{} RUNNING
 (catch 'abort (unwind-protect (dummy-function 'trash)
                  (setq state 'aborted))) @EV{} NOT-A-NUMBER
 state @EV{} ABORTED
@end lisp


The following code
is not correct:

@lisp
 (unwind-protect
   (progn (incf *access-count*)
          (perform-access))
   (decf *access-count*))
@end lisp

If an exit occurs before completion of @symbolref{incf, SYM},
the @symbolref{decf, SYM} @term{form} is executed anyway, resulting in an
incorrect value for @f{*access-count*}.
The correct way to code this is as follows:

@lisp
 (let ((old-count *access-count*))
   (unwind-protect
     (progn (incf *access-count*)
            (perform-access))
     (setq *access-count* old-count)))
@end lisp



@lisp
;;; The following returns 2.
 (block nil
   (unwind-protect (return 1)
     (return 2)))

;;; The following has undefined consequences.
 (block a
   (block b
     (unwind-protect (return-from a 1)
       (return-from b 2))))

;;; The following returns 2.
 (catch nil
   (unwind-protect (throw nil 1)
     (throw nil 2)))

;;; The following has undefined consequences because the catch of B is
;;; passed over by the first THROW, hence portable programs must assume
;;; its dynamic extent is terminated.  The binding of the catch tag is not
;;; yet disestablished and therefore it is the target of the second throw.
 (catch 'a
   (catch 'b
     (unwind-protect (throw 'a 1)
       (throw 'b 2))))

;;; The following prints "The inner catch returns :SECOND-THROW"
;;; and then returns :OUTER-CATCH.
 (catch 'foo
         (format t "The inner catch returns ~s.~%"
                 (catch 'foo
                     (unwind-protect (throw 'foo :first-throw)
                         (throw 'foo :second-throw))))
         :outer-catch)


;;; The following returns 10. The inner CATCH of A is passed over, but
;;; because that CATCH is disestablished before the THROW to A is executed,
;;; it isn't seen.
 (catch 'a
   (catch 'b
     (unwind-protect (1+ (catch 'a (throw 'b 1)))
       (throw 'a 10))))


;;; The following has undefined consequences because the extent of
;;; the (CATCH 'BAR ...) exit ends when the (THROW 'FOO ...)
;;; commences.
 (catch 'foo
   (catch 'bar
       (unwind-protect (throw 'foo 3)
         (throw 'bar 4)
         (print 'xxx))))


;;; The following returns 4; XXX is not printed.
;;; The (THROW 'FOO ...) has no effect on the scope of the BAR
;;; catch tag or the extent of the (CATCH 'BAR ...) exit.
 (catch 'bar
   (catch 'foo
       (unwind-protect (throw 'foo 3)
         (throw 'bar 4)
         (print 'xxx))))


;;; The following prints 5.
 (block nil
   (let ((x 5))
     (declare (special x))
     (unwind-protect (return)
       (print x))))
@end lisp


@subsubheading See Also:

@ref{catch},
@ref{go},
@ref{handler-case},
@ref{restart-case},
@ref{return},
@ref{return-from},
@ref{throw},
@ref{Evaluation}


@node nil (Constant Variable)
@syindexanchor{nil, CV}
@subsection nil (Constant Variable)
@cindex nil


@subsubheading Constant Value:

@nil{}.

@subsubheading Description:

@nil{}@spc{}represents both @term{boolean} (and @term{generalized boolean}) @term{false}
and the @term{empty list}.

@subsubheading Examples:
@lisp
 nil @EV{} NIL
@end lisp


@subsubheading See Also:

@ref{t (Constant Variable)}


@node not (Function)
@syindexanchor{not, F}
@subsection not (Function)
@cindex not



@subsubheading Syntax:

@DefunWithValues{not, x, boolean}

@subsubheading Arguments and Values:

@param{x}---a @term{generalized boolean} (@ie{} any @term{object}).

@param{boolean}---a @term{boolean}.

@subsubheading Description:

@StrictPredicate{x, @term{false}}

@subsubheading Examples:

@lisp
 (not nil) @EV{} T
 (not '()) @EV{} T
 (not (integerp 'sss)) @EV{} T
 (not (integerp 1)) @EV{} NIL
 (not 3.7) @EV{} NIL
 (not 'apple) @EV{} NIL
@end lisp



@subsubheading See Also:

@ref{null (Function)}

@subsubheading Notes:

@symbolref{not, F} is intended to be used to invert the `truth value' of a @term{boolean}
(or @term{generalized boolean})
whereas @symbolref{null, F} is intended to be used to test for the @term{empty list}.
Operationally, @symbolref{not, F} and @symbolref{null, F} compute the same result;
which to use is a matter of style.


@node t (Constant Variable)
@syindexanchor{t, CV}
@subsection t (Constant Variable)
@cindex t


@subsubheading Constant Value:

@t{t}.

@subsubheading Description:

The @term{boolean} representing true,
and the canonical @term{generalized boolean} representing true.
Although any @term{object}
other than @nil{}@spc{}is considered @term{true},
@symbolref{t, SC}@spc{}is generally used when there is no special reason
to prefer one such @term{object} over another.

The @term{symbol} @symbolref{t, SC}@spc{}is also sometimes used for other purposes as well.
For example,
as the @term{name} of a @term{class},
as a @term{designator} (@eg{} a @term{stream designator})
or as a special symbol for some syntactic reason
(@eg{} in @symbolref{case, SYM} and @symbolref{typecase, SYM} to label the @param{otherwise-clause}).

@subsubheading Examples:

@lisp
 t @EV{} T
 (eq t 't) @EV{} @term{true}
 (find-class 't) @EV{} #<CLASS T 610703333>
 (case 'a (a 1) (t 2)) @EV{} 1
 (case 'b (a 1) (t 2)) @EV{} 2
 (prin1 'hello t)
@OUT{} HELLO
@EV{} HELLO
@end lisp


@subsubheading See Also:

@ref{nil (Constant Variable)}


@node eq
@syindexanchor{eq, SYM}
@subsection eq (Function)
@cindex eq


@subsubheading Syntax:

@DefunWithValues{eq, x y, generalized-boolean}

@subsubheading Arguments and Values:

@param{x}---an @term{object}.

@param{y}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

Returns @term{true} if its @term{arguments} are the same, identical @term{object};
otherwise, returns @term{false}.

@subsubheading Examples:
@lisp
 (eq 'a 'b) @EV{} @term{false}
 (eq 'a 'a) @EV{} @term{true}
 (eq 3 3)
@EV{} @term{true}
@OV{} @term{false}
 (eq 3 3.0) @EV{} @term{false}
 (eq 3.0 3.0)
@EV{} @term{true}
@OV{} @term{false}
 (eq #c(3 -4) #c(3 -4))
@EV{} @term{true}
@OV{} @term{false}
 (eq #c(3 -4.0) #c(3 -4)) @EV{} @term{false}
 (eq (cons 'a 'b) (cons 'a 'c)) @EV{} @term{false}
 (eq (cons 'a 'b) (cons 'a 'b)) @EV{} @term{false}
 (eq '(a . b) '(a . b))
@EV{} @term{true}
@OV{} @term{false}
 (progn (setq x (cons 'a 'b)) (eq x x)) @EV{} @term{true}
 (progn (setq x '(a . b)) (eq x x)) @EV{} @term{true}
 (eq #@bsl{}A #@bsl{}A)
@EV{} @term{true}
@OV{} @term{false}
 (let ((x "Foo")) (eq x x)) @EV{} @term{true}
 (eq "Foo" "Foo")
@EV{} @term{true}
@OV{} @term{false}
 (eq "Foo" (copy-seq "Foo")) @EV{} @term{false}
 (eq "FOO" "foo") @EV{} @term{false}
 (eq "string-seq" (copy-seq "string-seq")) @EV{} @term{false}
 (let ((x 5)) (eq x x))
@EV{} @term{true}
@OV{} @term{false}
@end lisp


@subsubheading See Also:

@ref{eql (Function)},
@ref{equal},
@ref{equalp},
@ref{=},
@ref{Compilation}

@subsubheading Notes:
@term{Objects} that appear the same when printed are not necessarily
@symbolref{eq, SYM} to each other.  @term{Symbols} that print the same
usually are @symbolref{eq, SYM} to each other because of the use of the
@symbolref{intern, SYM} function.  However, @term{numbers} with the
same value need not be @symbolref{eq, SYM}, and two similar
@term{lists} are usually not @term{identical}.

An implementation is permitted to make ``copies'' of
@term{characters} and @term{numbers} at any time.
The effect is that @clisp{}@spc{}makes no guarantee that @symbolref{eq, SYM}
is true even when both its arguments are ``the same thing'' if
that thing is a @term{character} or @term{number}.

Most @clisp{}@spc{}@term{operators} use @symbolref{eql, F} rather than
@symbolref{eq, SYM} to compare objects, or else they default to @symbolref{eql, F}
and only use @symbolref{eq, SYM} if specifically requested to do so.
However, the following @term{operators} are defined to use @symbolref{eq, SYM}
rather than @symbolref{eql, F} in a way that cannot be overridden by the
@term{code} which employs them:


@float Figure,fig5.11
@cartouche
@multitable{get-properties}{remprop}{throw}

@item catch @tab getf @tab throw
@item get @tab remf @tab
@item get-properties @tab remprop @tab
@end multitable
@end cartouche
@caption{Operators that always prefer EQ over EQL}
@end float



@node eql (Function)
@syindexanchor{eql, F}
@subsection eql (Function)
@cindex eql


@subsubheading Syntax:

@DefunWithValues{eql, x y, generalized-boolean}

@subsubheading Arguments and Values:

@param{x}---an @term{object}.

@param{y}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

The value of @symbolref{eql, F} is @term{true} of two objects, @param{x} and
@param{y}, in the folowing cases:

@enumerate 1
@item If @param{x} and @param{y} are @symbolref{eq, SYM}.
@item If @param{x} and @param{y} are both @term{numbers}
of the same @term{type} and the same value.
@item If they are both @term{characters} that represent the
same character.
@end enumerate


Otherwise the value of @symbolref{eql, F} is @term{false}.

If an implementation supports positive and negative zeros as @term{distinct} values,
then @f{(eql 0.0 -0.0)} returns @term{false}.
Otherwise, when the syntax @f{-0.0} is read it is interpreted as the value @f{0.0},
and so @f{(eql 0.0 -0.0)} returns @term{true}.

@subsubheading Examples:

@lisp
 (eql 'a 'b) @EV{} @term{false}
 (eql 'a 'a) @EV{} @term{true}
 (eql 3 3) @EV{} @term{true}
 (eql 3 3.0) @EV{} @term{false}
 (eql 3.0 3.0) @EV{} @term{true}
 (eql #c(3 -4) #c(3 -4)) @EV{} @term{true}
 (eql #c(3 -4.0) #c(3 -4)) @EV{} @term{false}
 (eql (cons 'a 'b) (cons 'a 'c)) @EV{} @term{false}
 (eql (cons 'a 'b) (cons 'a 'b)) @EV{} @term{false}
 (eql '(a . b) '(a . b))
@EV{} @term{true}
@OV{} @term{false}
 (progn (setq x (cons 'a 'b)) (eql x x)) @EV{} @term{true}
 (progn (setq x '(a . b)) (eql x x)) @EV{} @term{true}
 (eql #@bsl{}A #@bsl{}A) @EV{} @term{true}
 (eql "Foo" "Foo")
@EV{} @term{true}
@OV{} @term{false}
 (eql "Foo" (copy-seq "Foo")) @EV{} @term{false}
 (eql "FOO" "foo") @EV{} @term{false}
@end lisp


Normally @f{(eql 1.0s0 1.0d0)} is false, under the assumption
that @f{1.0s0} and @f{1.0d0} are of distinct data types.
However, implementations that do not provide four distinct floating-point
formats are permitted to ``collapse'' the four formats into some
smaller number of them; in such an implementation @f{(eql 1.0s0 1.0d0)}
might be true.

@subsubheading See Also:

@ref{eq},
@ref{equal},
@ref{equalp},
@ref{=},
@ref{char=}

@subsubheading Notes:

@symbolref{eql, F} is the same as @symbolref{eq, SYM}, except that if the
arguments are @term{characters} or @term{numbers}
of the same type then their
values are compared.  Thus @symbolref{eql, F} tells whether two @term{objects}
are conceptually the same, whereas @symbolref{eq, SYM} tells whether two
@term{objects} are implementationally identical.  It is for this reason
that @symbolref{eql, F}, not @symbolref{eq, SYM}, is the default comparison predicate
for @term{operators} that take @term{sequences}
as arguments.

@symbolref{eql, F} may not be true of two @term{floats}
even when they represent the same
value.  @symbolref{=, SYM} is used to compare
mathematical values.

Two @term{complex} numbers are considered to be @symbolref{eql, F}
if their real parts are @symbolref{eql, F}
and their imaginary parts are @symbolref{eql, F}.
For example, @f{(eql #C(4 5) #C(4 5))} is @term{true} and
@f{(eql #C(4 5) #C(4.0 5.0))} is @term{false}.
Note that while @f{(eql #C(5.0 0.0) 5.0)} is @term{false},
@f{(eql #C(5 0) 5)} is @term{true}.
In the case of @f{(eql #C(5.0 0.0) 5.0)} the
two arguments are of different types,
and so cannot satisfy @symbolref{eql, F}.
In the case of @f{(eql #C(5 0) 5)},
@f{#C(5 0)} is not a @term{complex} number, but
is automatically reduced
to the @term{integer} @f{5}.


@node equal
@syindexanchor{equal, SYM}
@subsection equal (Function)
@cindex equal


@subsubheading Syntax:

@DefunWithValues{equal, x y, generalized-boolean}

@subsubheading Arguments and Values:

@param{x}---an @term{object}.

@param{y}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

Returns @term{true} if @param{x} and @param{y} are structurally similar
(isomorphic) @term{objects}.  @term{Objects} are treated as follows by
@symbolref{equal, SYM}.


@table @asis
@item @id{@term{Symbols}, @term{Numbers}, and @term{Characters}}


@symbolref{equal, SYM} is @term{true} of two @term{objects}
if they are @term{symbols} that are @symbolref{eq, SYM},
if they are @term{numbers} that are @symbolref{eql, F}, or
if they are @term{characters} that are @symbolref{eql, F}.

@item @id{@term{Conses}}


For @term{conses}, @symbolref{equal, SYM} is defined recursively as
the two @term{sequences} being @symbolref{equal, SYM}
and the two @term{sequences} being @symbolref{equal, SYM}.

@item @id{@term{Arrays}}


Two @term{arrays} are @symbolref{equal, SYM} only if they are @symbolref{eq, SYM},
with one exception:
@term{strings} and @term{bit vectors} are compared element-by-element (using @symbolref{eql, F}).
If either @param{x} or @param{y} has a @term{fill pointer}, the
@term{fill pointer} limits
the number of elements examined by @symbolref{equal, SYM}.
Uppercase and lowercase letters in @term{strings} are considered by
@symbolref{equal, SYM} to be different.

@item @id{@term{Pathnames}}


Two @term{pathnames} are @symbolref{equal, SYM} if and only if
all the corresponding components
(host, device, and so on) are
equivalent.  Whether or not
uppercase and lowercase letters are considered equivalent
in @term{strings} appearing in components is @term{implementation-dependent}.
@term{pathnames}
that are @symbolref{equal, SYM} should be functionally equivalent.

@item @id{@bf{Other (Structures, hash-tables, instances, @mat{@ldots{}})}}


Two other @term{objects} are @symbolref{equal, SYM} only if they are @symbolref{eq, SYM}.

@end table


@symbolref{equal, SYM} does not descend any @term{objects} other than the
ones explicitly specified above.
@Thenextfigure{}@spc{}summarizes the information given in the previous list.
In addition, the figure specifies the priority of the behavior of @symbolref{equal, SYM},
with upper
entries taking priority over lower ones.


@float Figure,fig5.12
@cartouche
@multitable{Other @term{object}}{``functionally equivalent''}
@headitem Type @tab Behavior
@item @term{number} @tab uses @symbolref{eql, F}
@item @term{character} @tab uses @symbolref{eql, F}
@item @term{cons} @tab descends
@item @term{bit vector} @tab descends
@item @term{string} @tab descends
@item @term{pathname} @tab ``functionally equivalent''
@item @term{structure} @tab uses @symbolref{eq, SYM}
@item Other @term{array} @tab uses @symbolref{eq, SYM}
@item @term{hash table} @tab uses @symbolref{eq, SYM}
@item Other @term{object} @tab uses @symbolref{eq, SYM}
@end multitable
@end cartouche
@caption{Summary and priorities of behavior of @symbolref{equal, SYM}}
@end float


Any two @term{objects} that are @symbolref{eql, F} are also @symbolref{equal, SYM}.

@symbolref{equal, SYM} may fail to terminate if @param{x} or @param{y} is circular.

@subsubheading Examples:

@lisp
 (equal 'a 'b) @EV{} @term{false}
 (equal 'a 'a) @EV{} @term{true}
 (equal 3 3) @EV{} @term{true}
 (equal 3 3.0) @EV{} @term{false}
 (equal 3.0 3.0) @EV{} @term{true}
 (equal #c(3 -4) #c(3 -4)) @EV{} @term{true}
 (equal #c(3 -4.0) #c(3 -4)) @EV{} @term{false}
 (equal (cons 'a 'b) (cons 'a 'c)) @EV{} @term{false}
 (equal (cons 'a 'b) (cons 'a 'b)) @EV{} @term{true}
 (equal #@bsl{}A #@bsl{}A) @EV{} @term{true}
 (equal #@bsl{}A #@bsl{}a) @EV{} @term{false}
 (equal "Foo" "Foo") @EV{} @term{true}
 (equal "Foo" (copy-seq "Foo")) @EV{} @term{true}
 (equal "FOO" "foo") @EV{} @term{false}
 (equal "This-string" "This-string") @EV{} @term{true}
 (equal "This-string" "this-string") @EV{} @term{false}
@end lisp


@subsubheading See Also:

@ref{eq}, @ref{eql (Function)}, @ref{equalp}, @ref{=},
@ref{string=}, @ref{string-equal}, @ref{char=},
@ref{char-equal}, @ref{tree-equal}

@subsubheading Notes:

@term{Object} equality is not a concept for which there is a uniquely
determined correct algorithm. The appropriateness of an equality
predicate can be judged only in the context of the needs of some
particular program. Although these functions take any type of
argument and their names sound very generic,
@symbolref{equal, SYM} and @symbolref{equalp, SYM} are
not appropriate for every application.

A rough rule of thumb is that two @term{objects} are @symbolref{equal, SYM}
if and only if their printed representations are the same.


@node equalp
@syindexanchor{equalp, SYM}
@subsection equalp (Function)
@cindex equalp


@subsubheading Syntax:

@DefunWithValues{equalp, x y, generalized-boolean}

@subsubheading Arguments and Values:

@param{x}---an @term{object}.

@param{y}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

Returns @term{true} if @param{x} and @param{y} are @symbolref{equal, SYM},
or if they have components that are of the same @term{type} as each other
and if those components are @symbolref{equalp, SYM};
specifically, @symbolref{equalp, SYM} returns @term{true} in the following cases:

@table @asis
@item @id{@term{Characters}}


If two @term{characters} are @symbolref{char-equal, SYM}.

@item @id{@term{Numbers}}


If two @term{numbers} are the @term{same} under @symbolref{=, SYM}.

@item @id{@term{Conses}}


If the two @term{cars} in the @term{conses} are @symbolref{equalp, SYM}
and the two @term{cdrs} in the @term{conses} are @symbolref{equalp, SYM}.

@item @id{@term{Arrays}}


If two @term{arrays} have the same
number of dimensions, the dimensions match,
and the corresponding
@term{active} @term{elements}
are @symbolref{equalp, SYM}.
The @term{types} for which the @term{arrays} are @term{specialized} need not match;
for example, a @term{string} and a general @term{array} that happens to contain the same
@term{characters} are @symbolref{equalp, SYM}.
Because @symbolref{equalp, SYM} performs @term{element}-by-@term{element} comparisons
of @term{strings} and ignores the @term{case} of @term{characters},
@term{case} distinctions are ignored when @symbolref{equalp, SYM} compares @term{strings}.

@item @id{@term{Structures}}


If two @term{structures} @mat{S@sub{1}} and @mat{S@sub{2}} have the same @term{class}
and the value of each @term{slot} in @mat{S@sub{1}} is the @term{same} under @symbolref{equalp, SYM}
as the value of the corresponding @term{slot} in @mat{S@sub{2}}.

@item @id{@term{Hash Tables}}


@symbolref{equalp, SYM} descends @i{hash-tables} by first comparing the count of entries
and the @kwd{test} function; if those are the same, it compares the
keys of the tables using the @kwd{test} function and then the values
of the matching keys using @symbolref{equalp, SYM} recursively.
@end table


@symbolref{equalp, SYM} does not descend any @term{objects}
other than the ones explicitly specified above.
@Thenextfigure{}@spc{}summarizes the information given in the previous list.
In addition, the figure specifies the priority of the behavior of @symbolref{equalp, SYM},
with upper
entries taking priority over lower ones.


@float Figure,fig5.13
@cartouche
@multitable{Other @term{object}}{descends, as described above}
@headitem Type @tab Behavior
@item @term{number} @tab uses @symbolref{=, SYM}
@item @term{character} @tab uses @symbolref{char-equal, SYM}
@item @term{cons} @tab descends
@item @term{bit vector} @tab descends
@item @term{string} @tab descends
@item @term{pathname} @tab same as @symbolref{equal, SYM}
@item @term{structure} @tab descends, as described above
@item Other @term{array} @tab descends
@item @term{hash table} @tab descends, as described above
@item Other @term{object} @tab uses @symbolref{eq, SYM}
@end multitable
@end cartouche
@caption{Summary and priorities of behavior of @symbolref{equalp, SYM}}
@end float


@subsubheading Examples:

@lisp
 (equalp 'a 'b) @EV{} @term{false}
 (equalp 'a 'a) @EV{} @term{true}
 (equalp 3 3) @EV{} @term{true}
 (equalp 3 3.0) @EV{} @term{true}
 (equalp 3.0 3.0) @EV{} @term{true}
 (equalp #c(3 -4) #c(3 -4)) @EV{} @term{true}
 (equalp #c(3 -4.0) #c(3 -4)) @EV{} @term{true}
 (equalp (cons 'a 'b) (cons 'a 'c)) @EV{} @term{false}
 (equalp (cons 'a 'b) (cons 'a 'b)) @EV{} @term{true}
 (equalp #@bsl{}A #@bsl{}A) @EV{} @term{true}
 (equalp #@bsl{}A #@bsl{}a) @EV{} @term{true}
 (equalp "Foo" "Foo") @EV{} @term{true}
 (equalp "Foo" (copy-seq "Foo")) @EV{} @term{true}
 (equalp "FOO" "foo") @EV{} @term{true}
@end lisp

@lisp
 (setq array1 (make-array 6 :element-type 'integer
                            :initial-contents '(1 1 1 3 5 7)))
@EV{} #(1 1 1 3 5 7)
 (setq array2 (make-array 8 :element-type 'integer
                            :initial-contents '(1 1 1 3 5 7 2 6)
                            :fill-pointer 6))
@EV{} #(1 1 1 3 5 7)
 (equalp array1 array2) @EV{} @term{true}
 (setq vector1 (vector 1 1 1 3 5 7)) @EV{} #(1 1 1 3 5 7)
 (equalp array1 vector1) @EV{} @term{true}
@end lisp


@subsubheading See Also:

@ref{eq}, @ref{eql (Function)}, @ref{equal}, @ref{=},
@ref{string=}, @ref{string-equal}, @ref{char=},
@ref{char-equal}

@subsubheading Notes:

@term{Object} equality is not a concept for which there is a uniquely
determined correct algorithm. The appropriateness of an equality
predicate can be judged only in the context of the needs of some
particular program. Although these functions take any type of
argument and their names sound very generic,
@symbolref{equal, SYM} and @symbolref{equalp, SYM} are
not appropriate for every application.


@node identity
@syindexanchor{identity, SYM}
@subsection identity (Function)
@cindex identity


@subsubheading Syntax:

@DefunWithValues{identity, object, object}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@subsubheading Description:

Returns its argument @param{object}.

@subsubheading Examples:

@lisp
 (identity 101) @EV{} 101
 (mapcan #'identity (list (list 1 2 3) '(4 5 6))) @EV{} (1 2 3 4 5 6)
@end lisp


@subsubheading Notes:

@symbolref{identity, SYM} is intended for use with functions that require
a @term{function} as an argument.

@f{(eql x (identity x))} returns @term{true} for all possible values of @param{x},
but @f{(eq x (identity x))} might return @term{false} when @param{x} is a @term{number}
or @term{character}.

@symbolref{identity, SYM} could be defined by

@lisp
(defun identity (x) x)
@end lisp



@node complement
@syindexanchor{complement, SYM}
@subsection complement (Function)
@cindex complement



@subsubheading Syntax:

@DefunWithValues{complement, function, complement-function}

@subsubheading Arguments and Values:

@param{function}---a @term{function}.

@param{complement-function}---a @term{function}.

@subsubheading Description:

Returns a @term{function} that
takes the same @term{arguments} as @param{function},
and has the same side-effect behavior as @param{function},
but returns only a single value:
a @term{generalized boolean} with the opposite truth value of that
which would be returned as the @term{primary value} of @param{function}.
That is, when the @param{function} would have returned
@term{true} as its @term{primary value}
the @param{complement-function} returns @term{false},
and when the @param{function} would have returned
@term{false} as its @term{primary value}
the @param{complement-function} returns @term{true}.

@subsubheading Examples:

@lisp
 (funcall (complement #'zerop) 1) @EV{} @term{true}
 (funcall (complement #'characterp) #@bsl{}A) @EV{} @term{false}
 (funcall (complement #'member) 'a '(a b c)) @EV{} @term{false}
 (funcall (complement #'member) 'd '(a b c)) @EV{} @term{true}
@end lisp


@subsubheading See Also:

@ref{not (Function)}

@subsubheading Notes:

@lisp
 (complement @i{x}) @EQ{} #'(lambda (&rest arguments) (not (apply @i{x} arguments)))
@end lisp


In @clisp{}, functions with names like ``@f{@i{xxx}-if-not}''
are related to functions with names like ``@f{@it{xxx}-if}''
in that

@lisp
(@i{xxx}-if-not @i{f} . @i{arguments}) @EQ{} (@i{xxx}-if (complement @i{f}) . @i{arguments})
@end lisp


For example,

@lisp
 (find-if-not #'zerop '(0 0 3)) @EQ{}
 (find-if (complement #'zerop) '(0 0 3)) @EV{} 3
@end lisp


Note that since the ``@f{@i{xxx}-if-not}'' @term{functions}
and the @kwd{test-not} arguments have been deprecated,
uses of ``@f{@i{xxx}-if}'' @term{functions} or
@kwd{test} arguments with @symbolref{complement, SYM} are preferred.


@node constantly
@syindexanchor{constantly, SYM}
@subsection constantly (Function)
@cindex constantly



@subsubheading Syntax:

@DefunWithValues{constantly, value, function}

@subsubheading Arguments and Values:

@param{value}---an @term{object}.

@param{function}---a @term{function}.

@subsubheading Description:

@symbolref{constantly, SYM} returns a @term{function} that accepts any number of
arguments, that has no side-effects, and that always returns @param{value}.

@subsubheading Examples:

@lisp
 (mapcar (constantly 3) '(a b c d)) @EV{} (3 3 3 3)
 (defmacro with-vars (vars &body forms)
   `((lambda ,vars ,@@forms) ,@@(mapcar (constantly nil) vars)))
@EV{} WITH-VARS
 (macroexpand '(with-vars (a b) (setq a 3 b (* a a)) (list a b)))
@EV{} ((LAMBDA (A B) (SETQ A 3 B (* A A)) (LIST A B)) NIL NIL), @term{true}
@end lisp


@subsubheading See Also:

@ref{identity}

@subsubheading Notes:

@symbolref{constantly, SYM} could be defined by:

@lisp
 (defun constantly (object)
   #'(lambda (&rest arguments) object))
@end lisp




@node every; some; notevery; notany
@syindexanchor{every, SYM}
@syindexanchor{some, SYM}
@syindexanchor{notevery, SYM}
@syindexanchor{notany, SYM}
@subsection every, some, notevery, notany (Function)
@cindex every
@cindex some
@cindex notevery
@cindex notany
@anchor{every}
@anchor{some}


@subsubheading Syntax:

@DefunWithValues{every, predicate @rest{} @plus{sequences}, generalized-boolean}
@DefunWithValues{some, predicate @rest{} @plus{sequences}, result}
@DefunWithValues{notevery, predicate @rest{} @plus{sequences}, generalized-boolean}
@DefunWithValues{notany, predicate @rest{} @plus{sequences}, generalized-boolean}

@subsubheading Arguments and Values:

@param{predicate}---a @term{designator} for a @term{function} of
as many @term{arguments} as there are @param{sequences}.

@param{sequence}---a @term{sequence}.

@param{result}---an @term{object}.

@param{generalized-boolean}---a @term{generalized boolean}.

@subsubheading Description:

@symbolref{every, SYM}, @symbolref{some, SYM}, @symbolref{notevery, SYM}, and @symbolref{notany, SYM}
test @term{elements} of @param{sequences} for satisfaction of a given @param{predicate}.
The first argument to @param{predicate} is an @term{element} of the first @param{sequence};
each succeeding argument is an @term{element} of a succeeding @param{sequence}.

@param{Predicate} is first applied to the elements
with index @f{0} in each of the @param{sequences}, and possibly then to
the elements with index @f{1}, and so on, until a termination
criterion is met or the end of the shortest of the @param{sequences} is reached.

@symbolref{every, SYM} returns @term{false} as soon
as any invocation of @param{predicate} returns @term{false}.
If the end of a @param{sequence} is reached,
@symbolref{every, SYM} returns @term{true}.
Thus, @symbolref{every, SYM} returns @term{true} if and only if
every invocation of @param{predicate} returns @term{true}.

@symbolref{some, SYM} returns the first @term{non-nil} value
which is returned by an invocation of @param{predicate}.
If the end of a @param{sequence} is reached without any invocation of the
@param{predicate} returning @term{true}, @symbolref{some, SYM} returns @term{false}.
Thus, @symbolref{some, SYM} returns @term{true} if and only if
some invocation of @param{predicate} returns @term{true}.

@symbolref{notany, SYM} returns @term{false}
as soon as any invocation of @param{predicate} returns @term{true}.
If the end of a @param{sequence} is reached,
@symbolref{notany, SYM} returns @term{true}.
Thus, @symbolref{notany, SYM} returns @term{true} if and only if
it is not the case that any invocation of @param{predicate} returns @term{true}.

@symbolref{notevery, SYM} returns @term{true} as soon as any invocation of
@param{predicate} returns @term{false}.
If the end of a @param{sequence} is reached,
@symbolref{notevery, SYM} returns @term{false}.
Thus, @symbolref{notevery, SYM} returns @term{true} if and only if
it is not the case that every invocation of @param{predicate} returns @term{true}.

@subsubheading Examples:

@lisp
 (every #'characterp "abc") @EV{} @term{true}
 (some #'= '(1 2 3 4 5) '(5 4 3 2 1)) @EV{} @term{true}
 (notevery #'< '(1 2 3 4) '(5 6 7 8) '(9 10 11 12)) @EV{} @term{false}
 (notany #'> '(1 2 3 4) '(5 6 7 8) '(9 10 11 12)) @EV{} @term{true}
@end lisp


@subsubheading Exceptional Situations:

Should signal @symbolref{type-error, SYM} if its first argument is neither a
@term{symbol} nor a @term{function} or if any subsequent
argument is not a @term{proper sequence}.

Other exceptional situations are possible, depending on the nature
of the @param{predicate}.

@subsubheading See Also:

@ref{and (Macro)},
@ref{or (Macro)},
@ref{Traversal Rules and Side Effects}

@subsubheading Notes:

@lisp
 (notany @param{predicate} @starparam{sequence}) @EQ{} (not (some @param{predicate} @starparam{sequence}))
 (notevery @param{predicate} @starparam{sequence}) @EQ{} (not (every @param{predicate} @starparam{sequence}))
@end lisp



@node and (Macro)
@syindexanchor{and, M}
@subsection and (Macro)
@cindex and


@subsubheading Syntax:

@DefmacWithValues{and, @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{form}---a @term{form}.

@param{results}---the @term{values} resulting from the evaluation of
the last @param{form}, or the symbols @nil{}@spc{}or @symbolref{t, SC}.

@subsubheading Description:

The macro @symbolref{and, M} evaluates each @param{form} one at a time from left to right.
As soon as any @param{form} evaluates to @nil{}, @symbolref{and, M} returns
@nil{}@spc{}without evaluating the remaining @param{forms}.  If all @param{forms}
but the last evaluate to @term{true} values, @symbolref{and, M} returns the results
produced by evaluating the last @param{form}.

If no @param{forms} are supplied, @f{(and)} returns @symbolref{t, SC}.

@symbolref{and, M} passes back multiple values from the last @term{subform}
but not from subforms other than the last.

@subsubheading Examples:

@lisp
 (if (and (>= n 0)
          (< n (length a-simple-vector))
          (eq (elt a-simple-vector n) 'foo))
     (princ "Foo!"))
@end lisp

The above expression prints @f{Foo!} if element @f{n} of @f{a-simple-vector}
is the symbol @f{foo}, provided also that @f{n} is indeed a valid index
for @f{a-simple-vector}.  Because @symbolref{and, M} guarantees
left-to-right testing
of its parts, @symbolref{elt, SYM} is not called if @f{n} is out of range.

@lisp
 (setq temp1 1 temp2 1 temp3 1) @EV{} 1
 (and (incf temp1) (incf temp2) (incf temp3)) @EV{} 2
 (and (eql 2 temp1) (eql 2 temp2) (eql 2 temp3)) @EV{} @term{true}
 (decf temp3) @EV{} 1
 (and (decf temp1) (decf temp2) (eq temp3 'nil) (decf temp3)) @EV{} NIL
 (and (eql temp1 temp2) (eql temp2 temp3)) @EV{} @term{true}
 (and) @EV{} T
@end lisp


@subsubheading See Also:

@ref{cond},
@ref{every},
@ref{if},
@ref{or (Macro)},
@ref{when}

@subsubheading Notes:

@lisp
 (and @param{form}) @EQ{} (let () @param{form})
 (and @param{form1} @param{form2} ...) @EQ{} (when @param{form1} (and @param{form2} ...))
@end lisp



@node cond
@syindexanchor{cond, SYM}
@subsection cond (Macro)
@cindex cond


@subsubheading Syntax:

@DefmacWithValues{cond, @stardown{clause}, @starparam{result}}

@auxbnf{clause, @paren{test-form @starparam{form}}}

@subsubheading Arguments and Values:

@param{test-form}---a @term{form}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} of the @param{forms}
in the first @param{clause} whose @param{test-form} @term{yields} @term{true},
or the @term{primary value} of the @param{test-form}
if there are no @param{forms} in that @param{clause},
or else @nil{}@spc{}if no @param{test-form} @term{yields} @term{true}.

@subsubheading Description:

@symbolref{cond, SYM} allows the execution of @param{forms} to be dependent
on @param{test-form}.

@param{Test-forms} are evaluated one at a time in the order in which
they are given in the argument list until a @param{test-form} is found that
evaluates to @term{true}.

If there are no @term{forms} in that clause, the @term{primary value}
of the @param{test-form} is returned by the @symbolref{cond, SYM} @term{form}.
Otherwise, the @param{forms} associated with this @param{test-form} are
evaluated in order, left to right, as an @term{implicit progn}, and the
@term{values} returned by the last @param{form}
are returned by the @symbolref{cond, SYM} @term{form}.

Once one @param{test-form} has @term{yielded} @term{true},
no additional @param{test-forms} are @term{evaluated}.
If no @param{test-form} @term{yields} @term{true}, @nil{}@spc{}is returned.

@subsubheading Examples:

@lisp
 (defun select-options ()
   (cond ((= a 1) (setq a 2))
         ((= a 2) (setq a 3))
         ((and (= a 3) (floor a 2)))
         (t (floor a 3)))) @EV{} SELECT-OPTIONS
 (setq a 1) @EV{} 1
 (select-options) @EV{} 2
 a @EV{} 2
 (select-options) @EV{} 3
 a @EV{} 3
 (select-options) @EV{} 1
 (setq a 5) @EV{} 5
 (select-options) @EV{} 1, 2
@end lisp


@subsubheading See Also:

@ref{if}, @ref{case}.


@node if
@syindexanchor{if, SYM}
@subsection if (Special Operator)
@cindex if


@subsubheading Syntax:

@DefspecWithValues{if, @param{test-form} @param{then-form} @brac{@param{else-form}}, @starparam{result}}

@subsubheading Arguments and Values:

@param{Test-form}---a @term{form}.

@param{Then-form}---a @term{form}.

@param{Else-form}---a @term{form}.
@Default{@nil{}}

@param{results}---if the @param{test-form} @term{yielded} @term{true},
the @term{values} returned by the @param{then-form}; otherwise,
the @term{values} returned by the @param{else-form}.

@subsubheading Description:

@symbolref{if, SYM} allows the execution of a @term{form} to be dependent
on a single @param{test-form}.

First @param{test-form} is evaluated.
If the result is @term{true}, then @param{then-form} is selected;
otherwise @param{else-form} is selected.
Whichever form is selected is then evaluated.

@subsubheading Examples:

@lisp
 (if t 1) @EV{} 1
 (if nil 1 2) @EV{} 2
 (defun test ()
   (dolist (truth-value '(t nil 1 (a b c)))
     (if truth-value (print 'true) (print 'false))
     (prin1 truth-value))) @EV{} TEST
 (test)
@OUT{} TRUE T
@OUT{} FALSE NIL
@OUT{} TRUE 1
@OUT{} TRUE (A B C)
@EV{} NIL
@end lisp


@subsubheading See Also:

@ref{cond},
@ref{unless},
@ref{when}

@subsubheading Notes:

@lisp
 (if @param{test-form} @param{then-form} @param{else-form})
 @EQ{} (cond (@param{test-form} @param{then-form}) (t @param{else-form}))
@end lisp



@node or (Macro)
@syindexanchor{or, M}
@subsection or (Macro)
@cindex or


@subsubheading Syntax:

@DefmacWithValues{or, @starparam{form}, @starparam{results}}

@subsubheading Arguments and Values:

@param{form}---a @term{form}.

@param{results}---the @term{values} or @term{primary value} (see below)
resulting from the evaluation of
the last @param{form} executed or @nil{}.

@subsubheading Description:

@symbolref{or, M} evaluates each @param{form}, one at a time, from left to right.
The evaluation of all @param{forms} terminates when a @param{form} evaluates
to @term{true} (@ie{} something other than @nil{}).

If the @term{evaluation} of any @param{form} other than the last returns a
@term{primary value} that is @term{true}, @symbolref{or, M} immediately returns
that @term{value} (but no additional @term{values}) without evaluating the
remaining @param{forms}.
If every @param{form} but the last returns @term{false} as its @term{primary value},
@symbolref{or, M} returns all @term{values} returned by the last @param{form}.
If no @param{forms} are supplied, @symbolref{or, M} returns @nil{}.

@subsubheading Examples:

@lisp
 (or) @EV{} NIL
 (setq temp0 nil temp1 10 temp2 20 temp3 30) @EV{} 30
 (or temp0 temp1 (setq temp2 37)) @EV{} 10
 temp2 @EV{} 20
 (or (incf temp1) (incf temp2) (incf temp3)) @EV{} 11
 temp1 @EV{} 11
 temp2 @EV{} 20
 temp3 @EV{} 30
 (or (values) temp1) @EV{} 11
 (or (values temp1 temp2) temp3) @EV{} 11
 (or temp0 (values temp1 temp2)) @EV{} 11, 20
 (or (values temp0 temp1) (values temp2 temp3)) @EV{} 20, 30
@end lisp


@subsubheading See Also:

@ref{and (Macro)},
@ref{some},
@ref{unless}


@node when; unless
@syindexanchor{when, SYM}
@syindexanchor{unless, SYM}
@subsection when, unless (Macro)
@cindex when
@cindex unless
@anchor{when}
@anchor{unless}


@subsubheading Syntax:

@DefmacWithValues{when, test-form @starparam{form}, @starparam{result}}

@DefmacWithValues{unless, test-form @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{test-form}---a @term{form}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} of the @term{forms}
in a  @symbolref{when, SYM}   @term{form} if the @param{test-form} @term{yields} @term{true}
or in an @symbolref{unless, SYM} @term{form} if the @param{test-form} @term{yields} @term{false};
otherwise @nil{}.

@subsubheading Description:

@symbolref{when, SYM} and @symbolref{unless, SYM} allow the execution of @param{forms}
to be dependent on a single @param{test-form}.

In a @symbolref{when, SYM} @term{form},
if the @param{test-form} @term{yields} @term{true},
the @param{forms} are @term{evaluated} in order from left to right
and the @term{values} returned by the @param{forms}
are returned from the @symbolref{when, SYM} @term{form}.
Otherwise, if the @param{test-form} @term{yields} @term{false},
the @param{forms} are not @term{evaluated},
and the @symbolref{when, SYM} @term{form} returns @nil{}.

In an @symbolref{unless, SYM} @term{form},
if the @param{test-form} @term{yields} @term{false},
the @param{forms} are @term{evaluated} in order from left to right
and the @term{values} returned by the @param{forms}
are returned from the @symbolref{unless, SYM} @term{form}.
Otherwise, if the @param{test-form} @term{yields} @term{false},
the @param{forms} are not @term{evaluated},
and the @symbolref{unless, SYM} @term{form} returns @nil{}.

@subsubheading Examples:

@lisp
 (when t 'hello) @EV{} HELLO
 (unless t 'hello) @EV{} NIL
 (when nil 'hello) @EV{} NIL
 (unless nil 'hello) @EV{} HELLO
 (when t) @EV{} NIL
 (unless nil) @EV{} NIL
 (when t (prin1 1) (prin1 2) (prin1 3))
@OUT{} 123
@EV{} 3
 (unless t (prin1 1) (prin1 2) (prin1 3)) @EV{} NIL
 (when nil (prin1 1) (prin1 2) (prin1 3)) @EV{} NIL
 (unless nil (prin1 1) (prin1 2) (prin1 3))
@OUT{} 123
@EV{} 3
 (let ((x 3))
   (list (when (oddp x) (incf x) (list x))
         (when (oddp x) (incf x) (list x))
         (unless (oddp x) (incf x) (list x))
         (unless (oddp x) (incf x) (list x))
         (if (oddp x) (incf x) (list x))
         (if (oddp x) (incf x) (list x))
         (if (not (oddp x)) (incf x) (list x))
         (if (not (oddp x)) (incf x) (list x))))
@EV{} ((4) NIL (5) NIL 6 (6) 7 (7))
@end lisp


@subsubheading See Also:

@ref{and (Macro)},
@ref{cond},
@ref{if},
@ref{or (Macro)}

@subsubheading Notes:

@lisp
 (when @param{test} @plus{@curly{@param{form}}}) @EQ{} (and @param{test} (progn @plus{@curly{@param{form}}}))
 (when @param{test} @plus{@curly{@param{form}}}) @EQ{} (cond (@param{test} @plus{@curly{@param{form}}}))
 (when @param{test} @plus{@curly{@param{form}}}) @EQ{} (if @param{test} (progn @plus{@curly{@param{form}}}) nil)
 (when @param{test} @plus{@curly{@param{form}}}) @EQ{} (unless (not @param{test}) @plus{@curly{@param{form}}})
 (unless @param{test} @plus{@curly{@param{form}}}) @EQ{} (cond ((not @param{test}) @plus{@curly{@param{form}}}))
 (unless @param{test} @plus{@curly{@param{form}}}) @EQ{} (if @param{test} nil (progn @plus{@curly{@param{form}}}))
 (unless @param{test} @plus{@curly{@param{form}}}) @EQ{} (when (not @param{test}) @plus{@curly{@param{form}}})
@end lisp



@node case; ccase; ecase
@syindexanchor{case, SYM}
@syindexanchor{ccase, SYM}
@syindexanchor{ecase, SYM}
@subsection case, ccase, ecase (Macro)
@cindex case
@cindex ccase
@cindex ecase
@anchor{case}
@anchor{ccase}


@subsubheading Syntax:

@DefmacWithValues{case, keyform  @stardown{normal-clause} @brac{@down{otherwise-clause}}, @starparam{result}}
@DefmacWithValues{ccase, keyplace @stardown{normal-clause}, @starparam{result}}
@DefmacWithValues{ecase, keyform  @stardown{normal-clause}, @starparam{result}}

@auxbnf{normal-clause, @paren{keys @starparam{form}}}
@auxbnf{otherwise-clause, @paren{@curly{otherwise | t} @starparam{form}}}
@auxbnf{clause, normal-clause | otherwise-clause}
@cindex otherwise
@cindex t

@subsubheading Arguments and Values:

@param{keyform}---a @term{form}; evaluated to produce a @param{test-key}.

@param{keyplace}---a @term{form}; evaluated initially to produce a @param{test-key}.
Possibly also used later as a @term{place} if no @param{keys} match.

@param{test-key}---an object produced by evaluating @param{keyform} or @param{keyplace}.

@param{keys}---a @term{designator} for a @term{list} of @term{objects}.
In the case of @symbolref{case, SYM}, the @term{symbols} @symbolref{t, SC}@spc{}and @t{otherwise} may
not be used as the @param{keys} @term{designator}.  To refer to these @term{symbols}
by themselves as @param{keys}, the designators @f{(t)} and @f{(otherwise)}, respectively,
must be used instead.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} returned by the @param{forms}
in the matching @param{clause}.

@subsubheading Description:

These @term{macros} allow the conditional execution of a body of @param{forms}
in a @param{clause} that is selected by matching the @param{test-key} on the
basis of its identity.

The @param{keyform} or @param{keyplace} is @term{evaluated} to produce the
@param{test-key}.

Each of the @param{normal-clauses} is then considered in turn.
If the @param{test-key} is the @term{same} as any @term{key} for
that @param{clause}, the @param{forms} in that @param{clause} are
@param{evaluated} as an @term{implicit progn}, and the @term{values}
it returns are returned as the value of the @symbolref{case, SYM},
@symbolref{ccase, SYM}, or @symbolref{ecase, SYM} @term{form}.

These @term{macros} differ only in their @i{behavior} when
no @param{normal-clause} matches; specifically:


@table @asis

@item @id{@symbolref{case, SYM}}


If no @param{normal-clause} matches, and there is an @param{otherwise-clause},
then that @param{otherwise-clause} automatically matches; the @param{forms} in
that @param{clause} are @param{evaluated} as an @term{implicit progn},
and the @term{values} it returns are returned as the value of the @symbolref{case, SYM}.

If there is no @param{otherwise-clause}, @symbolref{case, SYM} returns @nil{}.

@item @id{@symbolref{ccase, SYM}}


If no @param{normal-clause} matches,
a @term{correctable} @term{error} @oftype{type-error} is signaled.
The offending datum is the @param{test-key} and
the expected type is @term{type equivalent} to @f{(member @param{key1} @param{key2} ...)}.
@Therestart{store-value} can be used to correct the error.

If @therestart{store-value} is invoked, its @term{argument} becomes the
new @param{test-key}, and is stored in @param{keyplace} as if by
@f{(setf @param{keyplace} @param{test-key})}.
Then @symbolref{ccase, SYM} starts over, considering each @param{clause} anew.

@reviewer{Barmar: Will it prompt for multiple values if keyplace is a VALUES general ref?}

The subforms of @param{keyplace} might be evaluated again if
none of the cases holds.

@item @id{@symbolref{ecase, SYM}}


If no @param{normal-clause} matches,
a @term{non-correctable} @term{error} @oftype{type-error} is signaled.
The offending datum is the @param{test-key} and
the expected type is @term{type equivalent} to @f{(member @param{key1} @param{key2} ...)}.

Note that in contrast with @symbolref{ccase, SYM},
the caller of @symbolref{ecase, SYM} may rely on the fact that @symbolref{ecase, SYM}
does not return if a @param{normal-clause} does not match.
@end table


@subsubheading Examples:

@lisp
 (dolist (k '(1 2 3 :four #@bsl{}v () t 'other))
    (format t "~S "
       (case k ((1 2) 'clause1)
               (3 'clause2)
               (nil 'no-keys-so-never-seen)
               ((nil) 'nilslot)
               ((:four #@bsl{}v) 'clause4)
               ((t) 'tslot)
               (otherwise 'others))))
@OUT{} CLAUSE1 CLAUSE1 CLAUSE2 CLAUSE4 CLAUSE4 NILSLOT TSLOT OTHERS
@EV{} NIL
 (defun add-em (x) (apply #'+ (mapcar #'decode x)))
@EV{} ADD-EM
 (defun decode (x)
   (ccase x
     ((i uno) 1)
     ((ii dos) 2)
     ((iii tres) 3)
     ((iv cuatro) 4)))
@EV{} DECODE
 (add-em '(uno iii)) @EV{} 4
 (add-em '(uno iiii))
@OUT{} Error: The value of X, IIII, is not I, UNO, II, DOS, III,
@OUT{}        TRES, IV, or CUATRO.
@OUT{}  1: Supply a value to use instead.
@OUT{}  2: Return to Lisp Toplevel.
@OUT{} Debug> @IN{:CONTINUE 1}
@OUT{} Value to evaluate and use for X: @IN{'IV}
@EV{} 5
@end lisp


@subsubheading Side Effects:

The debugger might be entered.
If @therestart{store-value} is invoked,
the @term{value} of @param{keyplace} might be changed.

@subsubheading Affected By:

@symbolref{ccase, SYM} and @symbolref{ecase, SYM}, since they might signal an error,
are potentially affected by existing @param{handlers} and @symbolref{*debug-io*, SYM}.

@subsubheading Exceptional Situations:

@symbolref{ccase, SYM} and @symbolref{ecase, SYM} signal an error @oftype{type-error}
if no @param{normal-clause} matches.

@subsubheading See Also:

@ref{cond},
@ref{typecase},
@ref{setf},
@ref{Generalized Reference}

@subsubheading Notes:

@lisp
(case @param{test-key}
  @star{@curly{((@starparam{key}) @starparam{form})}})
@EQ{}
(let ((#1=#:g0001 @param{test-key}))
  (cond @star{@curly{((member #1# '(@starparam{key})) @starparam{form})}}))
@end lisp


The specific error message used by @symbolref{ecase, SYM} and @symbolref{ccase, SYM} can vary
between implementations.  In situations where control of the specific wording
of the error message is important, it is better to use @symbolref{case, SYM} with an
@param{otherwise-clause} that explicitly signals an error with an appropriate
message.


@node typecase; ctypecase; etypecase
@syindexanchor{typecase, SYM}
@syindexanchor{ctypecase, SYM}
@syindexanchor{etypecase, SYM}
@subsection typecase, ctypecase, etypecase (Macro)
@cindex typecase
@cindex ctypecase
@cindex etypecase
@anchor{typecase}
@anchor{ctypecase}


@subsubheading Syntax:

@DefmacWithValues{typecase, keyform  @stardown{normal-clause} @brac{@down{otherwise-clause}}, @starparam{result}}
@DefmacWithValues{ctypecase, keyplace @stardown{normal-clause}, @starparam{result}}
@DefmacWithValues{etypecase, keyform  @stardown{normal-clause}, @starparam{result}}

@auxbnf{normal-clause, @paren{type @starparam{form}}}
@auxbnf{otherwise-clause, @paren{@curly{otherwise | t} @starparam{form}}}
@auxbnf{clause, normal-clause | otherwise-clause}
@cindex otherwise
@cindex t

@subsubheading Arguments and Values:

@param{keyform}---a @term{form}; evaluated to produce a @param{test-key}.

@param{keyplace}---a @term{form}; evaluated initially to produce a @param{test-key}.
Possibly also used later as a @term{place} if no @param{types} match.

@param{test-key}---an object produced by evaluating @param{keyform} or @param{keyplace}.

@param{type}---a @term{type specifier}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} returned by the @param{forms}
in the matching @param{clause}.

@subsubheading Description:

These @term{macros} allow the conditional execution of a body of @param{forms}
in a @param{clause} that is selected by matching the @param{test-key} on the basis
of its @term{type}.

The @param{keyform} or @param{keyplace} is @term{evaluated} to produce the
@param{test-key}.

Each of the @param{normal-clauses} is then considered in turn.
If the @param{test-key} is of the @term{type}
given by the @param{clauses}'s @param{type},
the @param{forms} in that @param{clause} are
@param{evaluated} as an @term{implicit progn}, and the @term{values}
it returns are returned as the value of the @symbolref{typecase, SYM},
@symbolref{ctypecase, SYM}, or @symbolref{etypecase, SYM} @term{form}.

These @term{macros} differ only in their @i{behavior} when
no @param{normal-clause} matches; specifically:


@table @asis

@item @id{@symbolref{typecase, SYM}}


If no @param{normal-clause} matches, and there is an @param{otherwise-clause},
then that @param{otherwise-clause} automatically matches; the @param{forms} in
that @param{clause} are @param{evaluated} as an @term{implicit progn},
and the @term{values} it returns are returned as the value of the @symbolref{typecase, SYM}.

If there is no @param{otherwise-clause}, @symbolref{typecase, SYM} returns @nil{}.

@item @id{@symbolref{ctypecase, SYM}}


If no @param{normal-clause} matches,
a @term{correctable} @term{error} @oftype{type-error} is signaled.
The offending datum is the @param{test-key} and
the expected type is @term{type equivalent} to @f{(or @param{type1} @param{type2} ...)}.
@Therestart{store-value} can be used to correct the error.

If @therestart{store-value} is invoked, its @term{argument} becomes the
new @param{test-key}, and is stored in @param{keyplace} as if by
@f{(setf @param{keyplace} @param{test-key})}.
Then @symbolref{ctypecase, SYM} starts over, considering each @param{clause} anew.

If @therestart{store-value} is invoked interactively,
the user is prompted for a new @param{test-key} to use.

The subforms of @param{keyplace} might be evaluated again if
none of the cases holds.

@item @id{@symbolref{etypecase, SYM}}


If no @param{normal-clause} matches,
a @term{non-correctable} @term{error} @oftype{type-error} is signaled.
The offending datum is the @param{test-key} and
the expected type is @term{type equivalent} to @f{(or @param{type1} @param{type2} ...)}.

Note that in contrast with @symbolref{ctypecase, SYM},
the caller of @symbolref{etypecase, SYM} may rely on the fact that @symbolref{etypecase, SYM}
does not return if a @param{normal-clause} does not match.
@end table


In all three cases, is permissible for more than one @param{clause} to specify a
matching @term{type}, particularly if one is a @term{subtype} of another;
the earliest applicable @param{clause} is chosen.

@subsubheading Examples:

@lisp
;;; (Note that the parts of this example which use TYPE-OF
;;;  are implementation-dependent.)
 (defun what-is-it (x)
   (format t "~&~S is ~A.~%"
           x (typecase x
               (float "a float")
               (null "a symbol, boolean false, or the empty list")
               (list "a list")
               (t (format nil "a(n) ~(~A~)" (type-of x))))))
@EV{} WHAT-IS-IT
 (map 'nil #'what-is-it '(nil (a b) 7.0 7 box))
@OUT{} NIL is a symbol, boolean false, or the empty list.
@OUT{} (A B) is a list.
@OUT{} 7.0 is a float.
@OUT{} 7 is a(n) integer.
@OUT{} BOX is a(n) symbol.
@EV{} NIL
 (setq x 1/3)
@EV{} 1/3
 (ctypecase x
     (integer (* x 4))
     (symbol  (symbol-value x)))
@OUT{} Error: The value of X, 1/3, is neither an integer nor a symbol.
@OUT{} To continue, type :CONTINUE followed by an option number:
@OUT{}  1: Specify a value to use instead.
@OUT{}  2: Return to Lisp Toplevel.
@OUT{} Debug> @IN{:CONTINUE 1}
@OUT{} Use value: @IN{3.7}
@OUT{} Error: The value of X, 3.7, is neither an integer nor a symbol.
@OUT{} To continue, type :CONTINUE followed by an option number:
@OUT{}  1: Specify a value to use instead.
@OUT{}  2: Return to Lisp Toplevel.
@OUT{} Debug> @IN{:CONTINUE 1}
@OUT{} Use value: @IN{12}
@EV{} 48
 x @EV{} 12
@end lisp


@subsubheading Affected By:

@symbolref{ctypecase, SYM} and @symbolref{etypecase, SYM}, since they might signal an error,
are potentially affected by existing @param{handlers} and @symbolref{*debug-io*, SYM}.

@subsubheading Exceptional Situations:

@symbolref{ctypecase, SYM} and @symbolref{etypecase, SYM} signal an error @oftype{type-error}
if no @param{normal-clause} matches.

The @term{compiler} may choose to issue a warning @oftype{style-warning}
if a @param{clause} will never be selected because it is completely
shadowed by earlier clauses.

@subsubheading See Also:

@ref{case},
@ref{cond},
@ref{setf},
@ref{Generalized Reference}

@subsubheading Notes:

@lisp
(typecase @param{test-key}
  @star{@curly{(@param{type} @starparam{form})}})
@EQ{}
(let ((#1=#:g0001 @param{test-key}))
  (cond @star{@curly{((typep #1# '@param{type}) @starparam{form})}}))
@end lisp


The specific error message used by @symbolref{etypecase, SYM} and @symbolref{ctypecase, SYM} can vary
between implementations.  In situations where control of the specific wording
of the error message is important, it is better to use @symbolref{typecase, SYM} with an
@param{otherwise-clause} that explicitly signals an error with an appropriate
message.


@node multiple-value-bind
@syindexanchor{multiple-value-bind, SYM}
@subsection multiple-value-bind (Macro)
@cindex multiple-value-bind



@subsubheading Syntax:

@DefmacWithValuesNewline{multiple-value-bind, @paren{@starparam{var}} @param{values-form} @starparam{declaration} @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{var}---a @term{symbol} naming a variable; @noeval{}.

@param{values-form}---a @term{form}; @eval{}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} returned by the @param{forms}.

@subsubheading Description:

Creates new variable @term{bindings} for the @param{vars} and
executes a series of @param{forms} that use these @term{bindings}.

The variable @term{bindings} created are lexical unless
@symbolref{special, SYM} declarations are specified.

@param{Values-form} is evaluated, and each of the @param{vars} is
bound to the respective value returned by that @term{form}.  If there are more
@param{vars} than values returned, extra values of @nil{}@spc{}are given to the
remaining @param{vars}. If there are more values than
@param{vars}, the excess
values are discarded.  The @param{vars} are bound to the values over
the execution of the @param{forms}, which make up an implicit @symbolref{progn, SYM}.
The consequences are unspecified if a type @param{declaration} is specified
for a @param{var}, but the value to which
that @param{var} is bound  is not consistent with
the type @param{declaration}.

The @term{scopes} of the name binding and @param{declarations}
do not include the @param{values-form}.

@subsubheading Examples:

@lisp
 (multiple-value-bind (f r)
     (floor 130 11)
   (list f r)) @EV{} (11 9)
@end lisp


@subsubheading See Also:

@ref{let},
@ref{multiple-value-call}

@subsubheading Notes:

@lisp
 (multiple-value-bind (@starparam{var}) @param{values-form} @starparam{form})
 @EQ{} (multiple-value-call #'(lambda (&optional @starparam{var} &rest #1=#:ignore)
                             (declare (ignore #1#))
                             @starparam{form})
                         @param{values-form})
@end lisp




@node multiple-value-call
@syindexanchor{multiple-value-call, SYM}
@subsection multiple-value-call (Special Operator)
@cindex multiple-value-call


@subsubheading Syntax:

@DefspecWithValues{multiple-value-call, @param{function-form} @star{@param{form}}, @starparam{result}}

@subsubheading Arguments and Values:

@param{function-form}---a @term{form}; evaluated to produce @param{function}.

@param{function}---a @term{function designator}
resulting from the evaluation of @param{function-form}.

@param{form}---a @term{form}.

@param{results}---the @term{values} returned by the @param{function}.

@subsubheading Description:

Applies @param{function} to a @term{list} of the @term{objects} collected from groups of
@term{multiple values}@sub{2}.

@symbolref{multiple-value-call, SYM} first evaluates the @param{function-form}
to obtain @param{function}, and then evaluates each @param{form}.
All the values
of each @param{form} are gathered together (not just one value from each)
and given as arguments to the @param{function}.

@subsubheading Examples:
@lisp
 (multiple-value-call #'list 1 '/ (values 2 3) '/ (values) '/ (floor 2.5))
@EV{} (1 / 2 3 / / 2 0.5)
 (+ (floor 5 3) (floor 19 4)) @EQ{} (+ 1 4)
@EV{} 5
 (multiple-value-call #'+ (floor 5 3) (floor 19 4)) @EQ{} (+ 1 2 4 3)
@EV{} 10
@end lisp


@subsubheading See Also:

@ref{multiple-value-list}, @ref{multiple-value-bind}


@node multiple-value-list
@syindexanchor{multiple-value-list, SYM}
@subsection multiple-value-list (Macro)
@cindex multiple-value-list


@subsubheading Syntax:

@DefmacWithValues{multiple-value-list, form, list}

@subsubheading Arguments and Values:

@param{form}---a @term{form}; @evalspecial{}.

@param{list}---a @term{list} of the @term{values} returned by @param{form}.

@subsubheading Description:

@symbolref{multiple-value-list, SYM} evaluates @param{form}
and creates a @term{list} of the @term{multiple values}@sub{2} it returns.

@subsubheading Examples:

@lisp
 (multiple-value-list (floor -3 4)) @EV{} (-1 1)
@end lisp


@subsubheading See Also:

@ref{values-list},
@ref{multiple-value-call}

@subsubheading Notes:

@symbolref{multiple-value-list, SYM} and @symbolref{values-list, SYM} are inverses
of each other.

@lisp
 (multiple-value-list form) @EQ{} (multiple-value-call #'list form)
@end lisp



@node multiple-value-prog1
@syindexanchor{multiple-value-prog1, SYM}
@subsection multiple-value-prog1 (Special Operator)
@cindex multiple-value-prog1


@subsubheading Syntax:

@DefspecWithValues{multiple-value-prog1, first-form @starparam{form}, first-form-results}

@subsubheading Arguments and Values:

@param{first-form}---a @term{form}; @evalspecial{}.

@param{form}---a @term{form}; @evalspecial{}.

@param{first-form-results}---the @term{values} resulting from
the @term{evaluation} of @param{first-form}.

@subsubheading Description:

@symbolref{multiple-value-prog1, SYM} evaluates @param{first-form} and saves
all the values produced by that @term{form}. It then evaluates each
@param{form} from left to right, discarding their values.

@subsubheading Examples:

@lisp
 (setq temp '(1 2 3)) @EV{} (1 2 3)
 (multiple-value-prog1
    (values-list temp)
    (setq temp nil)
    (values-list temp)) @EV{} 1, 2, 3
@end lisp


@subsubheading See Also:

@ref{prog1}


@node multiple-value-setq
@syindexanchor{multiple-value-setq, SYM}
@subsection multiple-value-setq (Macro)
@cindex multiple-value-setq


@subsubheading Syntax:

@DefmacWithValues{multiple-value-setq, vars form, result}

@subsubheading Arguments and Values:

@param{vars}---a @term{list} of @term{symbols}
that are either @term{variable} @term{names}
or @term{names} of @term{symbol macros}.

@param{form}---a @term{form}.

@param{result}---The @term{primary value} returned by the @param{form}.

@subsubheading Description:

@symbolref{multiple-value-setq, SYM} assigns values to @param{vars}.

The @param{form} is evaluated,
and each @param{var} is @term{assigned}
to the corresponding @term{value} returned by that @term{form}.
If there are more @param{vars} than @term{values} returned,
@nil{}@spc{}is @term{assigned} to the extra @param{vars}.
If there are more @term{values} than @param{vars},
the extra @term{values} are discarded.

If any @param{var} is the @term{name} of a @term{symbol macro},
then it is @term{assigned} as if by @symbolref{setf, SYM}.  Specifically,

@begingroup{}
@lisp
 (multiple-value-setq (@i{symbol}@sub{1} ... @i{symbol}@sub{1}) @i{value-producing-form})
@end lisp

is defined to always behave in the same way as

@lisp
 (values (setf (values @i{symbol}@sub{1} ... @i{symbol}@sub{1}) @i{value-producing-form}))
@end lisp

@endgroup{}
in order that the rules for order of evaluation and side-effects be consistent
with those used by @symbolref{setf, SYM}.
@cindex order of evaluation
@cindex evaluation order
See @ref{VALUES Forms as Places}.

@subsubheading Examples:

@lisp
 (multiple-value-setq (quotient remainder) (truncate 3.2 2)) @EV{} 1
 quotient @EV{} 1
 remainder @EV{} 1.2
 (multiple-value-setq (a b c) (values 1 2)) @EV{} 1
 a @EV{} 1
 b @EV{} 2
 c @EV{} NIL
 (multiple-value-setq (a b) (values 4 5 6)) @EV{} 4
 a @EV{} 4
 b @EV{} 5
@end lisp


@subsubheading See Also:

@ref{setq},
@ref{symbol-macrolet}


@node values (Accessor)
@syindexanchor{values, A}
@subsection values (Accessor)
@cindex values


@subsubheading Syntax:

@DefunWithValues{values, @rest{} object, @starparam{object}}
@Defsetf{values, @rest{} place, new-values}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@param{place}---a @term{place}.

@param{new-value}---an @term{object}.

@subsubheading Description:

@symbolref{values, A}
returns the @param{objects} as @term{multiple values}@sub{2}.

@symbolref{setf, SYM} of @symbolref{values, A} is used to store the
@term{multiple values}@sub{2} @param{new-values} into the @param{places}.
See @ref{VALUES Forms as Places}.

@subsubheading Examples:

@lisp
 (values) @EV{} @novalues{}
 (values 1) @EV{} 1
 (values 1 2) @EV{} 1, 2
 (values 1 2 3) @EV{} 1, 2, 3
 (values (values 1 2 3) 4 5) @EV{} 1, 4, 5
 (defun polar (x y)
   (values (sqrt (+ (* x x) (* y y))) (atan y x))) @EV{} POLAR
 (multiple-value-bind (r theta) (polar 3.0 4.0)
   (vector r theta))
@EV{} #(5.0 0.927295)
@end lisp


Sometimes it is desirable to indicate explicitly that a function returns
exactly one value.  For example, the function

@lisp
 (defun foo (x y)
   (floor (+ x y) y)) @EV{} FOO
@end lisp

returns two values because @symbolref{floor, SYM} returns
two values.  It may be that the second value makes no sense,
or that for efficiency reasons it is desired not to compute the
second value.  @symbolref{values, A} is the standard idiom
for indicating that only one value is to be returned:

@lisp
 (defun foo (x y)
   (values (floor (+ x y) y))) @EV{} FOO
@end lisp

This works because @symbolref{values, A}
returns exactly one value for each of
@param{args}; as for any function call,
if any of @param{args} produces more than one value, all but the
first are discarded.

@subsubheading See Also:

@ref{values-list},
@ref{multiple-value-bind},
@ref{multiple-values-limit},
@ref{Evaluation}

@subsubheading Notes:

Since @symbolref{values, A} is a @term{function}, not a @term{macro} or @term{special form},
it receives as @term{arguments} only the @term{primary values} of
its @term{argument} @term{forms}.


@node values-list
@syindexanchor{values-list, SYM}
@subsection values-list (Function)
@cindex values-list


@subsubheading Syntax:

@DefunWithValues{values-list, list, @starparam{element}}

@subsubheading Arguments and Values:

@param{list}---a @term{list}.

@param{elements}---the @term{elements} of the @param{list}.

@subsubheading Description:

Returns the @term{elements} of the @param{list} as @term{multiple values}@sub{2}.

@subsubheading Examples:

@lisp
 (values-list nil) @EV{} @novalues{}
 (values-list '(1)) @EV{} 1
 (values-list '(1 2)) @EV{} 1, 2
 (values-list '(1 2 3)) @EV{} 1, 2, 3
@end lisp


@subsubheading Exceptional Situations:

Should signal @symbolref{type-error, SYM} if its argument is not a @term{proper list}.

@subsubheading See Also:

@ref{multiple-value-bind},
@ref{multiple-value-list},
@ref{multiple-values-limit},
@ref{values (Accessor)}

@subsubheading Notes:

@lisp
 (values-list @param{list}) @EQ{} (apply #'values @param{list})
@end lisp


@f{(equal @param{x} (multiple-value-list (values-list @param{x})))}
returns @term{true} for all @term{lists} @param{x}.


@node multiple-values-limit
@syindexanchor{multiple-values-limit, SYM}
@subsection multiple-values-limit (Constant Variable)
@cindex multiple-values-limit


@subsubheading Constant Value:

An @term{integer} not smaller than @f{20},
the exact magnitude of which is @term{implementation-dependent}.

@subsubheading Description:

The upper exclusive bound on the number of @term{values} that may be
returned from a @term{function},
bound or assigned by @symbolref{multiple-value-bind, SYM} or @symbolref{multiple-value-setq, SYM},
or passed as a first argument to @symbolref{nth-value, SYM}.
(If these individual limits might differ, the minimum value is used.)

@subsubheading See Also:

@ref{lambda-parameters-limit}, @ref{call-arguments-limit}

@subsubheading Notes:

Implementors are encouraged to make this limit as large as possible.


@node nth-value
@syindexanchor{nth-value, SYM}
@subsection nth-value (Macro)
@cindex nth-value



@subsubheading Syntax:

@DefmacWithValues{nth-value, n form, object}

@subsubheading Arguments and Values:

@param{n}---a non-negative @term{integer}; @eval{}.

@param{form}---a @term{form}; @evalspecial{}.

@param{object}---an @term{object}.

@subsubheading Description:

Evaluates @param{n} and then @param{form},
returning as its only value the @param{n}th value @term{yielded} by @param{form},
or @nil{}@spc{}if @param{n} is greater than or equal to the number of @term{values}
returned by @param{form}.  (The first returned value is numbered @f{0}.)

@subsubheading Examples:

@lisp
 (nth-value 0 (values 'a 'b)) @EV{} A
 (nth-value 1 (values 'a 'b)) @EV{} B
 (nth-value 2 (values 'a 'b)) @EV{} NIL
 (let* ((x 83927472397238947423879243432432432)
        (y 32423489732)
        (a (nth-value 1 (floor x y)))
        (b (mod x y)))
   (values a b (= a b)))
@EV{} 3332987528, 3332987528, @term{true}
@end lisp


@subsubheading See Also:

@ref{multiple-value-list},
@ref{nth}

@subsubheading Notes:

Operationally, the following relationship is true, although @symbolref{nth-value, SYM}
might be more efficient in some @term{implementations}
because, for example, some @term{consing} might be avoided.

@lisp
 (nth-value @param{n} @param{form}) @EQ{} (nth @param{n} (multiple-value-list @param{form}))
@end lisp



@node prog; prog*
@syindexanchor{prog, SYM}
@syindexanchor{prog*, SYM}
@subsection prog, prog* (Macro)
@cindex prog
@cindex prog*



@subsubheading Syntax:

@DefmacWithValuesNewline{prog, @paren{@star{@curly{@param{var} @mat{@vert{}} @paren{@param{var} @brac{@param{init-form}}}}}} @starparam{declaration} @star{@curly{@param{tag} @mat{@vert{}} @param{statement}}}, @starparam{result}}

@DefmacWithValuesNewline{prog*, @paren{@star{@curly{@param{var} @mat{@vert{}} @paren{@param{var} @brac{@param{init-form}}}}}} @starparam{declaration} @star{@curly{@param{tag} @mat{@vert{}} @param{statement}}}, @starparam{result}}

@subsubheading Arguments and Values:

@param{var}---variable name.

@param{init-form}---a @term{form}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{tag}---a @term{go tag}; @noeval{}.

@param{statement}---a @term{compound form}; @evalspecial{}.

@param{results}---@nil{}@spc{}if a @term{normal return} occurs,
or else, if an @term{explicit return} occurs, the @term{values} that were transferred.

@subsubheading Description:

Three distinct operations are performed by @symbolref{prog, SYM} and
@symbolref{prog*, SYM}:
they bind local variables,
they permit use of the @symbolref{return, SYM}
statement, and they permit use of the @symbolref{go, SYM}
statement.
A typical @symbolref{prog, SYM} looks like this:

@lisp
 (prog (var1 var2 (var3 init-form-3) var4 (var5 init-form-5))
       @starparam{declaration}
       statement1
  tag1
       statement2
       statement3
       statement4
  tag2
       statement5
       ...
       )
@end lisp


For @symbolref{prog, SYM},
@param{init-forms} are evaluated first, in the order in which they are
supplied. The @param{vars} are then bound to the corresponding values in
parallel.  If no @param{init-form}
is supplied for a given @param{var},
that @param{var} is  bound to @nil{}.

The body of @symbolref{prog, SYM} is executed as if it were a @symbolref{tagbody, SYM} @term{form};
the @symbolref{go, SYM} statement can be used to transfer control
to a @param{tag}.
@param{Tags} label @param{statements}.

@symbolref{prog, SYM} implicitly establishes a @symbolref{block, SYM} named @nil{}@spc{}around
the entire @symbolref{prog, SYM} @term{form}, so that @symbolref{return, SYM} can be used
at any time to exit from the @symbolref{prog, SYM} @term{form}.

The difference between @symbolref{prog*, SYM} and @symbolref{prog, SYM} is that
in @symbolref{prog*, SYM} the @term{binding} and initialization of the @param{vars}
is done @term{sequentially}, so that the @param{init-form} for each
one can use the values of previous ones.

@subsubheading Examples:
@lisp
(prog* ((y z) (x (car y)))
       (return x))
@end lisp

returns the @term{car} of the value of @f{z}.

@lisp
 (setq a 1) @EV{} 1
 (prog ((a 2) (b a)) (return (if (= a b) '= '/=))) @EV{} /=
 (prog* ((a 2) (b a)) (return (if (= a b) '= '/=))) @EV{} =
 (prog () 'no-return-value) @EV{} NIL
@end lisp

@lisp
 (defun king-of-confusion (w)
   "Take a cons of two lists and make a list of conses.
    Think of this function as being like a zipper."
   (prog (x y z)          ;Initialize x, y, z to NIL
        (setq y (car w) z (cdr w))
    loop
        (cond ((null y) (return x))
              ((null z) (go err)))
    rejoin
        (setq x (cons (cons (car y) (car z)) x))
        (setq y (cdr y) z (cdr z))
        (go loop)
    err
        (cerror "Will self-pair extraneous items"
                "Mismatch - gleep!  ~S" y)
        (setq z y)
        (go rejoin))) @EV{} KING-OF-CONFUSION
@end lisp

This can be accomplished more perspicuously as follows:

@lisp
 (defun prince-of-clarity (w)
   "Take a cons of two lists and make a list of conses.
    Think of this function as being like a zipper."
   (do ((y (car w) (cdr y))
        (z (cdr w) (cdr z))
        (x '@empty{} (cons (cons (car y) (car z)) x)))
       ((null y) x)
     (when (null z)
       (cerror "Will self-pair extraneous items"
              "Mismatch - gleep!  ~S" y)
       (setq z y)))) @EV{} PRINCE-OF-CLARITY
@end lisp


@subsubheading See Also:

@ref{block}, @ref{let}, @ref{tagbody}, @ref{go},
@ref{return}, @ref{Evaluation}

@subsubheading Notes:
@symbolref{prog, SYM} can be explained in terms of
@symbolref{block, SYM}, @symbolref{let, SYM}, and @symbolref{tagbody, SYM} as
follows:

@lisp
 (prog @param{variable-list} @param{declaration} . @param{body})
    @EQ{} (block nil (let @param{variable-list} @param{declaration} (tagbody . @param{body})))
@end lisp




@node prog1; prog2
@syindexanchor{prog1, SYM}
@syindexanchor{prog2, SYM}
@subsection prog1, prog2 (Macro)
@cindex prog1
@cindex prog2
@anchor{prog1}
@anchor{prog2}


@subsubheading Syntax:

@DefmacWithValues{prog1, first-form             @starparam{form}, result-1}
@DefmacWithValues{prog2, first-form second-form @starparam{form}, result-2}

@subsubheading Arguments and Values:

@param{first-form}---a @term{form}; @evalspecial{}.

@param{second-form}---a @term{form}; @evalspecial{}.

@param{forms}---an @term{implicit progn}; @evalspecial{}.

@param{result-1}---the @term{primary value} resulting from
the @term{evaluation} of @param{first-form}.

@param{result-2}---the @term{primary value} resulting from
the @term{evaluation} of @param{second-form}.

@subsubheading Description:

@symbolref{prog1, SYM} @term{sequences} @param{first-form}
and then @param{forms},
@term{yielding} as its only @term{value}
the @term{primary value} @term{yielded} by @param{first-form}.

@symbolref{prog2, SYM} @term{sequences} @param{first-form},
then @param{second-form},
and then @param{forms},
@term{yielding} as its only @term{value}
the @term{primary value} @term{yielded} by @param{first-form}.

@subsubheading Examples:

@lisp
 (setq temp 1) @EV{} 1
 (prog1 temp (print temp) (incf temp) (print temp))
@OUT{} 1
@OUT{} 2
@EV{} 1
 (prog1 temp (setq temp nil)) @EV{} 2
 temp @EV{} NIL
 (prog1 (values 1 2 3) 4) @EV{} 1
 (setq temp (list 'a 'b 'c))
 (prog1 (car temp) (setf (car temp) 'alpha)) @EV{} A
 temp @EV{} (ALPHA B C)
 (flet ((swap-symbol-values (x y)
          (setf (symbol-value x)
                (prog1 (symbol-value y)
                       (setf (symbol-value y) (symbol-value x))))))
   (let ((*foo* 1) (*bar* 2))
     (declare (special *foo* *bar*))
     (swap-symbol-values '*foo* '*bar*)
     (values *foo* *bar*)))
@EV{} 2, 1
 (setq temp 1) @EV{} 1
 (prog2 (incf temp) (incf temp) (incf temp)) @EV{} 3
 temp @EV{} 4
 (prog2 1 (values 2 3 4) 5) @EV{} 2
@end lisp


@subsubheading See Also:

@ref{multiple-value-prog1},
@ref{progn}

@subsubheading Notes:

@symbolref{prog1, SYM} and @symbolref{prog2, SYM} are typically used to @term{evaluate}
one or more @term{forms} with side effects and return a @term{value} that
must be computed before some or all of the side effects happen.

@lisp
 (prog1 @starparam{form}) @EQ{} (values (multiple-value-prog1 @starparam{form}))
 (prog2 @param{form1} @starparam{form}) @EQ{} (let () @param{form1} (prog1 @starparam{form}))
@end lisp



@node progn
@syindexanchor{progn, SYM}
@subsection progn (Special Operator)
@cindex progn


@subsubheading Syntax:

@DefspecWithValues{progn, @starparam{form}, @starparam{result}}

@subsubheading Arguments and Values:

@param{forms}---an @term{implicit progn}.

@param{results}---the @term{values} of the @term{forms}.

@subsubheading Description:

@symbolref{progn, SYM} evaluates @param{forms},
in the order in which they are given.

The values of each @param{form} but the last are discarded.

If @symbolref{progn, SYM} appears as a @term{top level form}, then all @term{forms}
within that @symbolref{progn, SYM} are considered by the compiler to be
@term{top level forms}.

@subsubheading Examples:
@lisp
 (progn) @EV{} NIL
 (progn 1 2 3) @EV{} 3
 (progn (values 1 2 3)) @EV{} 1, 2, 3
 (setq a 1) @EV{} 1
 (if a
      (progn (setq a nil) 'here)
      (progn (setq a t) 'there)) @EV{} HERE
 a @EV{} NIL
@end lisp


@subsubheading See Also:

@ref{prog1}, @ref{Evaluation}

@subsubheading Notes:

Many places in @clisp{}@spc{}involve syntax that uses @term{implicit progns}.
That is, part of their syntax allows many @term{forms} to be written
that are to be evaluated sequentially, discarding the results
of all @term{forms} but the last and returning the results of the last @term{form}.
Such places include, but are not limited to, the following:
the body of a @term{lambda expression};
the bodies of various control and conditional @term{forms}
(@eg{} @symbolref{case, SYM}, @symbolref{catch, SYM}, @symbolref{progn, SYM}, and @symbolref{when, SYM}).


@node define-modify-macro
@syindexanchor{define-modify-macro, SYM}
@subsection define-modify-macro (Macro)
@cindex define-modify-macro


@subsubheading Syntax:

@DefmacWithValues{define-modify-macro, name lambda-list function @brac{documentation}, name}

@subsubheading Arguments and Values:

@param{name}---a @term{symbol}.

@param{lambda-list}---a @term{define-modify-macro lambda list}

@param{function}---a @term{symbol}.

@param{documentation}---a @term{string}; @noeval{}.

@subsubheading Description:

@symbolref{define-modify-macro, SYM} defines a @term{macro} named
@param{name} to @term{read} and @term{write} a @term{place}.

The arguments to the new @term{macro} are a @term{place},
followed
by the arguments that are supplied in @param{lambda-list}.
@term{Macros} defined with @symbolref{define-modify-macro, SYM}
correctly pass the @term{environment parameter} to
@symbolref{get-setf-expansion, SYM}.

When the @term{macro} is invoked, @param{function}
is applied to the old contents of the @term{place}
and the @param{lambda-list} arguments to obtain the new value,
and the @term{place} is updated to contain the result.

Except for the issue of avoiding multiple evaluation (see below), the expansion
of a @symbolref{define-modify-macro, SYM} is equivalent to the following:

@lisp
 (defmacro @param{name} (reference . @param{lambda-list})
   @param{documentation}
   @bq{}(setf ,reference
          (@param{function} ,reference ,@i{arg1} ,@i{arg2} ...)))
@end lisp


where @i{arg1}, @i{arg2}, ...,
are the parameters appearing in @param{lambda-list};
appropriate provision is made for a @term{rest parameter}.

The @term{subforms} of the macro calls defined by @symbolref{define-modify-macro, SYM}
are evaluated as specified in @ref{Evaluation of Subforms to Places}.

@param{Documentation} is attached as a @term{documentation string}
to @param{name} (as kind @symbolref{function, SO})
and to the @term{macro function}.

If a @symbolref{define-modify-macro, SYM} @term{form} appears as a @term{top level form},
the @term{compiler} must store the @term{macro} definition at compile time,
so that occurrences of the macro later on in the file can be expanded correctly.

@subsubheading Examples:
@lisp
 (define-modify-macro appendf (&rest args)
    append "Append onto list") @EV{} APPENDF
 (setq x '(a b c) y x) @EV{} (A B C)
 (appendf x '(d e f) '(1 2 3)) @EV{} (A B C D E F 1 2 3)
 x @EV{} (A B C D E F 1 2 3)
 y @EV{} (A B C)
 (define-modify-macro new-incf (&optional (delta 1)) +)
 (define-modify-macro unionf (other-set &rest keywords) union)
@end lisp


@subsubheading Side Effects:

A macro definition is assigned to @param{name}.

@subsubheading See Also:

@ref{defsetf},
@ref{define-setf-expander},
@ref{documentation},
@ref{Syntactic Interaction of Documentation Strings and Declarations}


@node defsetf
@syindexanchor{defsetf, SYM}
@subsection defsetf (Macro)
@cindex defsetf



@subsubheading Syntax:

The ``short form'':

@DefmacWithValuesNewline{defsetf, access-fn update-fn @brac{documentation}, access-fn}

The ``long form'':

@DefmacWithValuesNewline{defsetf, access-fn lambda-list @paren{@starparam{store-variable}} @DeclsAndDoc{} @starparam{form}, access-fn}

@subsubheading Arguments and Values:

@param{access-fn}---a @term{symbol} which names a @term{function} or a @term{macro}.

@param{update-fn}---a @term{symbol} naming a @term{function} or @term{macro}.

@param{lambda-list}---a @term{defsetf lambda list}.

@param{store-variable}---a @term{symbol} (a @term{variable} @term{name}).

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{documentation}---a @term{string}; @noeval{}.

@param{form}---a @term{form}.

@subsubheading Description:

@symbolref{defsetf, SYM} defines how to
@symbolref{setf, SYM} a @term{place}
of the form @f{(@i{access-fn} ...)} for relatively simple cases.
(See @symbolref{define-setf-expander, SYM} for more general access to this facility.)
It must be the case that the @term{function} or @term{macro} named by @param{access-fn}
evaluates all of its arguments.

@symbolref{defsetf, SYM} may take one of two forms, called the ``short form'' and the ``long form,''
which are distinguished by the @term{type} of the second @term{argument}.

When the short form is used,
@param{update-fn} must name
a @term{function} (or @term{macro}) that takes one more argument
than @param{access-fn} takes.  When @symbolref{setf, SYM} is given a @term{place}
that is a call on @param{access-fn}, it expands into
a call on @param{update-fn} that is given all the arguments to
@param{access-fn} and also, as its last argument, the new value
(which must be returned by @param{update-fn} as its value).

The long form @symbolref{defsetf, SYM}
resembles @symbolref{defmacro, SYM}.
The @param{lambda-list} describes the arguments of @param{access-fn}.
The @param{store-variables} describe the
value
or values
to be stored into the @term{place}.
The @param{body} must
compute the expansion of a @symbolref{setf, SYM} of a call on @param{access-fn}.
The expansion function is defined in the same @term{lexical environment}
in which the @symbolref{defsetf, SYM} @term{form} appears.

During the evaluation of the
@param{forms}, the variables in the @param{lambda-list} and the
@param{store-variables}
are bound to names of temporary variables,
generated as if by @symbolref{gensym, SYM}
or @symbolref{gentemp, SYM},
that will be bound by the
expansion of @symbolref{setf, SYM}
to the values of those @term{subforms}.  This binding
permits the
@param{forms} to be written without regard for order-of-evaluation
issues.  @symbolref{defsetf, SYM} arranges for the temporary variables to be
optimized out of the final result in cases where that is possible.

The body code in @symbolref{defsetf, SYM} is implicitly enclosed in a
@term{block} whose name is
@param{access-fn}

@symbolref{defsetf, SYM}
ensures that @term{subforms}
of the @term{place} are evaluated exactly once.

@param{Documentation} is attached to @param{access-fn} as a @term{documentation string}
of kind @t{setf}.

If a @symbolref{defsetf, SYM} @term{form} appears as a @term{top level form},
the @term{compiler} must make the @term{setf expander} available so that
it may be used to expand calls to @symbolref{setf, SYM} later on in the @term{file}.
Users must ensure that the @param{forms}, if any, can be evaluated
at compile time if the @param{access-fn} is used in a @term{place}
later in the same @term{file}.
The @term{compiler} must make these @term{setf expanders} available to
compile-time calls to @symbolref{get-setf-expansion, SYM} when its @param{environment}
argument is a value received as the @term{environment parameter} of a @term{macro}.

@subsubheading Examples:
The effect of

@lisp
 (defsetf symbol-value set)
@end lisp

is built into the @clisp{}@spc{}system.
This causes the form @f{(setf (symbol-value foo) fu)}
to expand into @f{(set foo fu)}.

Note that

@lisp
 (defsetf car rplaca)
@end lisp

would be incorrect because @symbolref{rplaca, SYM} does not return its last argument.

@lisp
 (defun middleguy (x) (nth (truncate (1- (list-length x)) 2) x)) @EV{} MIDDLEGUY
 (defun set-middleguy (x v)
    (unless (null x)
      (rplaca (nthcdr (truncate (1- (list-length x)) 2) x) v))
    v) @EV{} SET-MIDDLEGUY
 (defsetf middleguy set-middleguy) @EV{} MIDDLEGUY
 (setq a (list 'a 'b 'c 'd)
       b (list 'x)
       c (list 1 2 3 (list 4 5 6) 7 8 9)) @EV{} (1 2 3 (4 5 6) 7 8 9)
 (setf (middleguy a) 3) @EV{} 3
 (setf (middleguy b) 7) @EV{} 7
 (setf (middleguy (middleguy c)) 'middleguy-symbol) @EV{} MIDDLEGUY-SYMBOL
 a @EV{} (A 3 C D)
 b @EV{} (7)
 c @EV{} (1 2 3 (4 MIDDLEGUY-SYMBOL 6) 7 8 9)
@end lisp


An example of the use of the long form of @symbolref{defsetf, SYM}:

@lisp
 (defsetf subseq (sequence start &optional end) (new-sequence)
   `(progn (replace ,sequence ,new-sequence
                    :start1 ,start :end1 ,end)
           ,new-sequence)) @EV{} SUBSEQ
@end lisp


@lisp
 (defvar *xy* (make-array '(10 10)))
 (defun xy (&key ((x x) 0) ((y y) 0)) (aref *xy* x y)) @EV{} XY
 (defun set-xy (new-value &key ((x x) 0) ((y y) 0))
   (setf (aref *xy* x y) new-value)) @EV{} SET-XY
 (defsetf xy (&key ((x x) 0) ((y y) 0)) (store)
   `(set-xy ,store 'x ,x 'y ,y)) @EV{} XY
 (get-setf-expansion '(xy a b))
@EV{} (#:t0 #:t1),
   (a b),
   (#:store),
   ((lambda (&key ((x #:x)) ((y #:y)))
      (set-xy #:store 'x #:x 'y #:y))
    #:t0 #:t1),
   (xy #:t0 #:t1)
 (xy 'x 1) @EV{} NIL
 (setf (xy 'x 1) 1) @EV{} 1
 (xy 'x 1) @EV{} 1
 (let ((a 'x) (b 'y))
   (setf (xy a 1 b 2) 3)
   (setf (xy b 5 a 9) 14))
@EV{} 14
 (xy 'y 0 'x 1) @EV{} 1
 (xy 'x 1 'y 2) @EV{} 3
@end lisp


@subsubheading See Also:

@ref{documentation},
@ref{setf},
@ref{define-setf-expander},
@ref{get-setf-expansion},
@ref{Generalized Reference},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading Notes:

@param{forms} must include provision
for returning the correct value (the value
or values
of @param{store-variable}).
This is
handled by @param{forms} rather than by @symbolref{defsetf, SYM} because
in many cases this value can be returned at no extra cost, by calling a
function that simultaneously stores into the @term{place} and
returns the correct value.

A @symbolref{setf, SYM} of a call on @param{access-fn} also evaluates
all of @param{access-fn}'s arguments; it cannot treat any of them specially.
This means that @symbolref{defsetf, SYM}
cannot be used to describe how to store into
a @term{generalized reference} to a byte, such as @f{(ldb field reference)}.
@symbolref{define-setf-expander, SYM}
is used to handle situations that
do not fit the restrictions imposed by @symbolref{defsetf, SYM}
and gives the user additional control.



@node define-setf-expander
@syindexanchor{define-setf-expander, SYM}
@subsection define-setf-expander (Macro)
@cindex define-setf-expander



@subsubheading Syntax:

@DefmacWithValuesNewline{define-setf-expander, @vtop{@hbox{access-fn lambda-list} @hbox{@DeclsAndDoc{} @starparam{form}}}, access-fn}

@subsubheading Arguments and Values:

@param{access-fn}---a @term{symbol} that @term{names} a @term{function} or @term{macro}.

@param{lambda-list}---@term{macro lambda list}.

@param{declaration}---a @t{declare} @term{expression}; @noeval{}.

@param{documentation}---a @term{string}; @noeval{}.

@param{forms}---an @term{implicit progn}.

@subsubheading Description:

@symbolref{define-setf-expander, SYM} specifies the means by which @symbolref{setf, SYM}
updates a @term{place} that is referenced by @param{access-fn}.

When @symbolref{setf, SYM} is given a @term{place} that is
specified in terms of @param{access-fn} and a new value for the
@term{place}, it is expanded into a form that performs
the appropriate update.

The @param{lambda-list} supports destructuring.
See @ref{Macro Lambda Lists}.

@param{Documentation} is attached to @param{access-fn} as a @term{documentation string}
of kind @t{setf}.

@param{Forms} constitute the body of the
@term{setf expander}
definition and must compute the @term{setf expansion} for a call on @symbolref{setf, SYM}
that references the @term{place} by means of the given
@param{access-fn}.
The @term{setf expander} function is defined in the same @term{lexical environment}
in which the @symbolref{define-setf-expander, SYM} @term{form} appears.
While @param{forms} are being executed,
the variables in @param{lambda-list} are bound to parts of the @term{place} @term{form}.
The body @param{forms} (but not the @param{lambda-list})
in a @symbolref{define-setf-expander, SYM} @term{form} are implicitly enclosed in a
@term{block} whose name is
@param{access-fn}.

The evaluation of @param{forms} must result in the five values
described in @ref{Setf Expansions}.

If a @symbolref{define-setf-expander, SYM} @term{form} appears as a @term{top level form},
the @term{compiler} must make the @term{setf expander} available so that
it may be used to expand calls to @symbolref{setf, SYM} later on in the @term{file}.
@term{sequences} must ensure that the @param{forms} can be evaluated
at compile time if the @param{access-fn} is used in a @term{place}
later in the same @term{file}.
The @term{compiler} must make these @term{setf expanders} available to
compile-time calls to @symbolref{get-setf-expansion, SYM} when its @param{environment}
argument is a value received as the @term{environment parameter} of a @term{macro}.

@subsubheading Examples:
@lisp
 (defun lastguy (x) (car (last x))) @EV{} LASTGUY
 (define-setf-expander lastguy (x &environment env)
   "Set the last element in a list to the given value."
   (multiple-value-bind (dummies vals newval setter getter)
       (get-setf-expansion x env)
     (let ((store (gensym)))
       (values dummies
               vals
               `(,store)
               `(progn (rplaca (last ,getter) ,store) ,store)
               `(lastguy ,getter))))) @EV{} LASTGUY
 (setq a (list 'a 'b 'c 'd)
       b (list 'x)
       c (list 1 2 3 (list 4 5 6))) @EV{} (1 2 3 (4 5 6))
 (setf (lastguy a) 3) @EV{} 3
 (setf (lastguy b) 7) @EV{} 7
 (setf (lastguy (lastguy c)) 'lastguy-symbol) @EV{} LASTGUY-SYMBOL
 a @EV{} (A B C 3)
 b @EV{} (7)
 c @EV{} (1 2 3 (4 5 LASTGUY-SYMBOL))
@end lisp


@lisp
;;; Setf expander for the form (LDB bytespec int).
;;; Recall that the int form must itself be suitable for SETF.
 (define-setf-expander ldb (bytespec int &environment env)
   (multiple-value-bind (temps vals stores
                          store-form access-form)
       (get-setf-expansion int env);Get setf expansion for int.
     (let ((btemp (gensym))     ;Temp var for byte specifier.
           (store (gensym))     ;Temp var for byte to store.
           (stemp (first stores))) ;Temp var for int to store.
       (if (cdr stores) (error "Can't expand this."))
;;; Return the setf expansion for LDB as five values.
       (values (cons btemp temps)       ;Temporary variables.
               (cons bytespec vals)     ;Value forms.
               (list store)             ;Store variables.
               @bq{}(let ((,stemp (dpb ,store ,btemp ,access-form)))
                  ,store-form
                  ,store)               ;Storing form.
               @bq{}(ldb ,btemp ,access-form) ;Accessing form.
              ))))
@end lisp


@subsubheading See Also:

@ref{setf},
@ref{defsetf},
@ref{documentation},
@ref{get-setf-expansion},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading Notes:

@symbolref{define-setf-expander, SYM} differs from the long form of @symbolref{defsetf, SYM}
in that while the body is being executed the @term{variables}
in @param{lambda-list} are bound to parts of the @term{place} @term{form},
not to temporary variables that will be bound to the values of such parts.
In addition, @symbolref{define-setf-expander, SYM} does not have @symbolref{defsetf, SYM}'s
restriction that @param{access-fn} must be a @term{function}
or a function-like @term{macro}; an arbitrary @symbolref{defmacro, SYM} destructuring
pattern is permitted in @param{lambda-list}.



@node get-setf-expansion
@syindexanchor{get-setf-expansion, SYM}
@subsection get-setf-expansion (Function)
@cindex get-setf-expansion



@subsubheading Syntax:

@DefunWithValuesNewline{get-setf-expansion, place @opt{} environment, vars\, vals\, store-vars\, writer-form\, reader-form}

@subsubheading Arguments and Values:

@param{place}---a @term{place}.

@param{environment}---an @term{environment} @term{object}.

@param{vars, vals, store-vars, writer-form, reader-form}---a @term{setf expansion}.

@subsubheading Description:

Determines
five values constituting the @term{setf expansion} for @param{place}
in @param{environment}; see @ref{Setf Expansions}.

If @param{environment} is not supplied or @nil{},
the environment is the @term{null lexical environment}.

@subsubheading Examples:

@lisp
 (get-setf-expansion 'x)
@EV{} NIL, NIL, (#:G0001), (SETQ X #:G0001), X
@end lisp


@lisp
;;; This macro is like POP

 (defmacro xpop (place &environment env)
   (multiple-value-bind (dummies vals new setter getter)
                        (get-setf-expansion place env)
      `(let* (,@@(mapcar #'list dummies vals) (,(car new) ,getter))
         (if (cdr new) (error "Can't expand this."))
         (prog1 (car ,(car new))
                (setq ,(car new) (cdr ,(car new)))
                ,setter))))

 (defsetf frob (x) (value)
     `(setf (car ,x) ,value)) @EV{} FROB
;;; The following is an error; an error might be signaled at macro expansion time
 (flet ((frob (x) (cdr x)))  ;Invalid
   (xpop (frob z)))

@end lisp


@subsubheading See Also:

@ref{defsetf},
@ref{define-setf-expander},
@ref{setf}

@subsubheading Notes:

Any @term{compound form} is a valid @term{place},
since any @term{compound form} whose @term{operator} @param{f} has no @term{setf expander}
are expanded into a call to @f{(setf @param{f})}.



@node setf; psetf
@syindexanchor{setf, SYM}
@syindexanchor{psetf, SYM}
@subsection setf, psetf (Macro)
@cindex setf
@cindex psetf
@anchor{setf}
@anchor{psetf}


@subsubheading Syntax:

@DefmacWithValues{setf, @stardown{pair}, @starparam{result}}
@DefmacWithValues{psetf, @stardown{pair}, @nil{}}

@auxbnf{pair, place newvalue}

@subsubheading Arguments and Values:

@param{place}---a @term{place}.

@param{newvalue}---a @term{form}.

@param{results}---the @term{multiple values}@sub{2}
returned by the storing form for the last @param{place},
or @nil{}@spc{}if there are no @param{pairs}.

@subsubheading Description:

@symbolref{setf, SYM} changes the @term{value} of @param{place} to be @param{newvalue}.

@f{(setf place newvalue)}
expands into an update form that stores the
result
of evaluating
@param{newvalue} into the location referred to by @param{place}.
Some @param{place} forms
involve uses of accessors that take optional arguments.
Whether those optional arguments are permitted by
@symbolref{setf, SYM}, or what their use
is, is up to the
@symbolref{setf, SYM} expander function and is not under the control
of @symbolref{setf, SYM}.
The documentation for any @term{function}
that accepts @keyref{optional}, @keyref{rest},
or @tt{&key} arguments and that
claims to be usable with @symbolref{setf, SYM} must specify
how those arguments are treated.

If more than one @param{pair} is supplied,
the @param{pairs} are processed sequentially; that is,

@lisp
 (setf place-1 newvalue-1
       place-2 newvalue-2
       ...
       place-N newvalue-N)
@end lisp

is precisely equivalent to

@lisp
 (progn (setf place-1 newvalue-1)
        (setf place-2 newvalue-2)
        ...
        (setf place-N newvalue-N))
@end lisp

For @symbolref{psetf, SYM},
if more than one @param{pair} is supplied then the assignments of new values to places are
done in parallel.  More precisely, all @term{subforms} (in both the @param{place}
and @param{newvalue} @term{forms}) that are to be evaluated
are evaluated from left to right; after all evaluations have been performed,
all of the assignments are performed in an unpredictable order.

For detailed treatment of the expansion of @symbolref{setf, SYM} and @symbolref{psetf, SYM},
see @ref{Kinds of Places}.

@subsubheading Examples:

@lisp
 (setq x (cons 'a 'b) y (list 1 2 3)) @EV{} (1 2 3)
 (setf (car x) 'x (cadr y) (car x) (cdr x) y) @EV{} (1 X 3)
 x @EV{} (X 1 X 3)
 y @EV{} (1 X 3)
 (setq x (cons 'a 'b) y (list 1 2 3)) @EV{} (1 2 3)
 (psetf (car x) 'x (cadr y) (car x) (cdr x) y) @EV{} NIL
 x @EV{} (X 1 A 3)
 y @EV{} (1 A 3)
@end lisp


@subsubheading Affected By:

@symbolref{define-setf-expander, SYM},
@symbolref{defsetf, SYM},
@symbolref{*macroexpand-hook*, SYM}

@subsubheading See Also:

@ref{define-setf-expander},
@ref{defsetf},
@ref{macroexpand-1},
@ref{rotatef},
@ref{shiftf},
@ref{Generalized Reference}


@node shiftf
@syindexanchor{shiftf, SYM}
@subsection shiftf (Macro)
@cindex shiftf


@subsubheading Syntax:

@DefmacWithValues{shiftf, @plusparam{place} newvalue, old-value-1}

@subsubheading Arguments and Values:

@param{place}---a @term{place}.

@param{newvalue}---a @term{form}; @eval{}.

@param{old-value-1}---an @term{object} (the old @term{value} of the first @param{place}).

@subsubheading Description:

@symbolref{shiftf, SYM} modifies the values of each
@param{place} by storing @param{newvalue}
into the last @param{place}, and shifting the
values of the second through the last @param{place}
into the remaining @param{places}.

If @param{newvalue} produces more values than there
are store variables, the extra values are ignored. If @param{newvalue}
produces fewer values than there are store variables, the missing values
are set to @nil{}.

In the form @tt{(shiftf @i{place1} @i{place2} ... @i{placen} @i{newvalue})},
the values in @i{place1} through @i{placen} are @term{read} and saved,
and @i{newvalue} is evaluated, for a total of @f{n}+1 values in all.
Values 2 through @f{n}+1 are then stored into @i{place1} through @i{placen}, respectively.
It is as if all the @param{places} form a shift register; the @param{newvalue}
is shifted in from the right, all values shift over to the left one place,
and the value shifted out of @i{place1} is returned.

For information about the @term{evaluation} of @term{subforms} of @param{places},
see @ref{Evaluation of Subforms to Places}.

@subsubheading Examples:

@lisp
 (setq x (list 1 2 3) y 'trash) @EV{} TRASH
 (shiftf y x (cdr x) '(hi there)) @EV{} TRASH
 x @EV{} (2 3)
 y @EV{} (1 HI THERE)

 (setq x (list 'a 'b 'c)) @EV{} (A B C)
 (shiftf (cadr x) 'z) @EV{} B
 x @EV{} (A Z C)
 (shiftf (cadr x) (cddr x) 'q) @EV{} Z
 x @EV{} (A (C) . Q)
 (setq n 0) @EV{} 0
 (setq x (list 'a 'b 'c 'd)) @EV{} (A B C D)
 (shiftf (nth (setq n (+ n 1)) x) 'z) @EV{} B
 x @EV{} (A Z C D)
@end lisp


@subsubheading Affected By:

@symbolref{define-setf-expander, SYM},
@symbolref{defsetf, SYM},
@symbolref{*macroexpand-hook*, SYM}

@subsubheading See Also:

@ref{Generalized Reference}

@subsubheading Notes:

The effect of
@f{(shiftf @param{place1} @param{place2} ... @param{placen} @param{newvalue})}
is roughly equivalent to

@lisp
 (let ((var1 @param{place1})
       (var2 @param{place2})
       ...
       (varn @param{placen})
       (var0 @param{newvalue}))
   (setf @param{place1} var2)
   (setf @param{place2} var3)
   ...
   (setf @param{placen} var0)
   var1)
@end lisp

except that the latter would evaluate any @term{subforms}
of each @f{place} twice, whereas @symbolref{shiftf, SYM} evaluates them once.
For example,

@lisp
 (setq n 0) @EV{} 0
 (setq x (list 'a 'b 'c 'd)) @EV{} (A B C D)
 (prog1 (nth (setq n (+ n 1)) x)
        (setf (nth (setq n (+ n 1)) x) 'z)) @EV{} B
 x @EV{} (A B Z D)
@end lisp



@node rotatef
@syindexanchor{rotatef, SYM}
@subsection rotatef (Macro)
@cindex rotatef


@subsubheading Syntax:

@DefmacWithValues{rotatef, @starparam{place}, @nil{}}

@subsubheading Arguments and Values:

@param{place}---a @term{place}.

@subsubheading Description:

@symbolref{rotatef, SYM} modifies the values of each @param{place} by
rotating values from one @param{place} into another.

If a @param{place} produces more values than there
are store variables, the extra values are ignored. If a @param{place}
produces fewer values than there are store variables, the missing values
are set to @nil{}.

In the form @f{(rotatef @i{place1} @i{place2} ... @i{placen})},
the values in @i{place1} through @i{placen} are @term{read} and @i{written}.
Values 2 through @i{n}
and value 1 are then stored into @i{place1} through @i{placen}.
It is as if all the places form an end-around shift register
that is rotated one place to the left, with the value of @i{place1}
being shifted around the end to @i{placen}.

For information about the @term{evaluation} of @term{subforms} of @param{places},
see @ref{Evaluation of Subforms to Places}.

@subsubheading Examples:
@lisp
 (let ((n 0)
        (x (list 'a 'b 'c 'd 'e 'f 'g)))
    (rotatef (nth (incf n) x)
             (nth (incf n) x)
             (nth (incf n) x))
    x) @EV{} (A C D B E F G)
@end lisp


@subsubheading See Also:

@ref{define-setf-expander},
@ref{defsetf},
@ref{setf},
@ref{shiftf},
@ref{*macroexpand-hook*},
@ref{Generalized Reference}

@subsubheading Notes:

The effect of
@f{(rotatef @param{place1} @param{place2} ... @param{placen})}
is roughly equivalent to

@lisp
 (psetf @param{place1} @param{place2}
        @param{place2} @param{place3}
        ...
        @param{placen} @param{place1})
@end lisp

except that the latter would evaluate any @term{subforms}
of each @f{place} twice, whereas @symbolref{rotatef, SYM} evaluates them once.


@node control-error
@syindexanchor{control-error, SYM}
@subsection control-error (Condition Type)
@cindex control-error


@subsubheading Class Precedence List:
@symbolref{control-error, SYM},
@symbolref{error, CT},
@symbolref{serious-condition, SYM},
@symbolref{condition, SYM},
@symbolref{t, SC}

@subsubheading Description:

@Thetype{control-error} consists of error conditions that result from
invalid dynamic transfers of control in a program.  The errors that
result from giving @symbolref{throw, SYM} a tag that is not active or from
giving @symbolref{go, SYM} or @symbolref{return-from, SYM} a tag that is no longer
dynamically available are @oftype{control-error}.


@node program-error
@syindexanchor{program-error, SYM}
@subsection program-error (Condition Type)
@cindex program-error


@subsubheading Class Precedence List:
@symbolref{program-error, SYM},
@symbolref{error, CT},
@symbolref{serious-condition, SYM},
@symbolref{condition, SYM},
@symbolref{t, SC}

@subsubheading Description:

@Thetype{program-error}
consists of error conditions related to incorrect program syntax.  The
errors that result from naming a @term{go tag} or a @term{block tag}
that is not lexically apparent are @oftype{program-error}.


@node undefined-function
@syindexanchor{undefined-function, SYM}
@subsection undefined-function (Condition Type)
@cindex undefined-function


@subsubheading Class Precedence List:
@symbolref{undefined-function, SYM},
@symbolref{cell-error, SYM},
@symbolref{error,CT},
@symbolref{serious-condition, SYM},
@symbolref{condition, SYM},
@symbolref{t, SC}

@subsubheading Description:

@Thetype{undefined-function} consists of @term{error} @term{conditions}
that represent attempts to @term{read} the definition of an @term{undefined function}.

The name of the cell (see @symbolref{cell-error, SYM}) is the @term{function name}
which was @term{funbound}.

@subsubheading See Also:

@ref{cell-error-name}