dotfiles/gcl-info/chap-5.texi

@node Data and Control Flow, Iteration, Types and Classes, Top
@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, Transfer of Control to an Exit Point, Data and Control Flow, Data and Control Flow
@section Generalized Reference

@c including concept-places

@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, Kinds of Places, Generalized Reference, Generalized Reference
@subsection Overview of Places and Generalized Reference

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

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

@group
@noindent
@w{  Access function   Update Function   Update using @b{setf}              }
@w{  @t{x}                 @t{(setq x datum)}    @t{(setf x datum)}                 }
@w{  @t{(car x)}           @t{(rplaca x datum)}  @t{(setf (car x) datum)}           }
@w{  @t{(symbol-value x)}  @t{(set x datum)}     @t{(setf (symbol-value x) datum)}  }

@noindent
@w{                     Figure 5--1: Examples of setf                   }

@end group

Figure 5--2 shows @i{operators} relating to
@i{places} and @i{generalized reference}.

@group
@noindent
@w{  assert                defsetf             push     }
@w{  ccase                 get-setf-expansion  remf     }
@w{  ctypecase             getf                rotatef  }
@w{  decf                  incf                setf     }
@w{  define-modify-macro   pop                 shiftf   }
@w{  define-setf-expander  psetf                        }

@noindent
@w{  Figure 5--2: Operators relating to places and generalized reference.}

@end group

Some of the @i{operators} above manipulate @i{places}
and some manipulate @i{setf expanders}.
A @i{setf expansion} can be derived from any @i{place}.

New @i{setf expanders} can be defined by using @b{defsetf} 
and @b{define-setf-expander}.

@menu
* Evaluation of Subforms to Places::  
* Examples of Evaluation of Subforms to Places::  
* Setf Expansions::		
* Examples of Setf Expansions::	 
@end menu

@node Evaluation of Subforms to Places, Examples of Evaluation of Subforms to Places, Overview of Places and Generalized Reference, Overview of Places and Generalized Reference
@subsubsection Evaluation of Subforms to Places

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

@table @asis

@item 1.  
The evaluation ordering of @i{subforms} within a @i{place}
is determined by the order specified by the second value returned by

@b{get-setf-expansion}. 

For all @i{places} defined by this specification
(@i{e.g.}, @b{getf}, @b{ldb}, ...),
this order of evaluation is left-to-right.

@ITindex{order of evaluation}

@ITindex{evaluation order}

When a @i{place} is derived from a macro expansion,
this rule is applied after the macro is expanded to find the appropriate @i{place}. 

@i{Places} defined by using @b{defmacro} or

@b{define-setf-expander}

use the evaluation order defined by those definitions.
For example, consider the following:

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

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

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

@item 2.  

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

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

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

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

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

@item 4.  
For @b{assert}, the order of evaluation of the generalized 
references is not specified.
@ITindex{order of evaluation}

@ITindex{evaluation order}

@end table

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

@node Examples of Evaluation of Subforms to Places, Setf Expansions, Evaluation of Subforms to Places, Overview of Places and Generalized Reference
@subsubsection Examples of Evaluation of Subforms to Places

@example
 (let ((ref2 (list '())))
   (push (progn (princ "1") 'ref-1)
         (car (progn (princ "2") ref2)))) 
@t{ |> } 12
@result{}  (REF1)

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

@b{push} first evaluates @t{(setq x (list 'a)) @result{}  (a)},
 then evaluates @t{(setq x (list 'b)) @result{}  (b)},
 then modifies the @i{car} of this latest value to be @t{((a) . b)}.

@node Setf Expansions, Examples of Setf Expansions, Examples of Evaluation of Subforms to Places, Overview of Places and Generalized Reference
@subsubsection Setf Expansions

Sometimes it is possible to avoid evaluating @i{subforms} of a 
@i{place} multiple times or in the wrong order.  A

@i{setf expansion}

for a given access form can be expressed as an ordered collection of five @i{objects}:

@table @asis

@item @b{List of temporary variables}  
a list of symbols naming temporary variables to be bound
sequentially, as if by @b{let*}, to @i{values} 
resulting from value forms.

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

@item @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
@i{place}.

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

@item @b{Accessing form}  
a @i{form} which can reference the temporary variables,
and which returns the @i{value} of the @i{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 @b{setf} in parallel via
@b{psetf}, @b{shiftf}, and @b{rotatef}.  
Because of this, the 

@i{setf expander}

must produce new temporary 
and store variable names every time.  For examples of how to do this,
see @b{gensym}.

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

@node Examples of Setf Expansions,  , Setf Expansions, Overview of Places and Generalized Reference
@subsubsection Examples of Setf Expansions

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

For a variable @i{x}:

@group
@noindent
@w{  @t{()}              ;list of temporary variables  }
@w{  @t{()}              ;list of value forms          }
@w{  @t{(g0001)}         ;list of store variables      }
@w{  @t{(setq @i{x} g0001)}  ;storing form                 }
@w{  @i{x}               ;accessing form               }

@noindent
@w{  Figure 5--3: Sample Setf Expansion of a Variable}

@end group

For @t{(car @i{exp})}:

@group
@noindent
@w{  @t{(g0002)}                             ;list of temporary variables  }
@w{  @t{(@i{exp})}                               ;list of value forms          }
@w{  @t{(g0003)}                             ;list of store variables      }
@w{  @t{(progn (rplaca g0002 g0003) g0003)}  ;storing form                 }
@w{  @t{(car g0002)}                         ;accessing form               }

@noindent
@w{           Figure 5--4: Sample Setf Expansion of a CAR Form         }

@end group

For @t{(subseq @i{seq} @i{s} @i{e})}:

@group
@noindent
@w{  @t{(g0004 g0005 g0006)}         ;list of temporary variables  }
@w{  @t{(@i{seq} @i{s} @i{e})}                   ;list of value forms          }
@w{  @t{(g0007)}                     ;list of store variables      }
@w{  @t{(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007)} }
@w{                              ;storing form                 }
@w{  @t{(subseq g0004 g0005 g0006)}  ; accessing form              }

@noindent
@w{     Figure 5--5: Sample Setf Expansion of a SUBSEQ Form    }

@end group

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

@group
@noindent
@w{  @t{(g0001 g0002)}            ;list of temporary variables  }
@w{  @t{(@i{bs} @i{exp})}                 ;list of value forms          }
@w{  @t{(g0003)}                  ;list of store variables      }
@w{  @t{(progn (rplaca g0002 (dpb g0003 g0001 (car g0002))) g0003)} }
@w{                           ;storing form                 }
@w{  @t{(ldb g0001 (car g0002))}  ; accessing form              }

@noindent
@w{     Figure 5--6: Sample Setf Expansion of a LDB Form    }

@end group

@node Kinds of Places, Treatment of Other Macros Based on SETF, Overview of Places and Generalized Reference, Generalized Reference
@subsection Kinds of Places

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

@menu
* Variable Names as Places::	
* Function Call Forms as Places::  
* VALUES Forms as Places::	
* THE Forms as Places::		
* APPLY Forms as Places::	
* Setf Expansions and Places::	
* Macro Forms as Places::	
* Symbol Macros as Places::	
* Other Compound Forms as Places::  
@end menu

@node Variable Names as Places, Function Call Forms as Places, Kinds of Places, Kinds of Places
@subsubsection Variable Names as Places

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

@node Function Call Forms as Places, VALUES Forms as Places, Variable Names as Places, Kinds of Places
@subsubsection Function Call Forms as Places

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

@table @asis

@item @t{*}  
A function call form whose first element is the name of
any one of the functions in Figure 5--7.

[Editorial Note by 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.]

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

@noindent
@w{       Figure 5--7: Functions that setf can be used with---1      }

@end group

In the case of @b{subseq}, the replacement value must be a @i{sequence}
whose elements might be contained by the sequence argument to @b{subseq},
but does not have to be a @i{sequence} of the same @i{type} 
as the @i{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 @b{replace}.

@item @t{*}  
A function call form whose first element is the name of
a selector function constructed by @b{defstruct}.

The function name must refer to the global function definition,
rather than a locally defined @i{function}.

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

@group
@noindent
@w{  Function name  Argument that is a @i{place}  Update function used      }
@w{  @b{ldb}            second                    @b{dpb}                       }
@w{  @b{mask-field}     second                    @b{deposit-field}             }
@w{  @b{getf}           first                     @i{implementation-dependent}  }

@noindent
@w{         Figure 5--8: Functions that setf can be used with---2       }

@end group

During the @b{setf} expansion of these @i{forms}, it is necessary to call 

@b{get-setf-expansion} 

in order to figure out how the inner, nested generalized variable must be treated.  

The information from

@b{get-setf-expansion}

is used as follows.
@table @asis

@item @b{ldb}  
In a form such as:

@t{(setf (ldb @i{byte-spec} @i{place-form}) @i{value-form})}

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

Thus this @b{setf} should generate code to do the following:

@table @asis

@item 1.  
Evaluate @i{byte-spec} (and bind it into a temporary variable).
@item 2.  
Bind the temporary variables for @i{place-form}.
@item 3.  
Evaluate @i{value-form}  (and bind 

its value or values into the store variable).

@item 4.  
Do the @i{read} from @i{place-form}.
@item 5.  
Do the @i{write} into @i{place-form} with 
the given bits of the @i{integer}
       fetched in step 4 replaced with the value from step 3.
@end table

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

@example
 (setq integer #x69) @result{}  #x69
 (rotatef (ldb (byte 4 4) integer) 
          (ldb (byte 4 0) integer))
 integer @result{}  #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 example

@item @b{mask-field}  
This case is the same as @b{ldb} in all essential aspects.

@item @b{getf}  
In a form such as:

@t{(setf (getf @i{place-form} @i{ind-form}) @i{value-form})}

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

    Thus this @b{setf} should generate code to do the following:
@table @asis

@item 1.  
Bind the temporary variables for @i{place-form}.
@item 2.  
Evaluate @i{ind-form} (and bind it into a temporary variable).
@item 3.  
Evaluate @i{value-form} (and bind 

its value or values into the store variable).

@item 4.  
Do the @i{read} from @i{place-form}.
@item 5.  
Do the @i{write} into @i{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 table

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

For example:

@example
 (setq s (setq r (list (list 'a 1 'b 2 'c 3)))) @result{}  ((a 1 b 2 c 3))
 (setf (getf (car r) 'b) 
       (progn (setq r nil) 6)) @result{}  6
 r @result{}  NIL
 s @result{}  ((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 example

@end table

@end table

@node VALUES Forms as Places, THE Forms as Places, Function Call Forms as Places, Kinds of Places
@subsubsection VALUES Forms as Places

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

A form such as

@t{(setf (values @i{place-1} \dots @i{place-n}) @i{values-form})}

does the following:

@table @asis

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

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

@node THE Forms as Places, APPLY Forms as Places, VALUES Forms as Places, Kinds of Places
@subsubsection THE Forms as Places

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

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

is processed as if it were

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

@node APPLY Forms as Places, Setf Expansions and Places, THE Forms as Places, Kinds of Places
@subsubsection APPLY Forms as Places

The following situations involving @b{setf} of @b{apply} must be supported:

@table @asis

@item @t{*}  
@t{(setf (apply #'aref @i{array}
				        @{@i{subscript}@}{*}
					@i{more-subscripts})
			  @i{new-element})}
@item @t{*}  
@t{(setf (apply #'bit @i{array} 
				       @{@i{subscript}@}{*}
				       @i{more-subscripts})
			  @i{new-element})}
@item @t{*}  
@t{(setf (apply #'sbit @i{array} 
					@{@i{subscript}@}{*}
					@i{more-subscripts}) 
			  @i{new-element})}
@end table

In all three cases, the @i{element} of @i{array} designated
by the concatenation of @i{subscripts} and @i{more-subscripts}
(@i{i.e.}, the same @i{element} which would be @i{read} by the call to
     @i{apply} if it were not part of a @b{setf} @i{form})
is changed to have the @i{value} given by @i{new-element}.

For these usages, the function name (@b{aref}, @b{bit}, or @b{sbit})
must refer to the global function definition, rather than a locally defined
@i{function}.

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

If a user-defined @i{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 @i{subforms}:

@example
 (setf (apply #'@i{name} @{@i{arg}@}{*}) @i{val})
 @equiv{} (apply #'(setf @i{name}) @i{val} @{@i{arg}@}{*})
@end example

@node Setf Expansions and Places, Macro Forms as Places, APPLY Forms as Places, Kinds of Places
@subsubsection Setf Expansions and Places

Any @i{compound form} for which the @i{operator} has a

@i{setf expander}

defined can be used as a @i{place}.

The 
@i{operator}
must refer to the global function definition,
rather than a locally defined @i{function} or @i{macro}.

@node Macro Forms as Places, Symbol Macros as Places, Setf Expansions and Places, Kinds of Places
@subsubsection Macro Forms as Places

A @i{macro form} can be used as a @i{place}, 
in which case @r{Common Lisp} expands the @i{macro form}

as if by @b{macroexpand-1}

and then uses the @i{macro expansion} in place of the original @i{place}.

Such @i{macro expansion} is attempted only after exhausting all other possibilities
other than expanding into a call to a function named @t{(setf @i{reader})}.

@node Symbol Macros as Places, Other Compound Forms as Places, Macro Forms as Places, Kinds of Places
@subsubsection Symbol Macros as Places

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

@node Other Compound Forms as Places,  , Symbol Macros as Places, Kinds of Places
@subsubsection Other Compound Forms as Places

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

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

expands into a form with the same effect and value as

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

A @i{function} named @t{(setf @i{f})} must return its first argument
as its only value in order to preserve the semantics of @b{setf}.

@node Treatment of Other Macros Based on SETF,  , Kinds of Places, Generalized Reference
@subsection Treatment of Other Macros Based on SETF

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

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

@example
 (@i{operator} @{@i{preceding-form}@}{*} @i{place} @{@i{following-form}@}{*})
@end example

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

@table @asis

@item 1.  
@i{Evaluate} each of the @i{preceding-forms}, in left-to-right order.
@item 2.  
@i{Evaluate} the @i{subforms} of the @i{place},
 in the order specified by the second value of the @i{setf expansion}
 for that @i{place}.
@item 3.  
@i{Evaluate} each of the @i{following-forms}, in left-to-right order.
@item 4.  
@i{Read} the old value from @i{place}.
@item 5.  
Compute the new value.
@item 6.  
Store the new value into @i{place}.
@end table

@group
@noindent
@w{  decf  pop   pushnew  }
@w{  incf  push  remf     }

@noindent
@w{  Figure 5--9: Read-Modify-Write Macros}

@end group

@c end of including concept-places

@node Transfer of Control to an Exit Point, Data and Control Flow Dictionary, Generalized Reference, Data and Control Flow
@section Transfer of Control to an Exit Point

@c including concept-exits

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

@table @asis

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

@item 2.  
The cleanup clauses of any intervening @b{unwind-protect} clauses
 are evaluated.

@item 3.  
Intervening dynamic @i{bindings} of @b{special} variables,
 @i{catch tags}, @i{condition handlers}, and @i{restarts}
 are undone.

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

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 @i{exit point} whose @i{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 @b{unwind-protect}
see the same dynamic @i{bindings} 
of variables and @i{catch tags} as were
visible when the @b{unwind-protect} was entered.

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

@c end of including concept-exits

@node Data and Control Flow Dictionary,  , Transfer of Control to an Exit Point, Data and Control Flow
@section Data and Control Flow Dictionary

@c including dict-flow

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

@node apply, defun, Data and Control Flow Dictionary, Data and Control Flow Dictionary
@subsection apply                                                            [Function]

@code{apply}  @i{function {&rest} args^+} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{function}---a @i{function designator}.

@i{args}---a @i{spreadable argument list designator}.

@i{results}---the @i{values} returned by @i{function}.

@subsubheading  Description::

@i{Applies} the @i{function} to the @i{args}.

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

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

@subsubheading  Examples::

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

 (defparameter *some-list* '(a b c))
 (defun strange-test (&rest x) (eq x *some-list*))
 (apply #'strange-test *some-list*) @result{}  @i{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 example

@example
 (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)
    @result{}  #(A B C D A B C D)
@end example

@subsubheading  See Also::

@ref{funcall}
,
@ref{fdefinition}
,
@b{function},
@ref{Evaluation},
@ref{APPLY Forms as Places}

@node defun, fdefinition, apply, Data and Control Flow Dictionary
@subsection defun                                                               [Macro]

@code{defun}  @i{function-name lambda-list {[[@{@i{declaration}@}{*} | @i{documentation}]]} @{@i{form}@}{*}}@*
   @result{}  @i{function-name}

@subsubheading  Arguments and Values:: 

@i{function-name}---a @i{function name}.

@i{lambda-list}---an @i{ordinary lambda list}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{documentation}---a @i{string}; not evaluated.

@i{forms}---an @i{implicit progn}.

@i{block-name}---the @i{function block name} of the @i{function-name}.

@subsubheading  Description::

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

@b{defun} implicitly puts a @b{block} named @i{block-name}
around the body @i{forms} 

(but not the @i{forms} in the @i{lambda-list})

of the @i{function} defined.

@i{Documentation} is attached as a @i{documentation string} 
    to @i{name} (as kind @b{function})
and to the @i{function} @i{object}.

Evaluating @b{defun} causes @i{function-name} to be a global name
for the @i{function} specified by the @i{lambda expression}

@example
 (lambda @i{lambda-list}
   {[[@{@i{declaration}@}{*} | @i{documentation}]]}
   (block @i{block-name} @{@i{form}@}{*}))
@end example

processed in the @i{lexical environment} in which @b{defun} was executed.

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

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

@subsubheading  Examples::

@example
 (defun recur (x)
  (when (> x 0)
    (recur (1- x)))) @result{}  RECUR 
 (defun ex (a b &optional c (d 66) &rest keys &key test (start 0))
    (list a b c d keys test start)) @result{}  EX 
 (ex 1 2) @result{}  (1 2 NIL 66 NIL NIL 0)
 (ex 1 2 3 4 :test 'equal :start 50) 
@result{}  (1 2 3 4 (:TEST EQUAL :START 50) EQUAL 50)
 (ex :test 1 :start 2) @result{}  (: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))) @result{}  DISCRIMINANT
 (discriminant 1 2/3 -2) @result{}  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)))) @result{}  CAREFUL-DISCRIMINANT
 (careful-discriminant 1 2/3 -2) @result{}  76/9
@end example

@subsubheading  See Also::

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

@subsubheading  Notes::
@b{return-from} can be used to return
prematurely from a @i{function} defined by @b{defun}.

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

@node fdefinition, fboundp, defun, Data and Control Flow Dictionary
@subsection fdefinition                                                      [Accessor]

@code{fdefinition}  @i{function-name} @result{}  @i{definition}

(setf (@code{         fdefinition} @i{function-name}) new-definition)@*

@subsubheading  Arguments and Values::

@i{function-name}---a @i{function name}.

In the non-@b{setf} case, 
the @i{name} must be @i{fbound} in the @i{global environment}.

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

@i{new-definition}---a @i{function}.

@subsubheading  Description::

@b{fdefinition} @i{accesses} the current global function definition
named by @i{function-name}.  The definition may be a
@i{function} or may be an @i{object} representing a 
@i{special form} or @i{macro}.

The value returned by @b{fdefinition} when @b{fboundp} returns true
but the @i{function-name} denotes a @i{macro} or 
@i{special form} is not well-defined, but @b{fdefinition} does not signal an error. 

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{function-name} is not a @i{function name}.

An error of @i{type} @b{undefined-function} is signaled 
in the non-@b{setf} case if @i{function-name} is not @i{fbound}.

@subsubheading  See Also::

@ref{fboundp}
,
@ref{fmakunbound}
,
@ref{macro-function}
,

@ref{special-operator-p}
,

@ref{symbol-function}

@subsubheading  Notes::

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

@b{setf} can be used with 
@b{fdefinition} to replace a global function
definition when the @i{function-name}'s function definition 
does not represent a @i{special form}.

@b{setf} of @b{fdefinition} 
requires a @i{function} as the new value.
It is an error to set the @b{fdefinition} of a @i{function-name}
to a @i{symbol}, a @i{list}, or the value returned
by @b{fdefinition} on the name of a @i{macro} 
or @i{special form}.

@node fboundp, fmakunbound, fdefinition, Data and Control Flow Dictionary
@subsection fboundp                                                          [Function]

@code{fboundp}  @i{name} @result{}  @i{generalized-boolean}

@subsubheading  Pronunciation::

pronounced ,ef 'baund p\=e

@subsubheading  Arguments and Values::

@i{name}---a @i{function name}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{name} is @i{fbound};
otherwise, returns @i{false}.

@subsubheading  Examples::

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

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{name} is not a @i{function name}.

@subsubheading  See Also::

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

@subsubheading  Notes::

It is permissible to call @b{symbol-function} on any @i{symbol}
that is @i{fbound}.

@b{fboundp} is sometimes used to ``guard''
an access to the @i{function cell}, as in:
@example
(if (fboundp x) (symbol-function x))
@end example

Defining a @i{setf expander} @i{F} does not cause the @i{setf function}
@t{(setf @i{F})} to become defined.

@node fmakunbound, flet, fboundp, Data and Control Flow Dictionary
@subsection fmakunbound                                                      [Function]

@code{fmakunbound}  @i{name} @result{}  @i{name}

@subsubheading  Pronunciation::

    pronounced ,ef 'mak e n,baund 
 or pronounced ,ef 'm\=a k e n,baund 

@subsubheading  Arguments and Values::

@i{name}---a @i{function name}.

@subsubheading  Description::

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

@subsubheading  Examples::

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

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{name} is not a @i{function name}.

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

@subsubheading  See Also::

@ref{fboundp}
, 
@ref{makunbound}

@node flet, funcall, fmakunbound, Data and Control Flow Dictionary
@subsection flet, labels, macrolet                                   [Special Operator]

@code{flet}  @i{@r{(}@{{(}@i{function-name} 
				                  @i{lambda-list}
				      		  {[[@{@i{local-declaration}@}{*} 
				  | @i{local-documentation}]]}
				      		  @{@i{local-form}@}{*}@r{)}@}{*}@r{)}
			  @{@i{declaration}@}{*} @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@code{labels}  @i{@r{(}@{{(}@i{function-name} 
				                  @i{lambda-list}
				      		  {[[@{@i{local-declaration}@}{*} 
				  | @i{local-documentation}]]}
				      		  @{@i{local-form}@}{*}@r{)}@}{*}@r{)}
			  @{@i{declaration}@}{*} @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@code{macrolet}  @i{@r{(}@{{(}@i{name} 
				                  @i{lambda-list}
				      		  {[[@{@i{local-declaration}@}{*} 
				  | @i{local-documentation}]]}
				      		  @{@i{local-form}@}{*}@r{)}@}{*}@r{)}
			  @{@i{declaration}@}{*} @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values:: 

@i{function-name}---a @i{function name}.

@i{name}---a @i{symbol}.

@i{lambda-list}---a @i{lambda list}; 
		      for @b{flet} and @b{labels},
			 it is an @i{ordinary lambda list};
		      for @b{macrolet},
			 it is a @i{macro lambda list}.

@i{local-declaration}---a @b{declare} @i{expression}; not evaluated.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{local-documentation}---a @i{string}; not evaluated.

@i{local-forms}, @i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} of the @i{forms}.

@subsubheading  Description::

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

The body forms (but not the @i{lambda list})

of each @i{function} created by @b{flet} and @b{labels} 
and each @i{macro} created by @b{macrolet}
are enclosed in an @i{implicit block} whose name 
is the @i{function block name} of the @i{function-name} or @i{name}, 
as appropriate.

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

The scope of these @i{declarations} 
does not include the bodies of the macro expander
functions defined by @b{macrolet}.  

@table @asis

@item flet  
@b{flet} defines locally named @i{functions} and executes a series of
@i{forms} with these definition @i{bindings}.  Any number of
such local @i{functions} can be defined.  

The @i{scope} of the name @i{binding} encompasses only the body.
Within the
body of @b{flet}, 
@i{function-names} matching those defined
by @b{flet} 
refer to the locally defined @i{functions} 
rather than to
the global function definitions of the same name.

Also, within the scope of @b{flet}, 
global @i{setf expander} definitions of the @i{function-name}
defined by @b{flet} do not apply. 
Note that this applies to 
@t{(defsetf @i{f} ...)}, not
@t{(defmethod (setf @i{f}) ...)}.

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

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

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

@item macrolet  
@b{macrolet} 
establishes local @i{macro} definitions,
using the same format used by @b{defmacro}.

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

The macro-expansion functions defined by @b{macrolet} 
are defined in the 

@i{lexical environment} in which the @b{macrolet} form appears.
Declarations and @b{macrolet} and 
@b{symbol-macrolet} definitions
affect the local macro definitions in a @b{macrolet}, but the
consequences are undefined if the local macro definitions reference
any local @i{variable} or @i{function} @i{bindings} that are visible in that
@i{lexical environment}.

Any @i{local-documentation} is attached to the corresponding local @i{macro function}
as a @i{documentation string}.

@end table

@subsubheading  Examples::

@example
 (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.
                 ` (if flag (* ,z ,z) ,z)))
    ;The parameters x and flag are accessible here.
     (+ x
        (fudge x)
        (fudge (+ x 1)))))
 @equiv{}
 (defun foo (x flag)
   (+ x
      (if flag (* x x) x)
      (if flag (* (+ x 1) (+ x 1)) (+ x 1))))
@end example

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

@example
 (flet ((flet1 (n) (+ n n)))
    (flet ((flet1 (n) (+ 2 (flet1 n))))
      (flet1 2))) @result{}  6

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

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

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

@example
 (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)))))
@result{}  3.291173
@end example

@example
 (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))) @result{}  INTEGER-POWER
@end example

@example
 (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)))
@result{}  ((1) (2) (3) (4 2) (5) (6 3 2) (A APPLE APRICOT) (B BANANA) (C CHERRY))
@end example

@subsubheading  See Also::

@b{declare},
@ref{defmacro}
,
@ref{defun}
,
@ref{documentation; (setf documentation)}
,
@ref{let; let*}
,
@ref{Evaluation},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading  Notes::

It is not possible to define recursive @i{functions} with @b{flet}.
@b{labels} can be used to define mutually recursive @i{functions}.

If a @b{macrolet} @i{form} is a @i{top level form},
the body @i{forms} are also processed as @i{top level forms}.
See @ref{File Compilation}.

@node funcall, function (Special Operator), flet, Data and Control Flow Dictionary
@subsection funcall                                                          [Function]

@code{funcall}  @i{function {&rest} args} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{function}---a @i{function designator}.

@i{args}---@i{arguments} to the @i{function}.

@i{results}---the @i{values} returned by the @i{function}.

@subsubheading  Description::

@b{funcall} applies @i{function} to @i{args}.

If @i{function} is a @i{symbol},
it is coerced to a @i{function} as if by
finding its @i{functional value} in the @i{global environment}.

@subsubheading  Examples::

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

@subsubheading  Exceptional Situations::

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

@subsubheading  See Also::

@ref{apply}
, @b{function}, @ref{Evaluation}

@subsubheading  Notes::

@example
 (funcall @i{function} @i{arg1} @i{arg2} ...)
 @equiv{} (apply @i{function} @i{arg1} @i{arg2} ... nil)
 @equiv{} (apply @i{function} (list @i{arg1} @i{arg2} ...))
@end example

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

@node function (Special Operator), function-lambda-expression, funcall, Data and Control Flow Dictionary
@subsection function                                                 [Special Operator]

@code{function}  @i{name} @result{}  @i{function}

@subsubheading  Arguments and Values::

@i{name}---a @i{function name} or @i{lambda expression}.

@i{function}---a @i{function} @i{object}.

@subsubheading  Description::

The @i{value} of @b{function} is the @i{functional value} of @i{name}
in the current @i{lexical environment}.

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

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

It is an error to use @b{function} on a @i{function name} 
that does not denote a @i{function} in the lexical environment in
which the @b{function} form appears. 
Specifically, it is an error to use @b{function} on a @i{symbol} 
that denotes a @i{macro} or @i{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::

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

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

@example
 (setq add3 (adder 3))
 (funcall add3 5) @result{}  8
@end example

This works because @b{function} creates a @i{closure} of
the @i{lambda expression} that is able to refer to the @i{value} @t{3}
of the variable @t{x} even after control has returned from the function @t{adder}.

@subsubheading  See Also::

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

@subsubheading  Notes::

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

@node function-lambda-expression, functionp, function (Special Operator), Data and Control Flow Dictionary
@subsection function-lambda-expression                                       [Function]

@code{function-lambda-expression}  @i{function}@*
   @result{}  @i{lambda-expression, closure-p, name}

@subsubheading  Arguments and Values::

@i{function}---a @i{function}.

@i{lambda-expression}---a @i{lambda expression} or @b{nil}.

@i{closure-p}---a @i{generalized boolean}.

@i{name}---an @i{object}.

@subsubheading  Description::

Returns information about @i{function} as follows:

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

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

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

@subsubheading  Examples::

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

@example
 (function-lambda-expression #'(lambda (x) x))
@result{}  NIL, @i{false}, NIL
@i{OR}@result{} NIL, @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) X), @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) X), @i{false}, NIL

 (function-lambda-expression
    (funcall #'(lambda () #'(lambda (x) x))))
@result{}  NIL, @i{false}, NIL
@i{OR}@result{} NIL, @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) X), @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) X), @i{false}, NIL

 (function-lambda-expression 
    (funcall #'(lambda (x) #'(lambda () x)) nil))
@result{}  NIL, @i{true}, NIL
@i{OR}@result{} (LAMBDA () X), @i{true}, NIL
@i{NOT}@result{} NIL, @i{false}, NIL
@i{NOT}@result{} (LAMBDA () X), @i{false}, NIL

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

 (defun foo ()
   (flet ((bar (x) x))
     #'bar))
 (function-lambda-expression (foo))
@result{}  NIL, @i{false}, NIL
@i{OR}@result{} NIL, @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) (BLOCK BAR X)), @i{true}, NIL
@i{OR}@result{} (LAMBDA (X) (BLOCK BAR X)), @i{true}, (:INTERNAL FOO 0 BAR)
@i{OR}@result{} (LAMBDA (X) (BLOCK BAR X)), @i{false}, "BAR in FOO"
@end example

@subsubheading  Notes::

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

@node functionp, compiled-function-p, function-lambda-expression, Data and Control Flow Dictionary
@subsection functionp                                                        [Function]

@code{functionp}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{function};
otherwise, returns @i{false}.

@subsubheading  Examples::

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

@subsubheading  Notes::

@example
 (functionp @i{object}) @equiv{} (typep @i{object} 'function)
@end example

@node compiled-function-p, call-arguments-limit, functionp, Data and Control Flow Dictionary
@subsection compiled-function-p                                              [Function]

@code{compiled-function-p}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{compiled-function};
otherwise, returns @i{false}.

@subsubheading  Examples::

@example
 (defun f (x) x) @result{}  F
 (compiled-function-p #'f)
@result{}  @i{false}
@i{OR}@result{} @i{true}
 (compiled-function-p 'f) @result{}  @i{false}
 (compile 'f) @result{}  F
 (compiled-function-p #'f) @result{}  @i{true}
 (compiled-function-p 'f) @result{}  @i{false}
 (compiled-function-p (compile nil '(lambda (x) x)))
@result{}  @i{true}
 (compiled-function-p #'(lambda (x) x))
@result{}  @i{false}
@i{OR}@result{} @i{true}
 (compiled-function-p '(lambda (x) x)) @result{}  @i{false}
@end example

@subsubheading  See Also::

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

@subsubheading  Notes::

@example
 (compiled-function-p @i{object}) @equiv{} (typep @i{object} 'compiled-function)
@end example

@node call-arguments-limit, lambda-list-keywords, compiled-function-p, Data and Control Flow Dictionary
@subsection call-arguments-limit                                    [Constant Variable]

@subsubheading  Constant Value::

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

@subsubheading  Description::

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

@subsubheading  See Also::

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

@node lambda-list-keywords, lambda-parameters-limit, call-arguments-limit, Data and Control Flow Dictionary
@subsection lambda-list-keywords                                    [Constant Variable]

@subsubheading  Constant Value::

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

@subsubheading  Description::

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

@subsubheading  See Also::

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

@node lambda-parameters-limit, defconstant, lambda-list-keywords, Data and Control Flow Dictionary
@subsection lambda-parameters-limit                                 [Constant Variable]

@subsubheading  Constant Value::

@i{implementation-dependent}, but not smaller than @t{50}.

@subsubheading  Description::

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

@subsubheading  See Also::

@ref{call-arguments-limit}

@subsubheading  Notes::

Implementors are encouraged to make the @i{value} of
@b{lambda-parameters-limit} as large as possible.

@node defconstant, defparameter, lambda-parameters-limit, Data and Control Flow Dictionary
@subsection defconstant                                                         [Macro]

@code{defconstant}  @i{name initial-value @r{[}documentation@r{]}} @result{}  @i{name}

@subsubheading  Arguments and Values::

@i{name}---a @i{symbol}; not evaluated.

@i{initial-value}---a @i{form}; evaluated.

@i{documentation}---a @i{string}; not evaluated.

@subsubheading  Description::

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

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

If @i{documentation} is supplied, it is attached to @i{name} as a
@i{documentation string} of kind @b{variable}. 

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

The consequences are undefined if there are any 
@i{bindings}
of the variable named by @i{name} at the time @b{defconstant} 
is executed or if the value is not @b{eql} to the value of
@i{initial-value}.

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

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

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

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

[Editorial Note by KMP: Does ``same value'' here mean eql or similar?]

[Reviewer Note by Moon: Probably depends on whether load time is compared to compile time,
		or two compiles.]

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

@subsubheading  See Also::

@ref{declaim}
,
@ref{defparameter; defvar}
, 
@b{defvar},
@ref{documentation; (setf documentation)}
,
@ref{proclaim}
,
@ref{Constant Variables},
@ref{Compilation}

@node defparameter, destructuring-bind, defconstant, Data and Control Flow Dictionary
@subsection defparameter, defvar                                                [Macro]

@code{defparameter}  @i{name         initial-value @r{[}documentation@r{]} } @result{}  @i{name}

@code{defvar}  @i{name @t{[}initial-value @r{[}documentation@r{]}@t{]}} @result{}  @i{name}

@subsubheading  Arguments and Values:: 

@i{name}---a @i{symbol}; not evaluated.

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

@i{documentation}---a @i{string}; not evaluated.

@subsubheading  Description::

@b{defparameter} and @b{defvar} @i{establish} @i{name} 
as a @i{dynamic variable}.

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

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

If @i{documentation} is supplied, it is attached to @i{name} as a
@i{documentation string} of kind @b{variable}. 

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

@subsubheading  Examples::

@example
 (defparameter *p* 1) @result{}  *P*
 *p* @result{}  1
 (constantp '*p*) @result{}  @i{false}
 (setq *p* 2) @result{}  2
 (defparameter *p* 3) @result{}  *P*
 *p* @result{}  3

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

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

The principal operational distinction between @b{defparameter} and @b{defvar}
is that @b{defparameter} makes an unconditional assignment to @i{name},
while @b{defvar} makes a conditional one.  In practice, this means that
@b{defparameter} is useful in situations where loading or reloading the definition
would want to pick up a new value of the variable, while @b{defvar} 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:

@example
 (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 example

Here the initial value, @t{()}, for the variable @t{*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 @b{defvar} 
to avoid having the @t{*interesting-numbers*} information reset if the file is
loaded a second time.  It is true that the two calls to
@b{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:

@example
 (defparameter *default-beep-count* 3)
 (defun beep (&optional (n *default-beep-count*))
   (dotimes (i n) (si:
@end example

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

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

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

@subsubheading  Side Effects::

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

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

@subsubheading  Affected By::

@b{defvar} is affected by whether @i{name} is already @i{bound}.

@subsubheading  See Also::

@ref{declaim}
, 
@ref{defconstant}
,
@ref{documentation; (setf documentation)}
,
@ref{Compilation}

@subsubheading  Notes::

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

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

@b{defparameter} and @b{defvar} might be defined as follows:

@example
 (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 example

@node destructuring-bind, let, defparameter, Data and Control Flow Dictionary
@subsection destructuring-bind                                                  [Macro]

@code{destructuring-bind}  @i{lambda-list expression @{@i{declaration}@}{*} @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{lambda-list}---a @i{destructuring lambda list}.

@i{expression}---a @i{form}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated. 

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} returned by the @i{forms}.

@subsubheading  Description::

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

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

@subsubheading  Examples::
@example
 (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)) @result{}  (ALPHA BEE 3 2 1)
@end example

@subsubheading  Exceptional Situations::

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

@subsubheading  See Also::

@b{macrolet}, 
@ref{defmacro}

@node let, progv, destructuring-bind, Data and Control Flow Dictionary
@subsection let, let*                                                [Special Operator]

@code{let}  @i{@r{(}@{@i{var} | @r{(}@i{var} @r{[}@i{init-form}@r{]}@r{)}@}{*}@r{)} @{@i{declaration}@}{*} @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@code{let*}  @i{@r{(}@{@i{var} | @r{(}@i{var} @r{[}@i{init-form}@r{]}@r{)}@}{*}@r{)} @{@i{declaration}@}{*} @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{var}---a @i{symbol}.

@i{init-form}---a @i{form}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{form}---a @i{form}.

@i{results}---the @i{values} returned by the @i{forms}.

@subsubheading  Description::

@b{let} and @b{let*}
create new variable @i{bindings} and
execute a series of @i{forms} that use these @i{bindings}.
@b{let} performs the @i{bindings} in parallel and 
@b{let*} does them sequentially.

The form

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

first evaluates the expressions @i{init-form-1}, @i{init-form-2}, and so on,

in that order, saving the resulting values.
Then all of the variables @i{varj} are bound to the corresponding
values; each @i{binding} is lexical unless
there is a @b{special} declaration to the contrary.
The expressions @i{formk} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of a @b{let} 
is an @i{implicit progn}).

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

The form

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

first evaluates the expression @i{init-form-1}, then binds the variable
@i{var1} to that value; then it evaluates @i{init-form-2} and binds 

@i{var2}, and so on.
The expressions @i{formj} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of @b{let*} is an implicit @b{progn}).

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

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

@subsubheading  Examples::

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

The code

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

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

@subsubheading  See Also::

@ref{progv}

@node progv, setq, let, Data and Control Flow Dictionary
@subsection progv                                                    [Special Operator]

@code{progv}  @i{@i{symbols} @i{values} @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{symbols}---a @i{list} of @i{symbols}; evaluated.

@i{values}---a @i{list} of @i{objects}; evaluated.

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} returned by the @i{forms}.

@subsubheading  Description::

@b{progv} creates new dynamic variable @i{bindings} and
executes each @i{form} using those @i{bindings}.
Each @i{form} is evaluated in  order.

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

@subsubheading  Examples::
@example
 (setq *x* 1) @result{}  1
 (progv '(*x*) '(2) *x*) @result{}  2
 *x* @result{}  1

Assuming *x* is not globally special,

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

@subsubheading  See Also::

@ref{let; let*}
, @ref{Evaluation}

@subsubheading  Notes::

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

@node setq, psetq, progv, Data and Control Flow Dictionary
@subsection setq                                                         [Special Form]

@code{setq}  @i{@{!@i{pair}@}{*}} @result{}  @i{result}

@w{@i{pair} ::=var form}

@subsubheading  Pronunciation::

pronounced 'set ,ky\"u 

@subsubheading  Arguments and Values::

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

@i{form}---a @i{form}.

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

@subsubheading  Description::

Assigns values to @i{variables}.

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

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

@subsubheading  Examples::

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

 ;; Use of SETQ to update values by sequential assignment.
 (setq a (1+ b) b (1+ a) c (+ a b)) @result{}  7
 a @result{}  3
 b @result{}  4
 c @result{}  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)))
@result{}  ((21 22 30) 21 22)
@end example

@subsubheading  Side Effects::

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

@subsubheading  See Also::

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

@node psetq, block, setq, Data and Control Flow Dictionary
@subsection psetq                                                               [Macro]

@code{psetq}  @i{@{!@i{pair}@}{*}} @result{}  @i{@b{nil}}

@w{@i{pair} ::=var form}

@subsubheading  Pronunciation::

@b{psetq}: pronounced {{{\vrule width 1pt height 2pt depth 2pt}\kern -1pt\raise 6pt{\vrule width 1pt height 2pt depth 2pt}}}p\=e'set ,ky\"u 

@subsubheading  Arguments and Values::

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

@i{form}---a @i{form}.

@subsubheading  Description::

Assigns values to @i{variables}.

This is just like @b{setq}, 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 @b{setq}'s 
sequential assignment.

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

@subsubheading  Examples::

@example
 ;; 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) @result{}  NIL
 a @result{}  1
 b @result{}  2
 c @result{}  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)) @result{}  NIL
 a @result{}  3
 b @result{}  2
 c @result{}  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)))
@result{}  ((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))
@result{}  2, 1
@end example

@subsubheading  Side Effects::

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

@subsubheading  See Also::

@b{psetf},
@ref{setq}

@node block, catch, psetq, Data and Control Flow Dictionary
@subsection block                                                    [Special Operator]

@code{block}  @i{@i{name} @i{form}@r{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{name}---a @i{symbol}.

@i{form}---a @i{form}.

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

@subsubheading  Description::

@b{block} @i{establishes} a @i{block} named @i{name}
and then evaluates @i{forms} as an @i{implicit progn}.

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

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

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

@subsubheading  Examples::

@example
 (block empty) @result{}  NIL
 (block whocares (values 1 2) (values 3 4)) @result{}  3, 4
 (let ((x 1)) 
   (block stop (setq x 2) (return-from stop) (setq x 3))
   x) @result{}  2
 (block early (return-from early (values 1 2)) (values 3 4)) @result{}  1, 2
 (block outer (block inner (return-from outer 1)) 2) @result{}  1
 (block twin (block twin (return-from twin 1)) 2) @result{}  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)) @result{}  1
@end example

@subsubheading  See Also::

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

@subsubheading  Notes::

@node catch, go, block, Data and Control Flow Dictionary
@subsection catch                                                    [Special Operator]

@code{catch}  @i{@i{tag} @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{tag}---a @i{catch tag}; evaluated.

@i{forms}---an @i{implicit progn}.

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

@subsubheading  Description::

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

The order of execution of @b{catch} follows:
@ITindex{order of evaluation}

@ITindex{evaluation order}

@table @asis

@item 1.  
@i{Tag} is evaluated.
It serves as the name of the
@b{catch}.  

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

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

@item 4.  
The @i{tag} @i{established} 
by @b{catch} is @i{disestablished}
just before the results are returned.

@end table

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

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

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

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

@subsubheading  Exceptional Situations::
An error of @i{type} @b{control-error} is signaled
if @b{throw} is done
when there is no suitable @b{catch} @i{tag}. 
@subsubheading  See Also::

@ref{throw}
, @ref{Evaluation}

@subsubheading  Notes::

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

@b{catch} differs from @b{block} in that 
@b{catch}
tags have dynamic @i{scope} while 
@b{block} names have @i{lexical scope}.

@node go, return-from, catch, Data and Control Flow Dictionary
@subsection go                                                       [Special Operator]

@code{go}  @i{tag} 
        @result{}  #<NoValue>
@subsubheading  Arguments and Values:: 

@i{tag}---a @i{go tag}.

@subsubheading  Description::

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

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

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

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

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

The following is in error because the @b{tagbody} is passed over
before the @b{go} @i{form} is executed.

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

@subsubheading  See Also::

@ref{tagbody}

@node return-from, return, go, Data and Control Flow Dictionary
@subsection return-from                                              [Special Operator]

@code{return-from}  @i{@i{name} @r{[}@i{result}@r{]}} 
        @result{}  #<NoValue>
@subsubheading  Arguments and Values:: 

@i{name}---a @i{block tag}; not evaluated.

@i{result}---a @i{form}; evaluated.
  The default is @b{nil}.

@subsubheading  Description::

Returns control and @i{multiple values}_2 from a lexically enclosing @i{block}.

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

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

@subsubheading  Examples::

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

The following has undefined consequences because the @b{block} @i{form}
exits normally before the @b{return-from} @i{form} is attempted.

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

@subsubheading  See Also::

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

@node return, tagbody, return-from, Data and Control Flow Dictionary
@subsection return                                                              [Macro]

@code{return}  @i{@r{[}@i{result}@r{]}} @result{}  #<NoValue>

@subsubheading  Arguments and Values:: 

@i{result}---a @i{form}; evaluated.
  The default is @b{nil}.

@subsubheading  Description::

Returns, as if by @b{return-from}, from the @i{block} named @b{nil}.

@subsubheading  Examples::

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

@subsubheading  See Also::

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

@subsubheading  Notes::

@example
 (return) @equiv{} (return-from nil)
 (return @i{form}) @equiv{} (return-from nil @i{form})
@end example

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

@node tagbody, throw, return, Data and Control Flow Dictionary
@subsection tagbody                                                  [Special Operator]

@code{tagbody}  @i{@{@i{tag} | @i{statement}@}{*}} @result{}  @i{@b{nil}}

@subsubheading  Arguments and Values::

@i{tag}---a @i{go tag}; not evaluated.

@i{statement}---a @i{compound form}; evaluated as described below.

@subsubheading  Description::

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

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

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

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

@subsubheading  Examples::

@example
 (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)
@result{}  15
 (defun f1 (flag)
   (let ((n 1))
     (tagbody 
       (setq n (f2 flag #'(lambda () (go out))))
      out
       (prin1 n))))
@result{}  F1
 (defun f2 (flag escape)
   (if flag (funcall escape) 2))
@result{}  F2
 (f1 nil)
@t{ |> } 2
@result{}  NIL
 (f1 t)
@t{ |> } 1
@result{}  NIL
@end example

@subsubheading  See Also::

@ref{go}

@subsubheading  Notes::

The @i{macros} in Figure 5--10 have @i{implicit tagbodies}.

@group
@noindent
@w{  do              do-external-symbols  dotimes  }
@w{  do*             do-symbols           prog     }
@w{  do-all-symbols  dolist               prog*    }

@noindent
@w{  Figure 5--10: Macros that have implicit tagbodies.}

@end group

@node throw, unwind-protect, tagbody, Data and Control Flow Dictionary
@subsection throw                                                    [Special Operator]

@code{throw}  @i{tag result-form} 
        @result{}  #<NoValue>
@subsubheading  Arguments and Values:: 

@i{tag}---a @i{catch tag}; evaluated.

@i{result-form}---a @i{form}; evaluated as described below.

@subsubheading  Description::

@b{throw} causes a non-local control transfer
to a @b{catch} whose tag is @b{eq} to @i{tag}. 

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

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

@subsubheading  Examples::

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

@end example

@example
 (catch nil 
   (unwind-protect (throw nil 1)
     (throw nil 2))) @result{}  2
@end example

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

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

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

@example
 (catch 'foo
         (format t "The inner catch returns ~s.~
                 (catch 'foo
                     (unwind-protect (throw 'foo :first-throw)
                         (throw 'foo :second-throw))))
         :outer-catch)
@t{ |> } The inner catch returns :SECOND-THROW
@result{}  :OUTER-CATCH
@end example

@subsubheading  Exceptional Situations::

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

@subsubheading  See Also::

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

@subsubheading  Notes::

@b{catch} and @b{throw} are normally used when the @i{exit point}
must have @i{dynamic scope} (@i{e.g.}, the @b{throw} is not lexically enclosed
by the @b{catch}), while @b{block} and @b{return} are used 
when @i{lexical scope} is sufficient.

@node unwind-protect, nil, throw, Data and Control Flow Dictionary
@subsection unwind-protect                                           [Special Operator]

@code{unwind-protect}  @i{@i{protected-form} @{@i{cleanup-form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{protected-form}---a @i{form}.

@i{cleanup-form}---a @i{form}.

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

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

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

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

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

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

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

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

The following code
is not correct:

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

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

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

@example
;;; 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 example

@subsubheading  See Also::

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

@node nil, not, unwind-protect, Data and Control Flow Dictionary
@subsection nil                                                     [Constant Variable]

@subsubheading  Constant Value::

@b{nil}.

@subsubheading  Description::

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

@subsubheading  Examples::
@example
 nil @result{}  NIL 
@end example

@subsubheading  See Also::

@ref{t}

@node not, t, nil, Data and Control Flow Dictionary
@subsection not                                                              [Function]

@code{not}  @i{x} @result{}  @i{boolean}

@subsubheading  Arguments and Values:: 

@i{x}---a @i{generalized boolean} (@i{i.e.}, any @i{object}).

@i{boolean}---a @i{boolean}.

@subsubheading  Description::

Returns @b{t} if @i{x} is @i{false};
otherwise, returns @b{nil}.

@subsubheading  Examples::

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

@subsubheading  See Also::

@ref{null}

@subsubheading  Notes::

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

@node t, eq, not, Data and Control Flow Dictionary
@subsection t                                                       [Constant Variable]

@subsubheading  Constant Value::

@b{t}.

@subsubheading  Description::

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

The @i{symbol} @b{t} is also sometimes used for other purposes as well.
For example,
    as the @i{name} of a @i{class},
    as a @i{designator} (@i{e.g.}, a @i{stream designator})
 or as a special symbol for some syntactic reason 
      (@i{e.g.}, in @b{case} and @b{typecase} to label the @i{otherwise-clause}).

@subsubheading  Examples::

@example
 t @result{}  T 
 (eq t 't) @result{}  @i{true}
 (find-class 't) @result{}  #<CLASS T 610703333>
 (case 'a (a 1) (t 2)) @result{}  1
 (case 'b (a 1) (t 2)) @result{}  2
 (prin1 'hello t)
@t{ |> } HELLO
@result{}  HELLO
@end example

@subsubheading  See Also::

@ref{NIL}

@node eq, eql, t, Data and Control Flow Dictionary
@subsection eq                                                               [Function]

@code{eq}  @i{x y} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values:: 

@i{x}---an @i{object}.

@i{y}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

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

@subsubheading  Examples::
@example
 (eq 'a 'b) @result{}  @i{false}
 (eq 'a 'a) @result{}  @i{true}
 (eq 3 3)
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (eq 3 3.0) @result{}  @i{false}
 (eq 3.0 3.0)
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (eq #c(3 -4) #c(3 -4))
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (eq #c(3 -4.0) #c(3 -4)) @result{}  @i{false}
 (eq (cons 'a 'b) (cons 'a 'c)) @result{}  @i{false}
 (eq (cons 'a 'b) (cons 'a 'b)) @result{}  @i{false}
 (eq '(a . b) '(a . b))
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (progn (setq x (cons 'a 'b)) (eq x x)) @result{}  @i{true}
 (progn (setq x '(a . b)) (eq x x)) @result{}  @i{true}
 (eq #\A #\A)
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (let ((x "Foo")) (eq x x)) @result{}  @i{true}
 (eq "Foo" "Foo")
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (eq "Foo" (copy-seq "Foo")) @result{}  @i{false}
 (eq "FOO" "foo") @result{}  @i{false}
 (eq "string-seq" (copy-seq "string-seq")) @result{}  @i{false}
 (let ((x 5)) (eq x x))
@result{}  @i{true}
@i{OR}@result{} @i{false}
@end example

@subsubheading  See Also::  

@ref{eql}
,
@ref{equal}
,
@ref{equalp}
,
@ref{=; /=; <; >; <=; >=}
,
@ref{Compilation}

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

An implementation is permitted to make ``copies'' of 
@i{characters} and @i{numbers} at any time.  
The effect is that @r{Common Lisp} makes no guarantee that @b{eq} 
is true even when both its arguments are ``the same thing'' if 
that thing is a @i{character} or @i{number}.

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

@group
@noindent
@w{  catch           getf     throw  }
@w{  get             remf            }
@w{  get-properties  remprop  }

@noindent
@w{  Figure 5--11: Operators that always prefer EQ over EQL}

@end group

@node eql, equal, eq, Data and Control Flow Dictionary
@subsection eql                                                              [Function]

@code{eql}  @i{x y} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{x}---an @i{object}.

@i{y}---an @i{object}. 

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

The value of @b{eql} is @i{true} of two objects, @i{x} and
@i{y}, in the folowing cases:
@table @asis

@item 1.  
If @i{x} and @i{y} are @b{eq}.
@item 2.  
If @i{x} and @i{y} are both @i{numbers} 
of the same @i{type} and the same value.
@item 3.  
If they are both @i{characters} that represent the 
same character.
@end table

Otherwise the value of @b{eql} is @i{false}.

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

@subsubheading  Examples::

@example
 (eql 'a 'b) @result{}  @i{false}
 (eql 'a 'a) @result{}  @i{true}
 (eql 3 3) @result{}  @i{true}
 (eql 3 3.0) @result{}  @i{false}
 (eql 3.0 3.0) @result{}  @i{true}
 (eql #c(3 -4) #c(3 -4)) @result{}  @i{true}
 (eql #c(3 -4.0) #c(3 -4)) @result{}  @i{false}
 (eql (cons 'a 'b) (cons 'a 'c)) @result{}  @i{false}
 (eql (cons 'a 'b) (cons 'a 'b)) @result{}  @i{false}
 (eql '(a . b) '(a . b))
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (progn (setq x (cons 'a 'b)) (eql x x)) @result{}  @i{true}
 (progn (setq x '(a . b)) (eql x x)) @result{}  @i{true}
 (eql #\A #\A) @result{}  @i{true}
 (eql "Foo" "Foo")
@result{}  @i{true}
@i{OR}@result{} @i{false}
 (eql "Foo" (copy-seq "Foo")) @result{}  @i{false}
 (eql "FOO" "foo") @result{}  @i{false}
@end example

Normally @t{(eql 1.0s0 1.0d0)} is false, under the assumption
that @t{1.0s0} and @t{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 @t{(eql 1.0s0 1.0d0)}
might be true.  

@subsubheading  See Also::

@ref{eq}
,
@ref{equal}
,
@ref{equalp}
,
@ref{=; /=; <; >; <=; >=}
,
@ref{char=; char/=; char<; char>; char<=; char>=; char-equal; char-not-equal; char-lessp; char-greaterp; char-not-greaterp; char-not-lessp}

@subsubheading  Notes::

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

@b{eql} may not be true of two @i{floats}
even when they represent the same
value.  @b{=} is used to compare
mathematical values.

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

@node equal, equalp, eql, Data and Control Flow Dictionary
@subsection equal                                                            [Function]

@code{equal}  @i{x y} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values:: 

@i{x}---an @i{object}.

@i{y}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{x} and @i{y} are structurally similar
(isomorphic) @i{objects}.  @i{Objects} are treated as follows by
@b{equal}.

@table @asis

@item @i{Symbols}, @i{Numbers}, and @i{Characters}  
@b{equal} is @i{true} of two @i{objects} 
if they are @i{symbols} that are @b{eq},
if they are @i{numbers} that are @b{eql}, or
if they are @i{characters} that are @b{eql}.

@item @i{Conses}  
For @i{conses}, @b{equal} is defined recursively as
the two @i{cars} being @b{equal} 
and the two @i{cdrs} being @b{equal}.

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

@item @i{Pathnames}  
Two @i{pathnames} are @b{equal} 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 @i{strings} appearing in components is @i{implementation-dependent}.
@i{pathnames}
that are @b{equal} should be functionally equivalent.

@item Other (Structures, hash-tables, instances, ...)  
Two other @i{objects} are @b{equal} only if they are @b{eq}.

@end table

@b{equal} does not descend any @i{objects} other than the
ones explicitly specified above.
Figure 5--12 summarizes the information given in the previous list.
In addition, the figure specifies the priority of the behavior of @b{equal},
with upper
  entries taking priority over lower ones.

@group
@noindent
@w{  Type          Behavior                   }
@w{  @i{number}        uses @b{eql}                   }
@w{  @i{character}     uses @b{eql}                   }
@w{  @i{cons}          descends                   }
@w{  @i{bit vector}    descends                   }
@w{  @i{string}        descends                   }
@w{  @i{pathname}      ``functionally equivalent''  }
@w{  @i{structure}     uses @b{eq}                    }
@w{  Other @i{array}   uses @b{eq}                    }
@w{  @i{hash table}    uses @b{eq}                    }
@w{  Other @i{object}  uses @b{eq}                    }

@noindent
@w{  Figure 5--12: Summary and priorities of behavior of @b{equal}}

@end group

Any two @i{objects} that are @b{eql} are also @b{equal}. 

@b{equal} may fail to terminate if @i{x} or @i{y} is circular.

@subsubheading  Examples::

@example
 (equal 'a 'b) @result{}  @i{false}
 (equal 'a 'a) @result{}  @i{true}
 (equal 3 3) @result{}  @i{true}
 (equal 3 3.0) @result{}  @i{false}
 (equal 3.0 3.0) @result{}  @i{true}
 (equal #c(3 -4) #c(3 -4)) @result{}  @i{true}
 (equal #c(3 -4.0) #c(3 -4)) @result{}  @i{false}
 (equal (cons 'a 'b) (cons 'a 'c)) @result{}  @i{false}
 (equal (cons 'a 'b) (cons 'a 'b)) @result{}  @i{true}
 (equal #\A #\A) @result{}  @i{true}
 (equal #\A #\a) @result{}  @i{false}
 (equal "Foo" "Foo") @result{}  @i{true}
 (equal "Foo" (copy-seq "Foo")) @result{}  @i{true}
 (equal "FOO" "foo") @result{}  @i{false}
 (equal "This-string" "This-string") @result{}  @i{true}
 (equal "This-string" "this-string") @result{}  @i{false}
@end example

@subsubheading  See Also::

@ref{eq}
, 
@ref{eql}
, 
@ref{equalp}
, 
@ref{=; /=; <; >; <=; >=}
, 
@ref{string=; string/=; string<; string>; string<=; string>=; string-equal; string-not-equal; string-lessp; string-greaterp; string-not-greaterp; string-not-lessp}
, @b{string-equal}, 
@ref{char=; char/=; char<; char>; char<=; char>=; char-equal; char-not-equal; char-lessp; char-greaterp; char-not-greaterp; char-not-lessp}
, 
@b{char-equal}, 
@ref{tree-equal}

@subsubheading  Notes::

    @i{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, 
@b{equal} and @b{equalp} are
    not appropriate for every application. 

A rough rule of thumb is that two @i{objects} are @b{equal} 
if and only if their printed representations are the same.

@node equalp, identity, equal, Data and Control Flow Dictionary
@subsection equalp                                                           [Function]

@code{equalp}  @i{x y} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{x}---an @i{object}.

@i{y}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

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

@item @i{Characters}  
If two @i{characters} are @b{char-equal}.

@item @i{Numbers}  
If two @i{numbers} are the @i{same} under @b{=}. 

@item @i{Conses}  
If the two @i{cars} in the @i{conses} are @b{equalp} 
and the two @i{cdrs} in the @i{conses} are @b{equalp}.

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

@item @i{Structures}  
If two @i{structures} S_1 and S_2 have the same @i{class}
and the value of each @i{slot} in S_1 is the @i{same} under @b{equalp}
as the value of the corresponding @i{slot} in S_2.

@item @i{Hash Tables}  
@b{equalp} descends @i{hash-tables} by first comparing the count of entries
  and the @t{:test} function; if those are the same, it compares the
  keys of the tables using the @t{:test} function and then the values
  of the matching keys using @b{equalp} recursively.

@end table

@b{equalp} does not descend any @i{objects}
  other than the ones explicitly specified above.
Figure 5--13 summarizes the information given in the previous list.
In addition, the figure specifies the priority of the behavior of @b{equalp},
with upper
  entries taking priority over lower ones.

@group
@noindent
@w{  Type          Behavior                      }
@w{  @i{number}        uses @b{=}                        }
@w{  @i{character}     uses @b{char-equal}               }
@w{  @i{cons}          descends                      }
@w{  @i{bit vector}    descends                      }
@w{  @i{string}        descends                      }
@w{  @i{pathname}      same as @b{equal}                 }
@w{  @i{structure}     descends, as described above  }
@w{  Other @i{array}   descends                      }
@w{  @i{hash table}    descends, as described above  }
@w{  Other @i{object}  uses @b{eq}                       }

@noindent
@w{  Figure 5--13: Summary and priorities of behavior of @b{equalp}}

@end group

@subsubheading  Examples::

@example
 (equalp 'a 'b) @result{}  @i{false}
 (equalp 'a 'a) @result{}  @i{true}
 (equalp 3 3) @result{}  @i{true}
 (equalp 3 3.0) @result{}  @i{true}
 (equalp 3.0 3.0) @result{}  @i{true}
 (equalp #c(3 -4) #c(3 -4)) @result{}  @i{true}
 (equalp #c(3 -4.0) #c(3 -4)) @result{}  @i{true}
 (equalp (cons 'a 'b) (cons 'a 'c)) @result{}  @i{false}
 (equalp (cons 'a 'b) (cons 'a 'b)) @result{}  @i{true}
 (equalp #\A #\A) @result{}  @i{true}
 (equalp #\A #\a) @result{}  @i{true}
 (equalp "Foo" "Foo") @result{}  @i{true}
 (equalp "Foo" (copy-seq "Foo")) @result{}  @i{true}
 (equalp "FOO" "foo") @result{}  @i{true}
@end example

@example
 (setq array1 (make-array 6 :element-type 'integer
                            :initial-contents '(1 1 1 3 5 7))) 
@result{}  #(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))
@result{}  #(1 1 1 3 5 7)
 (equalp array1 array2) @result{}  @i{true}
 (setq vector1 (vector 1 1 1 3 5 7)) @result{}  #(1 1 1 3 5 7)
 (equalp array1 vector1) @result{}  @i{true} 
@end example

@subsubheading  See Also::

@ref{eq}
, 
@ref{eql}
, 
@ref{equal}
, 
@ref{=; /=; <; >; <=; >=}
, 
@ref{string=; string/=; string<; string>; string<=; string>=; string-equal; string-not-equal; string-lessp; string-greaterp; string-not-greaterp; string-not-lessp}
, @b{string-equal}, 
@ref{char=; char/=; char<; char>; char<=; char>=; char-equal; char-not-equal; char-lessp; char-greaterp; char-not-greaterp; char-not-lessp}
, 
@b{char-equal}

@subsubheading  Notes::

    @i{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, 
@b{equal} and @b{equalp} are
    not appropriate for every application. 

@node identity, complement, equalp, Data and Control Flow Dictionary
@subsection identity                                                         [Function]

@code{identity}  @i{object} @result{}  @i{object}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@subsubheading  Description::

Returns its argument @i{object}.

@subsubheading  Examples::

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

@subsubheading  Notes::

@b{identity} is intended for use with functions that require
a @i{function} as an argument.

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

@b{identity} could be defined by

@example
(defun identity (x) x)
@end example

@node complement, constantly, identity, Data and Control Flow Dictionary
@subsection complement                                                       [Function]

@code{complement}  @i{function} @result{}  @i{complement-function}

@subsubheading  Arguments and Values::

@i{function}---a @i{function}.

@i{complement-function}---a @i{function}.

@subsubheading  Description::

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

@subsubheading  Examples::

@example
 (funcall (complement #'zerop) 1) @result{}  @i{true}
 (funcall (complement #'characterp) #\A) @result{}  @i{false}
 (funcall (complement #'member) 'a '(a b c)) @result{}  @i{false}
 (funcall (complement #'member) 'd '(a b c)) @result{}  @i{true}
@end example

@subsubheading  See Also::

@ref{not}

@subsubheading  Notes::

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

In @r{Common Lisp}, functions with names like ``@t{@i{xxx}-if-not}''
are related to functions with names like ``@t{@i{xxx}-if}'' 
in that

@example
(@i{xxx}-if-not @i{f} . @i{arguments}) @equiv{} (@i{xxx}-if (complement @i{f}) . @i{arguments})
@end example

For example,

@example
 (find-if-not #'zerop '(0 0 3)) @equiv{}
 (find-if (complement #'zerop) '(0 0 3)) @result{}  3
@end example

Note that since the ``@t{@i{xxx}-if-not}'' @i{functions}
and the @t{:test-not} arguments have been deprecated,
uses of ``@t{@i{xxx}-if}'' @i{functions} or 
@t{:test} arguments with @b{complement} are preferred.

@node constantly, every, complement, Data and Control Flow Dictionary
@subsection constantly                                                       [Function]

@code{constantly}  @i{value} @result{}  @i{function}

@subsubheading  Arguments and Values:: 

@i{value}---an @i{object}.

@i{function}---a @i{function}.

@subsubheading  Description::

@b{constantly} returns a @i{function} that accepts any number of
arguments, that has no side-effects, and that always returns @i{value}.

@subsubheading  Examples::

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

@subsubheading  See Also::

@ref{not}

@subsubheading  Notes::

@b{constantly} could be defined by:

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

@node every, and, constantly, Data and Control Flow Dictionary
@subsection every, some, notevery, notany                                    [Function]

@code{every}  @i{predicate {&rest} sequences^+} @result{}  @i{generalized-boolean}

@code{some}  @i{predicate {&rest} sequences^+} @result{}  @i{result}

@code{notevery}  @i{predicate {&rest} sequences^+} @result{}  @i{generalized-boolean}

@code{notany}  @i{predicate {&rest} sequences^+} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values:: 

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

@i{sequence}---a @i{sequence}.

@i{result}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}. 

@subsubheading  Description::

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

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

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

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

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

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

@subsubheading  Examples::

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

@subsubheading  Exceptional Situations::

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

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

@subsubheading  See Also::

@ref{and}
,
@ref{or}
,

@ref{Traversal Rules and Side Effects}

@subsubheading  Notes::

@example
 (notany @i{predicate} @{@i{sequence}@}{*}) @equiv{} (not (some @i{predicate} @{@i{sequence}@}{*}))
 (notevery @i{predicate} @{@i{sequence}@}{*}) @equiv{} (not (every @i{predicate} @{@i{sequence}@}{*}))
@end example

@node and, cond, every, Data and Control Flow Dictionary
@subsection and                                                                 [Macro]

@code{and}  @i{@{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{form}---a @i{form}.

@i{results}---the @i{values} resulting from the evaluation of 
	          the last @i{form}, or the symbols @b{nil} or @b{t}.

@subsubheading  Description::

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

If no @i{forms} are supplied, @t{(and)} returns @b{t}.

@b{and} passes back multiple values from the last @i{subform}
but not from subforms other than the last.

@subsubheading  Examples::

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

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

@example
 (setq temp1 1 temp2 1 temp3 1) @result{}  1 
 (and (incf temp1) (incf temp2) (incf temp3)) @result{}  2 
 (and (eql 2 temp1) (eql 2 temp2) (eql 2 temp3)) @result{}  @i{true}
 (decf temp3) @result{}  1 
 (and (decf temp1) (decf temp2) (eq temp3 'nil) (decf temp3)) @result{}  NIL 
 (and (eql temp1 temp2) (eql temp2 temp3)) @result{}  @i{true}
 (and) @result{}  T 
@end example

@subsubheading  See Also::

@ref{cond}
,
@ref{every; some; notevery; notany}
,
@ref{if}
,
@ref{or}
,
@ref{when; unless}

@subsubheading  Notes::

@example
 (and @i{form}) @equiv{} (let () @i{form})
 (and @i{form1} @i{form2} ...) @equiv{} (when @i{form1} (and @i{form2} ...))
@end example

@node cond, if, and, Data and Control Flow Dictionary
@subsection cond                                                                [Macro]

@code{cond}  @i{@{!@i{clause}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@w{@i{clause} ::=@r{(}test-form @{@i{form}@}{*}@r{)}}

@subsubheading  Arguments and Values::

@i{test-form}---a @i{form}.

@i{forms}---an @i{implicit progn}.

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

@subsubheading  Description::

@b{cond} allows the execution of @i{forms} to be dependent
on @i{test-form}.

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

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

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

@subsubheading  Examples::

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

@subsubheading  See Also::

@ref{if}
, 
@ref{case; ccase; ecase}
.

@node if, or, cond, Data and Control Flow Dictionary
@subsection if                                                       [Special Operator]

@code{if}  @i{@i{test-form} @i{then-form} @r{[}@i{else-form}@r{]}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{Test-form}---a @i{form}.

@i{Then-form}---a @i{form}.

@i{Else-form}---a @i{form}.
  The default is @b{nil}.

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

@subsubheading  Description::

@b{if} allows the execution of a @i{form} to be dependent
on a single @i{test-form}.

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

@subsubheading  Examples::

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

@subsubheading  See Also::

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

@subsubheading  Notes::

@example
 (if @i{test-form} @i{then-form} @i{else-form})
 @equiv{} (cond (@i{test-form} @i{then-form}) (t @i{else-form}))
@end example

@node or, when, if, Data and Control Flow Dictionary
@subsection or                                                                  [Macro]

@code{or}  @i{@{@i{form}@}{*}} @result{}  @i{@{@i{results}@}{*}}

@subsubheading  Arguments and Values:: 

@i{form}---a @i{form}.

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

@subsubheading  Description::

@b{or} evaluates each @i{form}, one at a time, from left to right.  
The evaluation of all @i{forms} terminates when a @i{form} evaluates
to @i{true} (@i{i.e.}, something other than @b{nil}).

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

@subsubheading  Examples::

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

@subsubheading  See Also::

@ref{and}
,
@b{some},
@b{unless}

@node when, case, or, Data and Control Flow Dictionary
@subsection when, unless                                                        [Macro]

@code{when}  @i{test-form @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@code{unless}  @i{test-form @{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{test-form}---a @i{form}.

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} of the @i{forms}
    in a  @b{when}   @i{form} if the @i{test-form} @i{yields} @i{true} 
 or in an @b{unless} @i{form} if the @i{test-form} @i{yields} @i{false};
 otherwise @b{nil}.

@subsubheading  Description::       

@b{when} and @b{unless} allow the execution of @i{forms} 
to be dependent on a single @i{test-form}.

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

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

@subsubheading  Examples::

@example
 (when t 'hello) @result{}  HELLO
 (unless t 'hello) @result{}  NIL
 (when nil 'hello) @result{}  NIL
 (unless nil 'hello) @result{}  HELLO
 (when t) @result{}  NIL
 (unless nil) @result{}  NIL
 (when t (prin1 1) (prin1 2) (prin1 3))
@t{ |> } 123
@result{}  3
 (unless t (prin1 1) (prin1 2) (prin1 3)) @result{}  NIL
 (when nil (prin1 1) (prin1 2) (prin1 3)) @result{}  NIL
 (unless nil (prin1 1) (prin1 2) (prin1 3))
@t{ |> } 123
@result{}  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))))
@result{}  ((4) NIL (5) NIL 6 (6) 7 (7))
@end example

@subsubheading  See Also::

@ref{and}
,
@ref{cond}
,
@ref{if}
,
@ref{or}

@subsubheading  Notes::

@example
 (when @i{test} @{@i{form}@}^+) @equiv{} (and @i{test} (progn @{@i{form}@}^+))
 (when @i{test} @{@i{form}@}^+) @equiv{} (cond (@i{test} @{@i{form}@}^+))
 (when @i{test} @{@i{form}@}^+) @equiv{} (if @i{test} (progn @{@i{form}@}^+) nil)
 (when @i{test} @{@i{form}@}^+) @equiv{} (unless (not @i{test}) @{@i{form}@}^+)
 (unless @i{test} @{@i{form}@}^+) @equiv{} (cond ((not @i{test}) @{@i{form}@}^+))
 (unless @i{test} @{@i{form}@}^+) @equiv{} (if @i{test} nil (progn @{@i{form}@}^+))
 (unless @i{test} @{@i{form}@}^+) @equiv{} (when (not @i{test}) @{@i{form}@}^+)
@end example

@node case, typecase, when, Data and Control Flow Dictionary
@subsection case, ccase, ecase                                                  [Macro]

@code{case}  @i{keyform  @{!@i{normal-clause}@}{*} @r{[}!@i{otherwise-clause}@r{]}} @result{}  @i{@{@i{result}@}{*}}

@code{ccase}  @i{keyplace @{!@i{normal-clause}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@code{ecase}  @i{keyform  @{!@i{normal-clause}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@w{@i{normal-clause} ::=@r{(}keys @{@i{form}@}{*}@r{)}}

@w{@i{otherwise-clause} ::=@r{(}@{otherwise | t@} @{@i{form}@}{*}@r{)}}

@w{@i{clause} ::=normal-clause | otherwise-clause}

@IRindex{otherwise}

@IRindex{t}

@subsubheading  Arguments and Values::

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

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

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

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

@i{forms}---an @i{implicit progn}.

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

@subsubheading  Description::

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

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

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

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

@table @asis

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

If there is no @i{otherwise-clause}, @b{case} returns @b{nil}.

@item @b{ccase}  
If no @i{normal-clause} matches,
a @i{correctable} @i{error} of @i{type} @b{type-error} is signaled.
The offending datum is the @i{test-key} and
the expected type is @i{type equivalent} to @t{(member @i{key1} @i{key2} ...)}.
The @b{store-value} @i{restart} can be used to correct the error.

If the @b{store-value} @i{restart} is invoked, its @i{argument} becomes the 
new @i{test-key}, and is stored in @i{keyplace} as if by
@t{(setf @i{keyplace} @i{test-key})}.
Then @b{ccase} starts over, considering each @i{clause} anew.

[Reviewer Note by Barmar: Will it prompt for multiple values if keyplace is a VALUES general ref?]

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

@item @b{ecase}  
If no @i{normal-clause} matches,
a @i{non-correctable} @i{error} of @i{type} @b{type-error} is signaled.
The offending datum is the @i{test-key} and
the expected type is @i{type equivalent} to @t{(member @i{key1} @i{key2} ...)}.

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

@end table

@subsubheading  Examples::

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

@subsubheading  Side Effects::

The debugger might be entered.
If the @b{store-value} @i{restart} is invoked,
the @i{value} of @i{keyplace} might be changed.

@subsubheading  Affected By::

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

@subsubheading  Exceptional Situations::

@b{ccase} and @b{ecase} signal an error of @i{type} @b{type-error}
if no @i{normal-clause} matches.

@subsubheading  See Also::

@ref{cond}
,
@ref{typecase; ctypecase; etypecase}
,
@ref{setf; psetf}
,
@ref{Generalized Reference}

@subsubheading  Notes::

@example
(case @i{test-key}
  @{((@{@i{key}@}{*}) @{@i{form}@}{*})@}{*})
@equiv{}
(let ((#1=#:g0001 @i{test-key}))
  (cond @{((member #1# '(@{@i{key}@}{*})) @{@i{form}@}{*})@}{*}))
@end example

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

@node typecase, multiple-value-bind, case, Data and Control Flow Dictionary
@subsection typecase, ctypecase, etypecase                                      [Macro]

@code{typecase}  @i{keyform  @{!@i{normal-clause}@}{*} @r{[}!@i{otherwise-clause}@r{]}} @result{}  @i{@{@i{result}@}{*}}

@code{ctypecase}  @i{keyplace @{!@i{normal-clause}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@code{etypecase}  @i{keyform  @{!@i{normal-clause}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@w{@i{normal-clause} ::=@r{(}type @{@i{form}@}{*}@r{)}}

@w{@i{otherwise-clause} ::=@r{(}@{otherwise | t@} @{@i{form}@}{*}@r{)}}

@w{@i{clause} ::=normal-clause | otherwise-clause}

@IRindex{otherwise}

@IRindex{t}

@subsubheading  Arguments and Values::

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

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

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

@i{type}---a @i{type specifier}.

@i{forms}---an @i{implicit progn}.

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

@subsubheading  Description::

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

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

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

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

@table @asis

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

If there is no @i{otherwise-clause}, @b{typecase} returns @b{nil}.

@item @b{ctypecase}  
If no @i{normal-clause} matches,
a @i{correctable} @i{error} of @i{type} @b{type-error} is signaled.
The offending datum is the @i{test-key} and
the expected type is @i{type equivalent} to @t{(or @i{type1} @i{type2} ...)}.
The @b{store-value} @i{restart} can be used to correct the error.

If the @b{store-value} @i{restart} is invoked, its @i{argument} becomes the 
new @i{test-key}, and is stored in @i{keyplace} as if by
@t{(setf @i{keyplace} @i{test-key})}.
Then @b{ctypecase} starts over, considering each @i{clause} anew.

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

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

@item @b{etypecase}  
If no @i{normal-clause} matches,
a @i{non-correctable} @i{error} of @i{type} @b{type-error} is signaled.
The offending datum is the @i{test-key} and
the expected type is @i{type equivalent} to @t{(or @i{type1} @i{type2} ...)}.

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

@end table

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

@subsubheading  Examples::

@example
;;; (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))))))
@result{}  WHAT-IS-IT
 (map 'nil #'what-is-it '(nil (a b) 7.0 7 box))
@t{ |> } NIL is a symbol, boolean false, or the empty list.
@t{ |> } (A B) is a list.
@t{ |> } 7.0 is a float.
@t{ |> } 7 is a(n) integer.
@t{ |> } BOX is a(n) symbol.
@result{}  NIL
 (setq x 1/3)
@result{}  1/3
 (ctypecase x
     (integer (* x 4))
     (symbol  (symbol-value x)))
@t{ |> } Error: The value of X, 1/3, is neither an integer nor a symbol.
@t{ |> } To continue, type :CONTINUE followed by an option number:
@t{ |> }  1: Specify a value to use instead.
@t{ |> }  2: Return to Lisp Toplevel.
@t{ |> } Debug> @b{|>>}@t{:CONTINUE 1}@b{<<|}
@t{ |> } Use value: @b{|>>}@t{3.7}@b{<<|}
@t{ |> } Error: The value of X, 3.7, is neither an integer nor a symbol.
@t{ |> } To continue, type :CONTINUE followed by an option number:
@t{ |> }  1: Specify a value to use instead.
@t{ |> }  2: Return to Lisp Toplevel.
@t{ |> } Debug> @b{|>>}@t{:CONTINUE 1}@b{<<|}
@t{ |> } Use value: @b{|>>}@t{12}@b{<<|}
@result{}  48
 x @result{}  12
@end example

@subsubheading  Affected By::

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

@subsubheading  Exceptional Situations::

@b{ctypecase} and @b{etypecase} signal an error of @i{type} @b{type-error}
if no @i{normal-clause} matches.

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

@subsubheading  See Also::

@ref{case; ccase; ecase}
,
@ref{cond}
,
@ref{setf; psetf}
,
@ref{Generalized Reference}

@subsubheading  Notes::

@example
(typecase @i{test-key}
  @{(@i{type} @{@i{form}@}{*})@}{*})
@equiv{}
(let ((#1=#:g0001 @i{test-key}))
  (cond @{((typep #1# '@i{type}) @{@i{form}@}{*})@}{*}))
@end example

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

@node multiple-value-bind, multiple-value-call, typecase, Data and Control Flow Dictionary
@subsection multiple-value-bind                                                 [Macro]

@code{multiple-value-bind}  @i{@r{(}@{@i{var}@}{*}@r{)}
 		   @i{values-form}
 		   @{@i{declaration}@}{*}
 		   @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{var}---a @i{symbol} naming a variable; not evaluated.

@i{values-form}---a @i{form}; evaluated.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} returned by the @i{forms}.

@subsubheading  Description::

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

The variable @i{bindings} created are lexical unless
@b{special} declarations are specified.  

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

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

@subsubheading  Examples::

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

@subsubheading  See Also::

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

@subsubheading  Notes::

@example
 (multiple-value-bind (@{@i{var}@}{*}) @i{values-form} @{@i{form}@}{*})
 @equiv{} (multiple-value-call #'(lambda (&optional @{@i{var}@}{*} &rest #1=#:ignore)
                             (declare (ignore #1#))
                             @{@i{form}@}{*})
                         @i{values-form})
@end example

@node multiple-value-call, multiple-value-list, multiple-value-bind, Data and Control Flow Dictionary
@subsection multiple-value-call                                      [Special Operator]

@code{multiple-value-call}  @i{@i{function-form} @i{form}@r{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

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

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

@i{form}---a @i{form}.

@i{results}---the @i{values} returned by the @i{function}.

@subsubheading  Description::

Applies @i{function} to a @i{list} of the @i{objects} collected from groups of 
@i{multiple values}_2.

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

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

@subsubheading  See Also::

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

@node multiple-value-list, multiple-value-prog1, multiple-value-call, Data and Control Flow Dictionary
@subsection multiple-value-list                                                 [Macro]

@code{multiple-value-list}  @i{form} @result{}  @i{list}

@subsubheading  Arguments and Values::

@i{form}---a @i{form}; evaluated as described below.

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

@subsubheading  Description::

@b{multiple-value-list} evaluates @i{form} 
and creates a @i{list} of the @i{multiple values}_2 it returns.

@subsubheading  Examples::

@example
 (multiple-value-list (floor -3 4)) @result{}  (-1 1)
@end example

@subsubheading  See Also::

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

@subsubheading  Notes::

@b{multiple-value-list} and @b{values-list} are inverses
of each other.

@example
 (multiple-value-list form) @equiv{} (multiple-value-call #'list form)
@end example

@node multiple-value-prog1, multiple-value-setq, multiple-value-list, Data and Control Flow Dictionary
@subsection multiple-value-prog1                                     [Special Operator]

@code{multiple-value-prog}  @i{1} @result{}  @i{first-form @{@i{form}@}{*}}

		   {first-form-results}

@subsubheading  Arguments and Values::

@i{first-form}---a @i{form}; evaluated as described below.

@i{form}---a @i{form}; evaluated as described below.

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

@subsubheading  Description::

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

@subsubheading  Examples::

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

@subsubheading  See Also::

@ref{prog1; prog2}

@node multiple-value-setq, values, multiple-value-prog1, Data and Control Flow Dictionary
@subsection multiple-value-setq                                                 [Macro]

@code{multiple-value-setq}  @i{vars form} @result{}  @i{result}

@subsubheading  Arguments and Values::

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

@i{form}---a @i{form}.

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

@subsubheading  Description::

@b{multiple-value-setq} assigns values to @i{vars}.

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

If any @i{var} is the @i{name} of a @i{symbol macro},
then it is @i{assigned} as if by @b{setf}.  Specifically,

@example
 (multiple-value-setq (@i{symbol}_1 ... @i{symbol}_n) @i{value-producing-form})
@end example

is defined to always behave in the same way as

@example
 (values (setf (values @i{symbol}_1 ... @i{symbol}_n) @i{value-producing-form}))
@end example

in order that the rules for order of evaluation and side-effects be consistent
with those used by @b{setf}.
@ITindex{order of evaluation}

@ITindex{evaluation order}

See @ref{VALUES Forms as Places}.

@subsubheading  Examples::

@example
 (multiple-value-setq (quotient remainder) (truncate 3.2 2)) @result{}  1
 quotient @result{}  1
 remainder @result{}  1.2
 (multiple-value-setq (a b c) (values 1 2)) @result{}  1
 a @result{}  1
 b @result{}  2
 c @result{}  NIL
 (multiple-value-setq (a b) (values 4 5 6)) @result{}  4
 a @result{}  4
 b @result{}  5
@end example

@subsubheading  See Also::

@ref{setq}
,
@ref{symbol-macrolet}

@node values, values-list, multiple-value-setq, Data and Control Flow Dictionary
@subsection values                                                           [Accessor]

@code{values}  @i{{&rest} object} @result{}  @i{@{@i{object}@}{*}}

(setf (@code{         values} @i{{&rest} place}) new-values)@*

@subsubheading  Arguments and Values:: 

@i{object}---an @i{object}.

@i{place}---a @i{place}.

@i{new-value}---an @i{object}.

@subsubheading  Description::

@b{values} 
returns the @i{objects} as @i{multiple values}_2.

@b{setf} of @b{values} is used to store the
@i{multiple values}_2 @i{new-values} into the @i{places}.  
See @ref{VALUES Forms as Places}.

@subsubheading  Examples::

@example
 (values) @result{}  <@i{no @i{values}}>
 (values 1) @result{}  1
 (values 1 2) @result{}  1, 2
 (values 1 2 3) @result{}  1, 2, 3
 (values (values 1 2 3) 4 5) @result{}  1, 4, 5
 (defun polar (x y)
   (values (sqrt (+ (* x x) (* y y))) (atan y x))) @result{}  POLAR
 (multiple-value-bind (r theta) (polar 3.0 4.0)
   (vector r theta))
@result{}  #(5.0 0.927295)
@end example

Sometimes it is desirable to indicate explicitly that a function returns
exactly one value.  For example, the function

@example
 (defun foo (x y)
   (floor (+ x y) y)) @result{}  FOO
@end example

returns two values because @b{floor} 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.  @b{values} is the standard idiom
for indicating that only one value is to be returned:

@example
 (defun foo (x y)
   (values (floor (+ x y) y))) @result{}  FOO
@end example

This works because @b{values} 
returns exactly one value for each of
@i{args}; as for any function call,
if any of @i{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 @b{values} is a @i{function}, not a @i{macro} or @i{special form},
it receives as @i{arguments} only the @i{primary values} of 
its @i{argument} @i{forms}.

@node values-list, multiple-values-limit, values, Data and Control Flow Dictionary
@subsection values-list                                                      [Function]

@code{values-list}  @i{list} @result{}  @i{@{@i{element}@}{*}}

@subsubheading  Arguments and Values::

@i{list}---a @i{list}.

@i{elements}---the @i{elements} of the @i{list}.

@subsubheading  Description::

Returns the @i{elements} of the @i{list} as @i{multiple values}_2.

@subsubheading  Examples::

@example
 (values-list nil) @result{}  <@i{no @i{values}}>
 (values-list '(1)) @result{}  1
 (values-list '(1 2)) @result{}  1, 2
 (values-list '(1 2 3)) @result{}  1, 2, 3
@end example

@subsubheading  Exceptional Situations::

Should signal @b{type-error} if its argument is not a @i{proper list}.

@subsubheading  See Also::

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

@subsubheading  Notes::

@example
 (values-list @i{list}) @equiv{} (apply #'values @i{list})
@end example

@t{(equal @i{x} (multiple-value-list (values-list @i{x})))}
returns @i{true} for all @i{lists} @i{x}.

@node multiple-values-limit, nth-value, values-list, Data and Control Flow Dictionary
@subsection multiple-values-limit                                   [Constant Variable]

@subsubheading  Constant Value::

An @i{integer} not smaller than @t{20}, 
the exact magnitude of which is @i{implementation-dependent}.

@subsubheading  Description::

The upper exclusive bound on the number of @i{values} that may be
    returned from a @i{function},

    bound or assigned by @b{multiple-value-bind} or @b{multiple-value-setq},
 or passed as a first argument to @b{nth-value}.
(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, prog, multiple-values-limit, Data and Control Flow Dictionary
@subsection nth-value                                                           [Macro]

@code{nth-value}  @i{n form} @result{}  @i{object}

@subsubheading  Arguments and Values::

@i{n}---a non-negative @i{integer}; evaluated.

@i{form}---a @i{form}; evaluated as described below.

@i{object}---an @i{object}.

@subsubheading  Description::

Evaluates @i{n} and then @i{form},
returning as its only value the @i{n}th value @i{yielded} by @i{form},
or @b{nil} if @i{n} is greater than or equal to the number of @i{values}
returned by @i{form}.  (The first returned value is numbered @t{0}.)

@subsubheading  Examples::

@example
 (nth-value 0 (values 'a 'b)) @result{}  A
 (nth-value 1 (values 'a 'b)) @result{}  B
 (nth-value 2 (values 'a 'b)) @result{}  NIL
 (let* ((x 83927472397238947423879243432432432)
        (y 32423489732)
        (a (nth-value 1 (floor x y)))
        (b (mod x y)))
   (values a b (= a b)))
@result{}  3332987528, 3332987528, @i{true}
@end example

@subsubheading  See Also::

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

@subsubheading  Notes::

Operationally, the following relationship is true, although @b{nth-value} 
might be more efficient in some @i{implementations} 
because, for example, some @i{consing} might be avoided.

@example
 (nth-value @i{n} @i{form}) @equiv{} (nth @i{n} (multiple-value-list @i{form}))
@end example

@node prog, prog1, nth-value, Data and Control Flow Dictionary
@subsection prog, prog*                                                         [Macro]

@code{prog}  @i{@r{(}@{@i{var} | 
			  	       @r{(}@i{var} @r{[}@i{init-form}@r{]}@r{)}@}{*}@r{)}
	      	   @{@i{declaration}@}{*}
	      	   @{@i{tag} | @i{statement}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@code{prog*}  @i{@r{(}@{@i{var} | 
				       @r{(}@i{var} @r{[}@i{init-form}@r{]}@r{)}@}{*}@r{)}
		   @{@i{declaration}@}{*} 
		   @{@i{tag} | @i{statement}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{var}---variable name.

@i{init-form}---a @i{form}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{tag}---a @i{go tag}; not evaluated.

@i{statement}---a @i{compound form}; evaluated as described below.

@i{results}---@b{nil} if a @i{normal return} occurs,
   or else, if an @i{explicit return} occurs, the @i{values} that were transferred.

@subsubheading  Description::

Three distinct operations are performed by @b{prog} and 
@b{prog*}:  
they bind local variables,
they permit use of the @b{return} 
statement, and they permit use of the @b{go}
statement.
A typical @b{prog} looks like this:

@example
 (prog (var1 var2 (var3 init-form-3) var4 (var5 init-form-5))
       @{@i{declaration}@}{*}
       statement1
  tag1
       statement2
       statement3
       statement4
  tag2
       statement5
       ...
       )
@end example

For @b{prog},
@i{init-forms} are evaluated first, in the order in which they are
supplied. The @i{vars} are then bound to the corresponding values in
parallel.  If no @i{init-form} 
is supplied for a given @i{var}, 
that @i{var} is  bound to @b{nil}.

The body of @b{prog} is executed as if it were a @b{tagbody} @i{form};
the @b{go} statement can be used to transfer control
to a @i{tag}.
@i{Tags} label @i{statements}.

@b{prog} implicitly establishes a @b{block} named @b{nil} around
the entire @b{prog} @i{form}, so that @b{return} can be used
at any time to exit from the @b{prog} @i{form}.

The difference between @b{prog*} and @b{prog} is that
in @b{prog*} the @i{binding} and initialization of the @i{vars} 
is done @i{sequentially}, so that the @i{init-form} for each
one can use the values of previous ones.

@subsubheading  Examples::
@example
(prog* ((y z) (x (car y)))
       (return x))
@end example

returns the @i{car} of the value of @t{z}.

@example
 (setq a 1) @result{}  1
 (prog ((a 2) (b a)) (return (if (= a b) '= '/=))) @result{}  /=
 (prog* ((a 2) (b a)) (return (if (= a b) '= '/=))) @result{}  =
 (prog () 'no-return-value) @result{}  NIL
@end example

@example
 (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))) @result{}  KING-OF-CONFUSION 
@end example

This can be accomplished more perspicuously as follows:

@example
 (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 '@t{()} (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)))) @result{}  PRINCE-OF-CLARITY 
@end example

@subsubheading  See Also::

@ref{block}
, 
@ref{let; let*}
, 
@ref{tagbody}
, 
@ref{go}
, 
@ref{return}
, @ref{Evaluation}

@subsubheading  Notes::
@b{prog} can be explained in terms of 
@b{block}, @b{let}, and @b{tagbody} as
follows:

@example
 (prog @i{variable-list} @i{declaration} . @i{body})
    @equiv{} (block nil (let @i{variable-list} @i{declaration} (tagbody . @i{body})))
@end example

@node prog1, progn, prog, Data and Control Flow Dictionary
@subsection prog1, prog2                                                        [Macro]

@code{prog}  @i{1} @result{}  @i{first-form             @{@i{form}@}{*}}
 {result-1}
@code{prog}  @i{2} @result{}  @i{first-form second-form @{@i{form}@}{*}}
 {result-2}

@subsubheading  Arguments and Values::

@i{first-form}---a @i{form}; evaluated as described below.

@i{second-form}---a @i{form}; evaluated as described below.

@i{forms}---an @i{implicit progn}; evaluated as described below.

@i{result-1}---the @i{primary value} resulting from 
		   the @i{evaluation} of @i{first-form}.

@i{result-2}---the @i{primary value} resulting from 
		   the @i{evaluation} of @i{second-form}.

@subsubheading  Description::

@b{prog1} @i{evaluates} @i{first-form} 
 and then @i{forms},
@i{yielding} as its only @i{value}
the @i{primary value} @i{yielded} by @i{first-form}.

@b{prog2} @i{evaluates} @i{first-form},
     then @i{second-form},
 and then @i{forms},
@i{yielding} as its only @i{value}
the @i{primary value} @i{yielded} by @i{first-form}.

@subsubheading  Examples::

@example
 (setq temp 1) @result{}  1
 (prog1 temp (print temp) (incf temp) (print temp))
@t{ |> } 1
@t{ |> } 2
@result{}  1
 (prog1 temp (setq temp nil)) @result{}  2
 temp @result{}  NIL
 (prog1 (values 1 2 3) 4) @result{}  1 
 (setq temp (list 'a 'b 'c))
 (prog1 (car temp) (setf (car temp) 'alpha)) @result{}  A
 temp @result{}  (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*)))
@result{}  2, 1
 (setq temp 1) @result{}  1
 (prog2 (incf temp) (incf temp) (incf temp)) @result{}  3
 temp @result{}  4
 (prog2 1 (values 2 3 4) 5) @result{}  2
@end example

@subsubheading  See Also::

@ref{multiple-value-prog1}
,
@ref{progn}

@subsubheading  Notes::

@b{prog1} and @b{prog2} are typically used to @i{evaluate} 
one or more @i{forms} with side effects and return a @i{value} that
must be computed before some or all of the side effects happen.

@example
 (prog1 @{@i{form}@}{*}) @equiv{} (values (multiple-value-prog1 @{@i{form}@}{*}))
 (prog2 @i{form1} @{@i{form}@}{*}) @equiv{} (let () @i{form1} (prog1 @{@i{form}@}{*}))
@end example

@node progn, define-modify-macro, prog1, Data and Control Flow Dictionary
@subsection progn                                                    [Special Operator]

@code{progn}  @i{@{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values:: 

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} of the @i{forms}.

@subsubheading  Description::

@b{progn} evaluates @i{forms},
in the order in which they are given.

The values of each @i{form} but the last are discarded.

If @b{progn} appears as a @i{top level form}, then all @i{forms}
within that @b{progn} are considered by the compiler to be 
@i{top level forms}.

@subsubheading  Examples::
@example
 (progn) @result{}  NIL
 (progn 1 2 3) @result{}  3
 (progn (values 1 2 3)) @result{}  1, 2, 3
 (setq a 1) @result{}  1
 (if a
      (progn (setq a nil) 'here)
      (progn (setq a t) 'there)) @result{}  HERE
 a @result{}  NIL
@end example

@subsubheading  See Also::

@ref{prog1; prog2}
, @b{prog2}, @ref{Evaluation}

@subsubheading  Notes::

Many places in @r{Common Lisp} involve syntax that uses @i{implicit progns}.
That is, part of their syntax allows many @i{forms} to be written
that are to be evaluated sequentially, discarding the results
of all @i{forms} but the last and returning the results of the last @i{form}.
Such places include, but are not limited to, the following:
     the body of a @i{lambda expression};
     the bodies of various control and conditional @i{forms}
    (@i{e.g.}, @b{case}, @b{catch}, @b{progn}, and @b{when}).

@node define-modify-macro, defsetf, progn, Data and Control Flow Dictionary
@subsection define-modify-macro                                                 [Macro]

@code{define-modify-macro}  @i{name lambda-list function @r{[}documentation@r{]}} @result{}  @i{name}

@subsubheading  Arguments and Values:: 

@i{name}---a @i{symbol}.

@i{lambda-list}---a @i{define-modify-macro lambda list} 

@i{function}---a @i{symbol}.

@i{documentation}---a @i{string}; not evaluated.

@subsubheading  Description::

@b{define-modify-macro} defines a @i{macro} named
@i{name} to @i{read} and @i{write} a @i{place}.

The arguments to the new @i{macro} are a @i{place},
followed
by the arguments that are supplied in @i{lambda-list}.

@i{Macros} defined with @b{define-modify-macro} 
correctly pass the @i{environment parameter} to 

@b{get-setf-expansion}.

When the @i{macro} is invoked, @i{function} 
is applied to the old contents of the @i{place}
and the @i{lambda-list} arguments to obtain the new value,
and the @i{place} is updated to contain the result.

Except for the issue of avoiding multiple evaluation (see below), the expansion
of a @b{define-modify-macro} is equivalent to the following:

@example
 (defmacro @i{name} (reference . @i{lambda-list})
   @i{documentation}
   `(setf ,reference
          (@i{function} ,reference ,@i{arg1} ,@i{arg2} ...)))
@end example

where @i{arg1}, @i{arg2}, ..., 
are the parameters appearing in @i{lambda-list};
appropriate provision is made for a @i{rest parameter}.

The @i{subforms} of the macro calls defined by @b{define-modify-macro}
are evaluated as specified in @ref{Evaluation of Subforms to Places}.

@i{Documentation} is attached as a @i{documentation string} 
    to @i{name} (as kind @b{function})
and to the @i{macro function}.

If a @b{define-modify-macro} @i{form} appears as a @i{top level form},
the @i{compiler} must store the @i{macro} definition at compile time,
so that occurrences of the macro later on in the file can be expanded correctly.

@subsubheading  Examples::
@example
 (define-modify-macro appendf (&rest args) 
    append "Append onto list") @result{}  APPENDF
 (setq x '(a b c) y x) @result{}  (A B C)
 (appendf x '(d e f) '(1 2 3)) @result{}  (A B C D E F 1 2 3)
 x @result{}  (A B C D E F 1 2 3)
 y @result{}  (A B C)
 (define-modify-macro new-incf (&optional (delta 1)) +)
 (define-modify-macro unionf (other-set &rest keywords) union)
@end example

@subsubheading  Side Effects::

A macro definition is assigned to @i{name}.

@subsubheading  See Also::

@ref{defsetf}
,

@ref{define-setf-expander}
,

@ref{documentation; (setf documentation)}
,
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@node defsetf, define-setf-expander, define-modify-macro, Data and Control Flow Dictionary
@subsection defsetf                                                             [Macro]

The ``short form'':

@code{defsetf}  @i{access-fn update-fn @r{[}documentation@r{]}}@*
   @result{}  @i{access-fn}

The ``long form'':

@code{defsetf}  @i{access-fn lambda-list @r{(}@{@i{store-variable}@}{*}@r{)}
                          {[[@{@i{declaration}@}{*} | @i{documentation}]]} @{@i{form}@}{*}}@*
   @result{}  @i{access-fn}

@subsubheading  Arguments and Values:: 

@i{access-fn}---a @i{symbol} which names a @i{function} or a @i{macro}.

@i{update-fn}---a @i{symbol} naming a @i{function} or @i{macro}.

@i{lambda-list}---a @i{defsetf lambda list}.

@i{store-variable}---a @i{symbol} (a @i{variable} @i{name}).

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{documentation}---a @i{string}; not evaluated.

@i{form}---a @i{form}.

@subsubheading  Description::

@b{defsetf} defines how to 
@b{setf} a @i{place}
of the form @t{(@i{access-fn} ...)} for relatively simple cases.
(See @b{define-setf-expander} for more general access to this facility.)

It must be the case that the @i{function} or @i{macro} named by @i{access-fn} 
evaluates all of its arguments.

@b{defsetf} may take one of two forms, called the ``short form'' and the ``long form,''
which are distinguished by the @i{type} of the second @i{argument}.

When the short form is used, 
@i{update-fn} must name 
a @i{function} (or @i{macro}) that takes one more argument
than @i{access-fn} takes.  When @b{setf} is given a @i{place}
that is a call on @i{access-fn}, it expands into
a call on @i{update-fn} that is given all the arguments to
@i{access-fn} and also, as its last argument, the new value
(which must be returned by @i{update-fn} as its value).

The long form @b{defsetf} 
resembles @b{defmacro}.
The @i{lambda-list} describes the arguments of @i{access-fn}. 
The @i{store-variables} describe the
value 

or values 

to be stored into the @i{place}.
The @i{body} must
compute the expansion of a @b{setf} of a call on @i{access-fn}.

The expansion function is defined in the same @i{lexical environment}
in which the @b{defsetf} @i{form} appears.

During the evaluation of the
@i{forms}, the variables in the @i{lambda-list} and the
@i{store-variables}
are bound to names of temporary variables,
generated as if by @b{gensym}
or @b{gentemp},
that will be bound by the
expansion of @b{setf} 
to the values of those @i{subforms}.  This binding
permits the
@i{forms} to be written without regard for order-of-evaluation
issues.  @b{defsetf} arranges for the temporary variables to be
optimized out of the final result in cases where that is possible.  

The body code in @b{defsetf} is implicitly enclosed in a 
@i{block} whose name is 
@i{access-fn}

@b{defsetf} 
ensures that @i{subforms} 
of the @i{place} are evaluated exactly once.

@i{Documentation} is attached to @i{access-fn} as a @i{documentation string}
of kind @b{setf}.

If a @b{defsetf} @i{form} appears as a @i{top level form},
the @i{compiler} must make the @i{setf expander} available so that
it may be used to expand calls to @b{setf} later on in the @i{file}.
Users must ensure that the @i{forms}, if any, can be evaluated
at compile time if the @i{access-fn} is used in a @i{place}
later in the same @i{file}.
The @i{compiler} must make these @i{setf expanders} available to 
compile-time calls to @b{get-setf-expansion} when its @i{environment} 
argument is a value received as the @i{environment parameter} of a @i{macro}.

@subsubheading  Examples::
The effect of

@example
 (defsetf symbol-value set)
@end example

is built into the @r{Common Lisp} system.
This causes the form @t{(setf (symbol-value foo) fu)}
to expand into @t{(set foo fu)}.

Note that

@example
 (defsetf car rplaca)
@end example

would be incorrect because @b{rplaca} does not return its last argument.

@example
 (defun middleguy (x) (nth (truncate (1- (list-length x)) 2) x)) @result{}  MIDDLEGUY
 (defun set-middleguy (x v)
    (unless (null x)
      (rplaca (nthcdr (truncate (1- (list-length x)) 2) x) v))
    v) @result{}  SET-MIDDLEGUY
 (defsetf middleguy set-middleguy) @result{}  MIDDLEGUY
 (setq a (list 'a 'b 'c 'd)
       b (list 'x)
       c (list 1 2 3 (list 4 5 6) 7 8 9)) @result{}  (1 2 3 (4 5 6) 7 8 9)
 (setf (middleguy a) 3) @result{}  3
 (setf (middleguy b) 7) @result{}  7
 (setf (middleguy (middleguy c)) 'middleguy-symbol) @result{}  MIDDLEGUY-SYMBOL
 a @result{}  (A 3 C D)
 b @result{}  (7)
 c @result{}  (1 2 3 (4 MIDDLEGUY-SYMBOL 6) 7 8 9)
@end example

An example of the use of the long form of @b{defsetf}:

@example
 (defsetf subseq (sequence start &optional end) (new-sequence)
   `(progn (replace ,sequence ,new-sequence
                    :start1 ,start :end1 ,end)
           ,new-sequence)) @result{}  SUBSEQ
@end example

@example
 (defvar *xy* (make-array '(10 10)))
 (defun xy (&key ((x x) 0) ((y y) 0)) (aref *xy* x y)) @result{}  XY
 (defun set-xy (new-value &key ((x x) 0) ((y y) 0))
   (setf (aref *xy* x y) new-value)) @result{}  SET-XY
 (defsetf xy (&key ((x x) 0) ((y y) 0)) (store)
   `(set-xy ,store 'x ,x 'y ,y)) @result{}  XY
 (get-setf-expansion '(xy a b))
@result{}  (#: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) @result{}  NIL
 (setf (xy 'x 1) 1) @result{}  1
 (xy 'x 1) @result{}  1
 (let ((a 'x) (b 'y))
   (setf (xy a 1 b 2) 3)
   (setf (xy b 5 a 9) 14))
@result{}  14
 (xy 'y 0 'x 1) @result{}  1
 (xy 'x 1 'y 2) @result{}  3
@end example

@subsubheading  See Also::

@ref{documentation; (setf documentation)}
,
@ref{setf; psetf}
,

@ref{define-setf-expander}
,
@ref{get-setf-expansion}
,

@ref{Generalized Reference},
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading  Notes::

@i{forms} must include provision
for returning the correct value (the value 

or values 

of @i{store-variable}).  
This is
handled by @i{forms} rather than by @b{defsetf} because
in many cases this value can be returned at no extra cost, by calling a
function that simultaneously stores into the @i{place} and 
returns the correct value.

A @b{setf} of a call on @i{access-fn} also evaluates
all of @i{access-fn}'s arguments; it cannot treat any of them specially.
This means that @b{defsetf} 
cannot be used to describe how to store into
a @i{generalized reference} to a byte, such as @t{(ldb field reference)}.

@b{define-setf-expander}

is used to handle situations that 
do not fit the restrictions imposed by @b{defsetf}
and gives the user additional control.

@node define-setf-expander, get-setf-expansion, defsetf, Data and Control Flow Dictionary
@subsection define-setf-expander                                                [Macro]

@code{define-setf-expander}  @i{access-fn lambda-list
			 {[[@{@i{declaration}@}{*} | @i{documentation}]]} @{@i{form}@}{*}}@*
   @result{}  @i{access-fn}

@subsubheading  Arguments and Values::

@i{access-fn}---a @i{symbol} that @i{names} a @i{function} or @i{macro}.

@i{lambda-list} -- @i{macro lambda list}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{documentation}---a @i{string}; not evaluated.

@i{forms}---an @i{implicit progn}.

@subsubheading  Description::

@b{define-setf-expander} specifies the means by which @b{setf} 
updates a @i{place} that is referenced by @i{access-fn}.

When @b{setf} is given a @i{place} that is
specified in terms of @i{access-fn} and a new value for the 
@i{place}, it is expanded into a form that performs
the appropriate update. 

The @i{lambda-list} supports destructuring.
See @ref{Macro Lambda Lists}.

@i{Documentation} is attached to @i{access-fn} as a @i{documentation string}
of kind @b{setf}.

@i{Forms} constitute the body of the 

@i{setf expander} 

definition and must compute the @i{setf expansion} for a call on @b{setf} 
that references the @i{place} by means of the given
@i{access-fn}.

The @i{setf expander} function is defined in the same @i{lexical environment}
in which the @b{define-setf-expander} @i{form} appears.

While @i{forms} are being executed,
the variables in @i{lambda-list} are bound to parts of the @i{place} @i{form}.

The body @i{forms} (but not the @i{lambda-list})

in a @b{define-setf-expander} @i{form} are implicitly enclosed in a 
@i{block} whose name is 
@i{access-fn}.

The evaluation of @i{forms} must result in the five values
described in @ref{Setf Expansions}.

If a @b{define-setf-expander} @i{form} appears as a @i{top level form},
the @i{compiler} must make the @i{setf expander} available so that
it may be used to expand calls to @b{setf} later on in the @i{file}.
@i{Programmers} must ensure that the @i{forms} can be evaluated
at compile time if the @i{access-fn} is used in a @i{place}
later in the same @i{file}.
The @i{compiler} must make these @i{setf expanders} available to 
compile-time calls to @b{get-setf-expansion} when its @i{environment} 
argument is a value received as the @i{environment parameter} of a @i{macro}.

@subsubheading  Examples::
@example
 (defun lastguy (x) (car (last x))) @result{}  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))))) @result{}  LASTGUY
 (setq a (list 'a 'b 'c 'd)
       b (list 'x)
       c (list 1 2 3 (list 4 5 6))) @result{}  (1 2 3 (4 5 6))
 (setf (lastguy a) 3) @result{}  3
 (setf (lastguy b) 7) @result{}  7
 (setf (lastguy (lastguy c)) 'lastguy-symbol) @result{}  LASTGUY-SYMBOL
 a @result{}  (A B C 3)
 b @result{}  (7)
 c @result{}  (1 2 3 (4 5 LASTGUY-SYMBOL))
@end example

@example
;;; 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.
               `(let ((,stemp (dpb ,store ,btemp ,access-form)))
                  ,store-form
                  ,store)               ;Storing form.
               `(ldb ,btemp ,access-form) ;Accessing form.
              ))))
@end example

@subsubheading  See Also::

@ref{setf; psetf}
,
@ref{defsetf}
,
@ref{documentation; (setf documentation)}
,
@ref{get-setf-expansion}
,
@ref{Syntactic Interaction of Documentation Strings and Declarations}

@subsubheading  Notes::

@b{define-setf-expander} differs from the long form of @b{defsetf}
in that while the body is being executed the @i{variables}
in @i{lambda-list} are bound to parts of the @i{place} @i{form},
not to temporary variables that will be bound to the values of such parts.
In addition, @b{define-setf-expander} does not have @b{defsetf}'s
restriction that @i{access-fn} must be a @i{function} 
or a function-like @i{macro}; an arbitrary @b{defmacro} destructuring
pattern is permitted in @i{lambda-list}.

@node get-setf-expansion, setf, define-setf-expander, Data and Control Flow Dictionary
@subsection get-setf-expansion                                               [Function]

@code{get-setf-expansion}  @i{place {&optional} environment}@*
   @result{}  @i{vars, vals, store-vars, writer-form, reader-form}

@subsubheading  Arguments and Values:: 

@i{place}---a @i{place}.

@i{environment}---an @i{environment} @i{object}.

@i{vars, vals, store-vars, writer-form, reader-form}---a @i{setf expansion}.

@subsubheading  Description::

Determines
five values constituting the @i{setf expansion} for @i{place}
in @i{environment}; see @ref{Setf Expansions}.

If @i{environment} is not supplied or @b{nil},
the environment is the @i{null lexical environment}. 

@subsubheading  Examples::

@example
 (get-setf-expansion 'x)
@result{}  NIL, NIL, (#:G0001), (SETQ X #:G0001), X 
@end example

@example
;;; 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)) @result{}  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 example

@subsubheading  See Also::

@ref{defsetf}
,
@ref{define-setf-expander}
,
@ref{setf; psetf}

@subsubheading  Notes::

Any @i{compound form} is a valid @i{place},
since any @i{compound form} whose @i{operator} @i{f} has no @i{setf expander}
are expanded into a call to @t{(setf @i{f})}.

@node setf, shiftf, get-setf-expansion, Data and Control Flow Dictionary
@subsection setf, psetf                                                         [Macro]

@code{setf}  @i{@{!@i{pair}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@code{psetf}  @i{@{!@i{pair}@}{*}} @result{}  @i{@b{nil}}

@w{@i{pair} ::=place newvalue}

@subsubheading  Arguments and Values::

@i{place}---a @i{place}.

@i{newvalue}---a @i{form}.

@i{results}---the @i{multiple values}_2 
                  returned by the storing form for the last @i{place},
                  or @b{nil} if there are no @i{pairs}.

@subsubheading  Description::

@b{setf} changes the @i{value} of @i{place} to be @i{newvalue}.

@t{(setf place newvalue)} 
expands into an update form that stores the 
result 
of evaluating
@i{newvalue} into the location referred to by @i{place}.
   Some @i{place} forms 
involve uses of accessors that take optional arguments. 
   Whether those optional arguments are permitted by 
@b{setf}, or what their use
   is, is up to the 
@b{setf} expander function and is not under the control
   of @b{setf}. 
The documentation for any @i{function} 
that accepts @b{&optional}, @b{&rest},
   or @t{&key} arguments and that 
claims to be usable with @b{setf} must specify
   how those arguments are treated.

If more than one @i{pair} is supplied,
the @i{pairs} are processed sequentially; that is,

@example
 (setf place-1 newvalue-1
       place-2 newvalue-2
       ...
       place-N newvalue-N)
@end example

is precisely equivalent to

@example
 (progn (setf place-1 newvalue-1)
        (setf place-2 newvalue-2)
        ...
        (setf place-N newvalue-N))
@end example

For @b{psetf}, 
if more than one @i{pair} is supplied then the assignments of new values to places are
done in parallel.  More precisely, all @i{subforms} (in both the @i{place}
and @i{newvalue} @i{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 @b{setf} and @b{psetf},
see @ref{Kinds of Places}.

@subsubheading  Examples::

@example
 (setq x (cons 'a 'b) y (list 1 2 3)) @result{}  (1 2 3) 
 (setf (car x) 'x (cadr y) (car x) (cdr x) y) @result{}  (1 X 3) 
 x @result{}  (X 1 X 3) 
 y @result{}  (1 X 3) 
 (setq x (cons 'a 'b) y (list 1 2 3)) @result{}  (1 2 3) 
 (psetf (car x) 'x (cadr y) (car x) (cdr x) y) @result{}  NIL 
 x @result{}  (X 1 A 3) 
 y @result{}  (1 A 3) 
@end example

@subsubheading  Affected By::

@b{define-setf-expander},
@b{defsetf},
@b{*macroexpand-hook*}

@subsubheading  See Also::

@ref{define-setf-expander}
,
@ref{defsetf}
,
@b{macroexpand-1},
@ref{rotatef}
,
@ref{shiftf}
,
@ref{Generalized Reference}

@node shiftf, rotatef, setf, Data and Control Flow Dictionary
@subsection shiftf                                                              [Macro]

@code{shiftf}  @i{@{@i{place}@}^+ newvalue} @result{}  @i{old-value-1}

@subsubheading  Arguments and Values::

@i{place}---a @i{place}.

@i{newvalue}---a @i{form}; evaluated.

@i{old-value-1}---an @i{object} (the old @i{value} of the first @i{place}).

@subsubheading  Description::

@b{shiftf} modifies the values of each
@i{place} by storing @i{newvalue}
into the last @i{place}, and shifting the 
values of the second through the last @i{place}
into the remaining @i{places}.

If @i{newvalue} produces more values than there
are store variables, the extra values are ignored. If @i{newvalue}
produces fewer values than there are store variables, the missing values
are set to @b{nil}.

In the form @t{(shiftf @i{place1} @i{place2} ... @i{placen} @i{newvalue})}, 
the values in @i{place1} through @i{placen} are @i{read} and saved,
and @i{newvalue} is evaluated, for a total of @t{n}+1 values in all.
Values 2 through @t{n}+1 are then stored into @i{place1} through @i{placen}, respectively.
It is as if all the @i{places} form a shift register; the @i{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 @i{evaluation} of @i{subforms} of @i{places},
see @ref{Evaluation of Subforms to Places}.  

@subsubheading  Examples::

@example
 (setq x (list 1 2 3) y 'trash) @result{}  TRASH
 (shiftf y x (cdr x) '(hi there)) @result{}  TRASH
 x @result{}  (2 3)
 y @result{}  (1 HI THERE)

 (setq x (list 'a 'b 'c)) @result{}  (A B C)
 (shiftf (cadr x) 'z) @result{}  B
 x @result{}  (A Z C)
 (shiftf (cadr x) (cddr x) 'q) @result{}  Z
 x @result{}  (A (C) . Q)
 (setq n 0) @result{}  0
 (setq x (list 'a 'b 'c 'd)) @result{}  (A B C D)
 (shiftf (nth (setq n (+ n 1)) x) 'z) @result{}  B
 x @result{}  (A Z C D)
@end example

@subsubheading  Affected By::

@b{define-setf-expander},
@b{defsetf},
@b{*macroexpand-hook*}

@subsubheading  See Also::

@ref{setf; psetf}
, 
@ref{rotatef}
, @ref{Generalized Reference}

@subsubheading  Notes::

The effect of
 @t{(shiftf @i{place1} @i{place2} ... @i{placen} @i{newvalue})}
is roughly equivalent to

@example
 (let ((var1 @i{place1})
       (var2 @i{place2})
       ...
       (varn @i{placen})
       (var0 @i{newvalue}))
   (setf @i{place1} var2)
   (setf @i{place2} var3)
   ...
   (setf @i{placen} var0)
   var1)
@end example

except that the latter would evaluate any @i{subforms} 
of each @t{place} twice, whereas @b{shiftf} evaluates them once.
For example, 

@example
 (setq n 0) @result{}  0
 (setq x (list 'a 'b 'c 'd)) @result{}  (A B C D)
 (prog1 (nth (setq n (+ n 1)) x)
        (setf (nth (setq n (+ n 1)) x) 'z)) @result{}  B
 x @result{}  (A B Z D)
@end example

@node rotatef, control-error, shiftf, Data and Control Flow Dictionary
@subsection rotatef                                                             [Macro]

@code{rotatef}  @i{@{@i{place}@}{*}} @result{}  @i{@b{nil}}

@subsubheading  Arguments and Values::

@i{place}---a @i{place}.

@subsubheading  Description::

@b{rotatef} modifies the values of each @i{place} by
rotating values from one @i{place} into another.

If a @i{place} produces more values than there
are store variables, the extra values are ignored. If a @i{place}
produces fewer values than there are store variables, the missing values
are set to @b{nil}.

In the form @t{(rotatef @i{place1} @i{place2} ... @i{placen})}, 
the values in @i{place1} through @i{placen} are @i{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 @i{evaluation} of @i{subforms} of @i{places},
see @ref{Evaluation of Subforms to Places}.  

@subsubheading  Examples::
@example
 (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) @result{}  (A C D B E F G)
@end example

@subsubheading  See Also::

@ref{define-setf-expander}
,
@ref{defsetf}
,
@ref{setf; psetf}
,
@ref{shiftf}
,
@b{*macroexpand-hook*},
@ref{Generalized Reference}

@subsubheading  Notes::

The effect of
 @t{(rotatef @i{place1} @i{place2} ... @i{placen})}
is roughly equivalent to

@example
 (psetf @i{place1} @i{place2}
        @i{place2} @i{place3}
        ...
        @i{placen} @i{place1})
@end example

except that the latter would evaluate any @i{subforms}
of each @t{place} twice, whereas @b{rotatef} evaluates them once.

@node control-error, program-error, rotatef, Data and Control Flow Dictionary
@subsection control-error                                              [Condition Type]

@subsubheading  Class Precedence List::
@b{control-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}

@subsubheading  Description::

The @i{type} @b{control-error} consists of error conditions that result from
invalid dynamic transfers of control in a program.  The errors that
result from giving @b{throw} a tag that is not active or from
giving @b{go} or @b{return-from} a tag that is no longer
dynamically available are of @i{type} @b{control-error}.

@node program-error, undefined-function, control-error, Data and Control Flow Dictionary
@subsection program-error                                              [Condition Type]

@subsubheading  Class Precedence List::
@b{program-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}

@subsubheading  Description::

The @i{type} @b{program-error}
consists of error conditions related to incorrect program syntax.  The
errors that result from naming a @i{go tag} or a @i{block tag}
that is not lexically apparent are of @i{type} @b{program-error}.

@node undefined-function,  , program-error, Data and Control Flow Dictionary
@subsection undefined-function                                         [Condition Type]

@subsubheading  Class Precedence List::
@b{undefined-function},
@b{cell-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}

@subsubheading  Description::

The @i{type} @b{undefined-function} consists of @i{error} @i{conditions}
that represent attempts to @i{read} the definition of an @i{undefined function}.

The name of the cell (see @b{cell-error}) is the @i{function name}
which was @i{funbound}.

@subsubheading  See Also::

@ref{cell-error-name}

@c end of including dict-flow

@c %**end of chapter