@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/functions
@node Functions, Macros, Variables, Top
@c @chapter Functions
@chapter $B4X?t(B

@c   A Lisp program is composed mainly of Lisp functions.  This chapter
@c explains what functions are, how they accept arguments, and how to
@c define them.
Lisp$B%W%m%0%i%`$O!"<g$K(BLisp$B4X?t$+$i9=@.$5$l$^$9!#(B
$BK\>O$G$O!"4X?t$H$O$J$K$+!"0z?t$r$I$N$h$&$K<u$1<h$k$N$+!"(B
$B$I$N$h$&$K4X?t$rDj5A$9$k$N$+$r@bL@$7$^$9!#(B

@menu
* What Is a Function::    Lisp functions vs. primitives; terminology.
* Lambda Expressions::    How functions are expressed as Lisp objects.
* Function Names::        A symbol can serve as the name of a function.
* Defining Functions::    Lisp expressions for defining functions.
* Calling Functions::     How to use an existing function.
* Mapping Functions::     Applying a function to each element of a list, etc.
* Anonymous Functions::   Lambda expressions are functions with no names.    
* Function Cells::        Accessing or setting the function definition
                            of a symbol.
* Inline Functions::	  Defining functions that the compiler will open code.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.
@end menu

@node What Is a Function
@c @section What Is a Function?
@section $B4X?t$H$O$J$K$+(B

@c   In a general sense, a function is a rule for carrying on a computation
@c given several values called @dfn{arguments}.  The result of the
@c computation is called the value of the function.  The computation can
@c also have side effects: lasting changes in the values of variables or
@c the contents of data structures.
$B0lHLE*$K$O!"4X?t$H$O!"(B@dfn{$B0z?t(B}$B!J(Barguments$B!K$H8F$P$l$kCM$rM?$($i$l!"(B
$B7W;;$r9T$&$?$a$N5,B'$G$9!#(B
$B$3$N7W;;7k2L$r4X?t$NCM$H8F$S$^$9!#(B
$B7W;;$G$OI{:nMQ!"$D$^$j!"JQ?t$NCM$d%G!<%?9=B$$NFbMF$K7QB3$9$kJQ99(B
$B$rH<$&$3$H$b$G$-$^$9!#(B

@c   Here are important terms for functions in Emacs Lisp and for other
@c function-like objects.
Emacs Lisp$B$N4X?t$d4X?t$N$h$&$J%*%V%8%'%/%H$K4X$9$k=EMW$JMQ8l$r$"$2$F$*$-$^$9!#(B

@table @dfn
@c @item function
@item $B4X?t(B
@c @cindex function
@cindex $B4X?t(B
@c In Emacs Lisp, a @dfn{function} is anything that can be applied to
@c arguments in a Lisp program.  In some cases, we use it more
@c specifically to mean a function written in Lisp.  Special forms and
@c macros are not functions.
Emacs Lisp$B$G$O!"(BLisp$B%W%m%0%i%`$K$*$$$F0z?t$KE,MQ2DG=$b$N$O(B
$B$J$s$G$"$l(B@dfn{$B4X?t(B}$B!J(Bfunction$B!K$G$"$k!#(B
Lisp$B$G=q$$$?4X?t$r0UL#$9$k>l9g$b$"$k!#(B
$B%9%Z%7%c%k%U%)!<%`$d%^%/%m$O4X?t$G$O$J$$!#(B

@c @item primitive
@item $B4pK\4X?t(B
@c @cindex primitive
@cindex $B4pK\4X?t(B
@cindex subr
@c @cindex built-in function
@cindex $BAH$_9~$_4X?t(B
@c A @dfn{primitive} is a function callable from Lisp that is written in C,
@c such as @code{car} or @code{append}.  These functions are also called
@c @dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
@c considered primitives.)
@dfn{$B4pK\4X?t(B}$B!J(Bprimitive$B!K$O!"(B@code{car}$B$d(B@code{append}$B$J$I$N(BC$B$G=q$$$?(B
Lisp$B$+$i8F$S=P$72DG=$J4X?t$G$"$k!#(B
$B$3$l$i$N4X?t$O!"(B@dfn{$BAH$_9~$_(B}$B4X?t$H$+(B@dfn{subrs}$B$H$b8F$V!#(B
$B!J%9%Z%7%c%k%U%)!<%`$O4pK\4X?t$H$b9M$($i$l$k!#!K(B

@c Usually the reason we implement a function as a primitive is either
@c because it is fundamental, because it provides a low-level interface to
@c operating system services, or because it needs to run fast.  Primitives
@c can be modified or added only by changing the C sources and recompiling
@c the editor.  See @ref{Writing Emacs Primitives}.
$B4X?t$r4pK\4X?t$H$7$F<BAu$9$kM}M3$O!"(B
$B$=$l$,4pK\E*$J$b$N$G$"$k!"(B
$B$=$l$,%*%Z%l!<%F%#%s%0%7%9%F%`$N5!G=$KBP$9$k(B
$BDc%l%Y%k$N%$%s%?!<%U%'%$%9$rDs6!$9$k!"(B
$B$"$k$$$O!"9bB.$KF0:n$9$kI,MW$,$"$k$+$i$G$"$k!#(B
$B4pK\4X?t$rJQ99$7$?$jDI2C$9$kM#0l$NJ}K!$O!"(B
C$B%=!<%9$rJQ99$7$F%(%G%#%?$r:F%3%s%Q%$%k$9$k$3$H$G$"$k!#(B
@pxref{Writing Emacs Primitives}$B!#(B

@c @item lambda expression
@item $B%i%`%@<0(B
@c A @dfn{lambda expression} is a function written in Lisp.
@c These are described in the following section.
@dfn{$B%i%`%@<0(B}$B!J(Blambda expression$B!K$O!"(BLisp$B$G=q$$$?4X?t$G$"$k!#(B
$B$3$l$i$K$D$$$F$O0J2<$N@a$G@bL@$9$k!#(B
@ifinfo
@c @xref{Lambda Expressions}.
@xref{Lambda Expressions}$B!#(B
@end ifinfo

@c @item special form
@item $B%9%Z%7%c%k%U%)!<%`(B
@c A @dfn{special form} is a primitive that is like a function but does not
@c evaluate all of its arguments in the usual way.  It may evaluate only
@c some of the arguments, or may evaluate them in an unusual order, or
@c several times.  Many special forms are described in @ref{Control
@c Structures}.
@dfn{$B%9%Z%7%c%k%U%)!<%`(B}$B!J(Bspecial form$B!K$O4X?t$K;w$?4pK\4X?t$G$"$k$,!"(B
$B$=$N0z?t$9$Y$F$rIaDL$N$h$&$K$OI>2A$7$J$$!#(B
$B0z?t$N0lIt$rI>2A$7$?$j!"IaDL$H$O0[$J$k=g=x$GI>2A$7$?$j!"(B
$BJ#?t2sI>2A$7$?$j$9$k!#(B
$BB?$/$N%9%Z%7%c%k%U%)!<%`$K$D$$$F$O!"(B
@ref{Control Structures}$B$G@bL@$7$F$"$k!#(B

@c @item macro
@item $B%^%/%m(B
@c @cindex macro
@cindex $B%^%/%m(B
@c A @dfn{macro} is a construct defined in Lisp by the programmer.  It
@c differs from a function in that it translates a Lisp expression that you
@c write into an equivalent expression to be evaluated instead of the
@c original expression.  Macros enable Lisp programmers to do the sorts of
@c things that special forms can do.  @xref{Macros}, for how to define and
@c use macros.
@dfn{$B%^%/%m(B}$B!J(Bmacro$B!K$O!"%W%m%0%i%^$,(BLisp$B$GDj5A$7$?9=J8$G$"$k!#(B
$B%^%/%m$H4X?t$H$N0c$$$O!"%^%/%m$O!"(B
$BFI<T$,=q$$$?(BLisp$B<0$r$b$H$N<0$N$+$o$j$KI>2A$5$l$kEy2A$J<0$KJQ49$9$k!#(B
$B%^%/%m$O!"%9%Z%7%c%k%U%)!<%`$G$G$-$k<oN`$N$3$H$r(B
Lisp$B%W%m%0%i%^$KDs6!$9$k!#(B
$B%^%/%m$NDj5AJ}K!$H;H$$J}$K$D$$$F$O!"(B@pxref{Macros}$B!#(B

@c @item command
@item $B%3%^%s%I(B
@c @cindex command
@cindex $B%3%^%s%I(B
@c A @dfn{command} is an object that @code{command-execute} can invoke; it
@c is a possible definition for a key sequence.  Some functions are
@c commands; a function written in Lisp is a command if it contains an
@c interactive declaration (@pxref{Defining Commands}).  Such a function
@c can be called from Lisp expressions like other functions; in this case,
@c the fact that the function is a command makes no difference.
@dfn{$B%3%^%s%I(B}$B!J(Bcommand$B!K$H$O!"(B
@code{command-execute}$B$,5/F0$G$-$k%*%V%8%'%/%H$G$"$j!"(B
$B%-!<Ns$KBP$7$FDj5A$G$-$k!#(B
$B$$$/$D$+$N4X?t$O%3%^%s%I$G$"$k!#(B
Lisp$B$G=q$$$?4X?t$KBPOC@k8@!J(B@pxref{Defining Commands}$B!K$,4^$^$l$F$$$k$H$-!"(B
$B$=$N4X?t$O%3%^%s%I$G$"$k!#(B
$B$=$N$h$&$J4X?t$O!"B>$N4X?t$HF1MM$K(BLisp$B<0$+$i8F$S=P$9$3$H$,$G$-$k!#(B
$B$=$N>l9g!"4X?t$,%3%^%s%I$G$"$k$H$$$&;v<B$O4X78$J$$!#(B

@c Keyboard macros (strings and vectors) are commands also, even though
@c they are not functions.  A symbol is a command if its function
@c definition is a command; such symbols can be invoked with @kbd{M-x}.
@c The symbol is a function as well if the definition is a function.
@c @xref{Command Overview}.
$B%-!<%\!<%I%^%/%m!JJ8;zNs$+%Y%/%H%k!K$b%3%^%s%I$G$"$k$,!"(B
$B$=$l$i$O4X?t$G$O$J$$!#(B
$B%7%s%\%k$N4X?tDj5A$,%3%^%s%I$G$"$l$P!"%7%s%\%k$O%3%^%s%I$G$"$k!#(B
$B$=$N$h$&$J%7%s%\%k$O!"(B@kbd{M-x}$B$G5/F0$G$-$k!#(B
$B%7%s%\%k$NDj5A$,4X?t$G$"$l$P!"%7%s%\%k$O4X?t$G$b$"$k!#(B

@c @item keystroke command
@item $BBG80%3%^%s%I(B
@c @cindex keystroke command
@cindex $BBG80%3%^%s%I(B
@c A @dfn{keystroke command} is a command that is bound to a key sequence
@c (typically one to three keystrokes).  The distinction is made here
@c merely to avoid confusion with the meaning of ``command'' in non-Emacs
@c editors; for Lisp programs, the distinction is normally unimportant.
@dfn{$BBG80%3%^%s%I(B}$B!J(Bkeystroke command$B!K$H$O!"(B
$B%-!<Ns!JE57?E*$K$O(B1$B$+$i(B3$BBG80!K$K%P%$%s%I$5$l$?%3%^%s%I$G$"$k!#(B
$B$3$3$G$N6hJL$O!"(BEmacs$B0J30$N%(%G%#%?$N!X%3%^%s%I!Y$N0UL#$H$N(B
$B:.Mp$rKI$0$?$a$G$"$k$,!"(B
Lisp$B%W%m%0%i%`$K$H$C$F$O!"$3$N6hJL$OIaDL$O=EMW$G$O$J$$!#(B

@c @item byte-code function
@item $B%P%$%H%3!<%I4X?t(B
@c A @dfn{byte-code function} is a function that has been compiled by the
@c byte compiler.  @xref{Byte-Code Type}.
@dfn{$B%P%$%H%3!<%I4X?t(B}$B!J(Bbyte-code function$B!K$H$O!"(B
$B%P%$%H%3%s%Q%$%i$G%3%s%Q%$%k$7$?4X?t$G$"$k!#(B
@pxref{Byte-Code Type}$B!#(B
@end table

@defun functionp object
@tindex functionp
@c This function returns @code{t} if @var{object} is any kind of function,
@c or a special form or macro.
$B$3$N4X?t$O!"(B@var{object}$B$,!"$J$s$i$+$N4X?t!"%9%Z%7%c%k%U%)!<%`!"(B
$B%^%/%m$G$"$l$P!"(B@code{t}$B$rJV$9!#(B
@end defun

@defun subrp object
@c This function returns @code{t} if @var{object} is a built-in function
@c (i.e., a Lisp primitive).
$B$3$N4X?t$O!"(B@var{object}$B$,AH$_9~$_4X?t!J$D$^$j!"(BLisp$B4pK\4X?t!K$G$"$l$P(B
@code{t}$B$rJV$9!#(B

@example
@group
@c (subrp 'message)            ; @r{@code{message} is a symbol,}
@c      @result{} nil                 ;   @r{not a subr object.}
(subrp 'message)            ; @r{@code{message}$B$O%7%s%\%k$G$"$j!"(B}
     @result{} nil                 ;   @r{subr$B%*%V%8%'%/%H$G$O$J$$(B}
@end group
@group
(subrp (symbol-function 'message))
     @result{} t
@end group
@end example
@end defun

@defun byte-code-function-p object
@c This function returns @code{t} if @var{object} is a byte-code
@c function.  For example:
$B$3$N4X?t$O!"(B@var{object}$B$,%P%$%H%3!<%I4X?t$G$"$l$P(B@code{t}$B$rJV$9!#(B
$B$?$H$($P!"$D$.$N$H$*$j!#(B

@example
@group
(byte-code-function-p (symbol-function 'next-line))
     @result{} t
@end group
@end example
@end defun

@node Lambda Expressions
@c @section Lambda Expressions
@section $B%i%`%@<0(B
@c @cindex lambda expression
@cindex $B%i%`%@<0(B

@c   A function written in Lisp is a list that looks like this:
Lisp$B$G=q$$$?4X?t$O$D$.$N$h$&$J%j%9%H$G$9!#(B

@example
(lambda (@var{arg-variables}@dots{})
  @r{[}@var{documentation-string}@r{]}
  @r{[}@var{interactive-declaration}@r{]}
  @var{body-forms}@dots{})
@end example

@noindent
@c Such a list is called a @dfn{lambda expression}.  In Emacs Lisp, it
@c actually is valid as an expression---it evaluates to itself.  In some
@c other Lisp dialects, a lambda expression is not a valid expression at
@c all.  In either case, its main use is not to be evaluated as an
@c expression, but to be called as a function.
$B$3$N$h$&$J%j%9%H$r(B@dfn{$B%i%`%@<0(B}$B!J(Blambda expression$B!K$H8F$S$^$9!#(B
Emacs Lisp$B$G$O!"$3$l$O<0$H$7$F@5$7$$$b$N$G!"(B
$B$=$l<+?H$KI>2A$5$l$^$9!#(B
Lisp$B$NB>$NJ}8@$G$O!"%i%`%@<0$O@5$7$$<0$G$O$"$j$^$;$s!#(B
$B$$$:$l$N>l9g$G$b!"$=$N<g$JMQES$O<0$H$7$FI>2A$9$k$3$H$G$O$J$/!"(B
$B4X?t$H$7$F8F$S=P$9$3$H$G$9!#(B

@menu
* Lambda Components::       The parts of a lambda expression.
* Simple Lambda::           A simple example.
* Argument List::           Details and special features of argument lists.
* Function Documentation::  How to put documentation in a function.
@end menu

@node Lambda Components
@c @subsection Components of a Lambda Expression
@subsection $B%i%`%@<0$N9=@.MWAG(B

@ifinfo

@c   A function written in Lisp (a ``lambda expression'') is a list that
@c looks like this:
Lisp$B$G=q$$$?4X?t!J!X%i%`%@<0!Y!K$O$D$.$N$h$&$J%j%9%H$G$9!#(B

@example
(lambda (@var{arg-variables}@dots{})
  [@var{documentation-string}]
  [@var{interactive-declaration}]
  @var{body-forms}@dots{})
@end example
@end ifinfo

@c @cindex lambda list
@cindex $B%i%`%@%j%9%H(B
@c   The first element of a lambda expression is always the symbol
@c @code{lambda}.  This indicates that the list represents a function.  The
@c reason functions are defined to start with @code{lambda} is so that
@c other lists, intended for other uses, will not accidentally be valid as
@c functions.
$B%i%`%@<0$N@hF,MWAG$O!"$D$M$K%7%s%\%k(B@code{lambda}$B$G$9!#(B
$B$3$N%7%s%\%k$O!"%j%9%H$,4X?t$rI=$9$3$H$r<($7$^$9!#(B
$B4X?t$O(B@code{lambda}$B$G;O$^$k$HDj5A$7$F$"$k$N$O!"(B
$BB>$NL\E*8~$1$NB>$N%j%9%H$,8m$C$F@5$7$$4X?t$H$J$i$J$$$h$&$K$9$k$?$a$G$9!#(B

@c   The second element is a list of symbols---the argument variable names.
@c This is called the @dfn{lambda list}.  When a Lisp function is called,
@c the argument values are matched up against the variables in the lambda
@c list, which are given local bindings with the values provided.
@c @xref{Local Variables}.
$BBh(B2$BMWAG$O!"%7%s%\%k$N%j%9%H!"$D$^$j!"0z?tJQ?tL>$G$9!#(B
$B$3$l$r(B@dfn{$B%i%`%@%j%9%H(B}$B!J(Blambda list$B!K$H8F$S$^$9!#(B
Lisp$B4X?t$,8F$P$l$k$H!"0z?tCM$r%i%`%@%j%9%H$NJQ?t$KBP1~$5$;!"(B
$B;XDj$7$?CM$r;}$D%m!<%+%kB+G{$K$J$j$^$9!#(B
@xref{Local Variables}$B!#(B

@c   The documentation string is a Lisp string object placed within the
@c function definition to describe the function for the Emacs help
@c facilities.  @xref{Function Documentation}.
$B@bL@J8;zNs$O!"4X?tDj5A$NFbB&$K$"$k(BLisp$BJ8;zNs%*%V%8%'%/%H$G$"$j!"(B
Emacs$B$N%X%k%W5!G=$KBP$7$F4X?t$r5-=R$7$^$9!#(B
@xref{Function Documentation}$B!#(B

@c   The interactive declaration is a list of the form @code{(interactive
@c @var{code-string})}.  This declares how to provide arguments if the
@c function is used interactively.  Functions with this declaration are called
@c @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
@c Functions not intended to be called in this way should not have interactive
@c declarations.  @xref{Defining Commands}, for how to write an interactive
@c declaration.
$BBPOC@k8@$O!"(B@code{(interactive @var{code-string})}$B$N7A<0$N%j%9%H$G$9!#(B
$B$3$N@k8@$O!"4X?t$,BPOCE*$K;H$o$l$?$H$-$K!"(B
$B$I$N$h$&$K0z?t$rM?$($k$+$r;XDj$7$^$9!#(B
$B$3$N@k8@$rM-$9$k4X?t$r(B@dfn{$B%3%^%s%I(B}$B!J(Bcommands$B!K$H8F$S$^$9!#(B
$B%3%^%s%I$O!"(B@kbd{M-x}$B$G8F$S=P$7$?$j!"%-!<$K%P%$%s%I$G$-$^$9!#(B
$B$3$N$h$&$K8F$P$l$k$3$H$r0U?^$7$F$$$J$$4X?t$K$O!"(B
$BBPOC@k8@$rIU$1$F$O$$$1$^$;$s!#(B
$BBPOC@k8@$N=q$-J}$K$D$$$F$O!"(B@xref{Defining Commands}$B!#(B

@c @cindex body of function
@cindex $B4X?tK\BN(B
@c   The rest of the elements are the @dfn{body} of the function: the Lisp
@c code to do the work of the function (or, as a Lisp programmer would say,
@c ``a list of Lisp forms to evaluate'').  The value returned by the
@c function is the value returned by the last element of the body.
$B;D$j$NMWAG$O!"4X?t$N(B@dfn{$BK\BN(B}$B!J(Bbody$B!K$G$9!#(B
$B4X?t$NF0:n$r9T$&(BLisp$B%3!<%I$G$9(B
$B!J(BLisp$B%W%m%0%i%^$H$7$F$O!"!XI>2A$9$k$Y$-(BLisp$B%U%)!<%`$N%j%9%H!Y$H$$$&!K!#(B
$B4X?t$,JV$9CM$O!"K\BN$N:G8e$NMWAG$,JV$9CM$G$9!#(B

@node Simple Lambda
@c @subsection A Simple Lambda-Expression Example
@subsection $B4JC1$J%i%`%@<0$NNc(B

@c   Consider for example the following function:
$B$D$.$N4X?t$r9M$($F$_$^$7$g$&!#(B

@example
(lambda (a b c) (+ a b c))
@end example

@noindent
@c We can call this function by writing it as the @sc{car} of an
@c expression, like this:
$B$3$N4X?t$r8F$S=P$9$K$O!"$D$.$N$h$&$K<0$N(B@sc{car}$B$K$3$N4X?t$r=q$-$^$9!#(B

@example
@group
((lambda (a b c) (+ a b c))
 1 2 3)
@end group
@end example

@noindent
@c This call evaluates the body of the lambda expression  with the variable
@c @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
@c Evaluation of the body adds these three numbers, producing the result 6;
@c therefore, this call to the function returns the value 6.
$B$3$N8F$S=P$7$O!"JQ?t(B@code{a}$B$K$O(B1$B!"JQ?t(B@code{b}$B$K$O(B2$B!"(B
$BJQ?t(B@code{c}$B$K$O(B3$B$rB+G{$7!"%i%`%@<0$NK\BN$rI>2A$7$^$9!#(B
$BK\BN$NI>2A$G$O$3$l$i$r2C;;$7!"7k2L(B6$B$r@8$8$^$9!#(B
$B$7$?$,$C$F!"$3$N4X?t8F$S=P$7$O(B6$B$rJV$7$^$9!#(B

@c   Note that the arguments can be the results of other function calls, as in
@c this example:
$B$D$.$NNc$N$h$&$K!"B>$N4X?t8F$S=P$7$N7k2L$,0z?t$K$J$k$3$H$b$"$j$^$9!#(B

@example
@group
((lambda (a b c) (+ a b c))
 1 (* 2 3) (- 5 4))
@end group
@end example

@noindent
@c This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
@c 4)} from left to right.  Then it applies the lambda expression to the
@c argument values 1, 6 and 1 to produce the value 8.
$B$3$l$O!"0z?t!"(B@code{1}$B!"(B@code{(* 2 3)}$B!"(B@code{(- 5 4)}$B$r(B
$B:8$+$i1&$X=g$KI>2A$7$^$9!#(B
$B$=$7$F!"0z?tCM!"(B1$B!"(B6$B!"(B1$B$K%i%`%@<0$rE,MQ$7!"CM(B8$B$r@8$8$^$9!#(B

@c   It is not often useful to write a lambda expression as the @sc{car} of
@c a form in this way.  You can get the same result, of making local
@c variables and giving them values, using the special form @code{let}
@c (@pxref{Local Variables}).  And @code{let} is clearer and easier to use.
@c In practice, lambda expressions are either stored as the function
@c definitions of symbols, to produce named functions, or passed as
@c arguments to other functions (@pxref{Anonymous Functions}).
$B$3$N$h$&$K%U%)!<%`$N(B@sc{car}$B$H$7$F%i%`%@<0$r=q$/$N$O!"(B
$B$"$^$jJXMx$G$O$"$j$^$;$s!#(B
$B%9%Z%7%c%k%U%)!<%`(B@code{let}$B!J(B@pxref{Local Variables}$B!K$r;H$C$F!"(B
$B%m!<%+%kJQ?t$r:n$C$F$=$l$i$KCM$rM?$($F$b!"F1$87k2L$rF@$i$l$^$9!#(B
$B$5$i$K!"(B@code{let}$B$O8+DL$7$,$h$/;H$$$d$9$$$G$9!#(B
$B<BMQ>e!"%i%`%@<0$O!"%7%s%\%k$N4X?tDj5A$H$7$F3JG<$7$FL>A0IU$-4X?t$r:n$k$+!"(B
$BB>$N4X?t$K0z?t$H$7$FEO$7$^$9!J(B@pxref{Anonymous Functions}$B!K!#(B

@c   However, calls to explicit lambda expressions were very useful in the
@c old days of Lisp, before the special form @code{let} was invented.  At
@c that time, they were the only way to bind and initialize local
@c variables.
$B$7$+$7$J$,$i!"%9%Z%7%c%k%U%)!<%`(B@code{let}$B$,$J$+$C$?=i4|$N(BLisp$B$G$O!"(B
$B%i%`%@<0$rL@<(E*$K8F$S=P$9$3$H$O$H$F$bJXMx$G$7$?!#(B
$B$=$N:"$G$O!"%i%`%@<0$O%m!<%+%kJQ?t$rB+G{$7=i4|2=$9$kM#0l$NJ}K!$G$7$?!#(B

@node Argument List
@c @subsection Other Features of Argument Lists
@subsection $B0z?t%j%9%H$N$=$NB>$N5!G=(B
@kindex wrong-number-of-arguments
@c @cindex argument binding
@c @cindex binding arguments
@cindex $B0z?tB+G{(B
@cindex $B0z?t$rB+G{$9$k(B

@c   Our simple sample function, @code{(lambda (a b c) (+ a b c))},
@c specifies three argument variables, so it must be called with three
@c arguments: if you try to call it with only two arguments or four
@c arguments, you get a @code{wrong-number-of-arguments} error.
$BC1=c$J4X?t$NNc(B@code{(lambda (a b c) (+ a b c))}$B$G$O!"(B
3$B$D$N0z?tJQ?t$r;XDj$7$F$$$k$N$G!"$3$l$O(B3$B0z?t$G8F$S=P$9I,MW$,$"$j$^$9!#(B
2$B0z?t$d(B4$B0z?t$G8F$S=P$=$&$H$9$k$H!"(B
$B%(%i!<(B@code{wrong-number-of-arguments}$B$K$J$j$^$9!#(B

@c   It is often convenient to write a function that allows certain
@c arguments to be omitted.  For example, the function @code{substring}
@c accepts three arguments---a string, the start index and the end
@c index---but the third argument defaults to the @var{length} of the
@c string if you omit it.  It is also convenient for certain functions to
@c accept an indefinite number of arguments, as the functions @code{list}
@c and @code{+} do.
$BFCDj$N0z?t$r>JN,$G$-$k4X?t$r=q$1$k$HJXMx$J$3$H$,$7$P$7$P$"$j$^$9!#(B
$B$?$H$($P!"4X?t(B@code{substring}$B$O(B3$B$D$N0z?t!"$D$^$j!"(B
$BJ8;zNs!"3+;O$H=*N;$NE:;z$r<h$j$^$9$,!"(B
$BBh(B3$B0z?t$r>JN,$9$k$H%G%U%)%k%H$OJ8;zNs$N(B@var{length}$B$K$J$j$^$9!#(B
@code{list}$B$d(B@code{+}$B$N$h$&$K!"(B
$BFCDj$N4X?t$G$OG$0U8D?t$N0z?t$r<u$1IU$1$k$HJXMx$J$3$H$b$"$j$^$9!#(B

@c @cindex optional arguments
@c @cindex rest arguments
@cindex optional$B0z?t(B
@cindex rest$B0z?t(B
@kindex &optional
@kindex &rest
@c   To specify optional arguments that may be omitted when a function
@c is called, simply include the keyword @code{&optional} before the optional
@c arguments.  To specify a list of zero or more extra arguments, include the
@c keyword @code{&rest} before one final argument.
$B4X?t8F$S=P$7;~$K>JN,$7$F$b$h$$0z?t$r;XDj$9$k$K$O!"(B
$B>JN,2DG=$J0z?t$N$^$($K%-!<%o!<%I(B@code{&optional}$B$r4^$a$k$@$1$G$9!#(B
0$B8D0J>e$N0z?t$N%j%9%H$r;XDj$9$k$K$O!"(B
$B:G8e$N0z?t$N$^$($K%-!<%o!<%I(B@code{&rest}$B$r4^$a$^$9!#(B

@c   Thus, the complete syntax for an argument list is as follows:
$B$7$?$,$C$F!"0z?t%j%9%H$N40A4$J9=J8$O$D$.$N$h$&$K$J$j$^$9!#(B

@example
@group
(@var{required-vars}@dots{}
               ; @r{$BI,?\$N0z?t(B}
 @r{[}&optional @var{optional-vars}@dots{}@r{]}
               ; @r{$B>JN,2DG=$J0z?t(B}
 @r{[}&rest @var{rest-var}@r{]})
               ; @r{$B;D$j$N0z?t(B}
@end group
@end example

@noindent
@c The square brackets indicate that the @code{&optional} and @code{&rest}
@c clauses, and the variables that follow them, are optional.
$B3Q3g8L$O!"(B@code{&optional}$B$d(B@code{&rest}$B$N@a$d(B
$B$=$l$KB3$/JQ?t$O>JN,$G$-$k$3$H$r<($7$^$9!#(B

@c   A call to the function requires one actual argument for each of the
@c @var{required-vars}.  There may be actual arguments for zero or more of
@c the @var{optional-vars}, and there cannot be any actual arguments beyond
@c that unless the lambda list uses @code{&rest}.  In that case, there may
@c be any number of extra actual arguments.
$B4X?t8F$S=P$7;~$K$O!"3F(B@var{required-vars}$B$K(B1$B$D$N<B0z?t$,I,MW$G$9!#(B
0$B8D0J>e$N(B@var{optional-vars}$B$K$b<B0z?t$,I,MW$G$9$,!"(B
$B%i%`%@%j%9%H$K(B@code{&rest}$B$,$J$$8B$j!"(B
@var{optional-vars}$B$N8D?t$rD6$($k<B0z?t$O;XDj$G$-$^$;$s!#(B
@code{&rest}$B$,$"$l$P!"G$0U8D$NM>J,$J<B0z?t$r;XDj$G$-$^$9!#(B

@c   If actual arguments for the optional and rest variables are omitted,
@c then they always default to @code{nil}.  There is no way for the
@c function to distinguish between an explicit argument of @code{nil} and
@c an omitted argument.  However, the body of the function is free to
@c consider @code{nil} an abbreviation for some other meaningful value.
@c This is what @code{substring} does; @code{nil} as the third argument to
@c @code{substring} means to use the length of the string supplied.
@code{&optional}$B$d(B@code{&rest}$B$KBP1~$9$k<B0z?t$r>JN,$9$k$H!"(B
$B$=$l$i$N%G%U%)%k%H$O(B@code{nil}$B$G$9!#(B
$B4X?t$G$O!"(B@code{nil}$B$rL@<($7$?0z?t$H>JN,$7$?0z?t$H$r6hJL$9$kJ}K!$O$"$j$^$;$s!#(B
$B$7$+$7$J$,$i!"4X?tK\BN$G(B@code{nil}$B$rE,@Z$J0UL#$"$kCM$N>JN,$H(B
$B$_$J$9$3$H$O<+M3$G$9!#(B
@code{substring}$B$O$=$N$h$&$K$7$F$$$^$9!#(B
@code{substring}$B$NBh(B3$B0z?t$,(B@code{nil}$B$G$"$k$H!"(B
$B;XDj$7$?J8;zNs$ND9$5$r;H$&$3$H$r0UL#$7$^$9!#(B

@c @cindex CL note---default optional arg
@cindex CL$B$K4X$7$?Cm0U!]!]>JN,2DG=0z?t$N%G%U%)%k%H(B
@quotation
@c @b{Common Lisp note:} Common Lisp allows the function to specify what
@c default value to use when an optional argument is omitted; Emacs Lisp
@c always uses @code{nil}.  Emacs Lisp does not support ``supplied-p''
@c variables that tell you whether an argument was explicitly passed.
@b{Common Lisp$B$K4X$7$?Cm0U!'(B}@code{ }
Common Lisp$B$G$O!">JN,2DG=0z?t$r>JN,$7$?$H$-$N%G%U%)%k%HCM$r4X?t$G;XDj$G$-$k!#(B
Emacs Lisp$B$G$O$D$M$K(B@code{nil}$B$r;H$&!#(B
Emacs Lisp$B$K$O!"L@<(E*$K0z?t$r;XDj$7$?$+$I$&$+D4$Y$k(B
$B!X(Bsupplied-p$B!YJQ?t$O$J$$!#(B
@end quotation

@c   For example, an argument list that looks like this:
$B$?$H$($P!"0z?t%j%9%H$O$D$.$N$h$&$K$J$j$^$9!#(B

@example
(a b &optional c d &rest e)
@end example

@noindent
@c binds @code{a} and @code{b} to the first two actual arguments, which are
@c required.  If one or two more arguments are provided, @code{c} and
@c @code{d} are bound to them respectively; any arguments after the first
@c four are collected into a list and @code{e} is bound to that list.  If
@c there are only two arguments, @code{c} is @code{nil}; if two or three
@c arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
@c is @code{nil}.
$B$3$l$O!"(B@code{a}$B$H(B@code{b}$B$K:G=i$N(B2$B$D$N<B0z?t$rB+G{$7!"$3$l$i$OI,?\$G$9!#(B
$B$5$i$K(B1$B8D$+(B2$B8D$N0z?t$r;XDj$9$k$H!"(B
$B$=$l$i$O!"$=$l$>$l(B@code{c}$B$H(B@code{d}$B$KB+G{$7$^$9!#(B
$B:G=i$N(B4$B8D$h$j$"$H$N0z?t$O%j%9%H$K$^$H$a!"(B
@code{e}$B$K$=$N%j%9%H$rB+G{$7$^$9!#(B
$B0z?t$,(B2$B8D$@$1$G$"$k$H!"(B@code{c}$B$O(B@code{nil}$B$G$9!#(B
$B0z?t$,(B2$B8D$+(B3$B8D$@$1$G$"$k$H!"(B@code{d}$B$O(B@code{nil}$B$G$9!#(B
$B0z?t$,(B4$B8D0J2<$G$"$k$H!"(B@code{e}$B$O(B@code{nil}$B$G$9!#(B

@c   There is no way to have required arguments following optional
@c ones---it would not make sense.  To see why this must be so, suppose
@c that @code{c} in the example were optional and @code{d} were required.
@c Suppose three actual arguments are given; which variable would the third
@c argument be for?  Similarly, it makes no sense to have any more
@c arguments (either required or optional) after a @code{&rest} argument.
$B>JN,2DG=$J0z?t$N$"$H$KI,?\0z?t$r;XDj$9$kJ}K!$O$"$j$^$;$s$7!"(B
$B$=$l$K$O0UL#$,$"$j$^$;$s!#(B
$B$J$<$=$&$J$N$+$rM}2r$9$k$?$a$K!">e$NNc$G!"(B
@code{c}$B$O>JN,2DG=$G$"$j!"(B@code{d}$B$OI,?\$G$"$k$H$7$^$7$g$&!#(B
3$B$D$N<B0z?t$r;XDj$7$?$H$-!"$I$N0z?t$r(B3$BHVL\$H9M$($k$N$G$7$g$&!)(B@code{ }
$BF1MM$K!"(B@code{&rest}$B$N$&$7$m$KM>J,$K!JI,?\!"$b$7$/$O>JN,2DG=$J!K0z?t$,(B
$B$"$C$F$b0UL#$,$"$j$^$;$s!#(B

@c   Here are some examples of argument lists and proper calls:
$B0z?t%j%9%H$H@5$7$$8F$S=P$7$NNc$r$"$2$^$9!#(B

@smallexample
@c ((lambda (n) (1+ n))                ; @r{One required:}
@c  1)                                 ; @r{requires exactly one argument.}
((lambda (n) (1+ n))                ; @r{1$B8D$,I,?\(B}
 1)                                 ; @r{$B0z?t$O(B1$B8D$@$1(B}
     @result{} 2
@c ((lambda (n &optional n1)           ; @r{One required and one optional:}
@c          (if n1 (+ n n1) (1+ n)))   ; @r{1 or 2 arguments.}
((lambda (n &optional n1)           ; @r{1$B8D$OI,?\!"(B1$B8D$O>JN,2D(B}
         (if n1 (+ n n1) (1+ n)))   ; @r{$B0z?t$O(B1$B8D$+(B2$B8D(B}
 1 2)
     @result{} 3
@c ((lambda (n &rest ns)               ; @r{One required and one rest:}
@c          (+ n (apply '+ ns)))       ; @r{1 or more arguments.}
((lambda (n &rest ns)               ; @r{1$B8D$OI,?\!"$"$H$O;D$jA4It(B}
         (+ n (apply '+ ns)))       ; @r{$B0z?t$O(B1$B8D0J>e$$$/$D$G$b$h$$(B}
 1 2 3 4 5)
     @result{} 15
@end smallexample

@node Function Documentation
@c @subsection Documentation Strings of Functions
@subsection $B4X?t$N@bL@J8;zNs(B
@c @cindex documentation of function
@cindex $B4X?t$N@bL@J8;zNs(B
@cindex $B@bL@J8;zNs!"4X?t(B

@c   A lambda expression may optionally have a @dfn{documentation string} just
@c after the lambda list.  This string does not affect execution of the
@c function; it is a kind of comment, but a systematized comment which
@c actually appears inside the Lisp world and can be used by the Emacs help
@c facilities.  @xref{Documentation}, for how the @var{documentation-string} is
@c accessed.
$B%i%`%@<0$K$O!"%i%`%@%j%9%H$ND>8e$K(B
@dfn{$B@bL@J8;zNs(B}$B!J(Bdocumentation string$B!K$,$"$C$F$b$+$^$$$^$;$s!#(B
$B$3$NJ8;zNs$O4X?t$N<B9T$K$O1F6A$7$^$;$s!#(B
$B%3%a%s%H$N$h$&$J$b$N$G$9$,!"(BLisp$BFbIt$K8=$l$k7OE}E*$J%3%a%s%H$G$"$j!"(B
Emacs$B$N%X%k%W5!G=$,;HMQ$7$^$9!#(B
@var{documentation-string}$B$N;2>HJ}K!$K$D$$$F$O!"(B@xref{Documentation}$B!#(B

@c   It is a good idea to provide documentation strings for all the
@c functions in your program, even those that are called only from within
@c your program.  Documentation strings are like comments, except that they
@c are easier to access.
$BFI<T$N%W%m%0%i%`$N4X?t$9$Y$F$K!"(B
$B$?$H$(FbItE*$K;HMQ$5$l$k$b$N$G$"$C$F$b@bL@J8;zNs$rM?$($k$3$H$O$h$$$3$H$G$9!#(B
$B@bL@J8;zNs$O%3%a%s%H$K;w$F$$$^$9$,!";2>H$9$k$N$O$b$C$H4JC1$G$9!#(B

@c   The first line of the documentation string should stand on its own,
@c because @code{apropos} displays just this first line.  It should consist
@c of one or two complete sentences that summarize the function's purpose.
$B@bL@J8;zNs$N@hF,9T$O!"$=$N(B1$B9T$G407k$7$F$$$k$Y$-$G$9!#(B
$B$H$$$&$N$O!"(B@code{apropos}$B$O@hF,9T$@$1$rI=<($9$k$+$i$G$9!#(B
$B4X?t$N5!G=$r$^$H$a$?(B1$B$D$+(B2$B$D$NJ8$K$7$^$7$g$&!#(B

@c   The start of the documentation string is usually indented in the source file,
@c but since these spaces come before the starting double-quote, they are not part of
@c the string.  Some people make a practice of indenting any additional
@c lines of the string so that the text lines up in the program source.
@c @emph{This is a mistake.}  The indentation of the following lines is
@c inside the string; what looks nice in the source code will look ugly
@c when displayed by the help commands.
$B@bL@J8;zNs$N@hF,$O!"%=!<%9%U%!%$%k>e$G$OIaDL;z2<$2$7$F$"$k$G$7$g$&$,!"(B
$B$=$l$i$N6uGr$OJ8;zNs$r;O$a$k%@%V%k%/%)!<%H$N$^$($K$"$j$^$9$+$i!"(B
$B$=$l$i$OJ8;zNs$N0lIt$G$O$"$j$^$;$s!#(B
$B@bL@J8;zNs$N;D$j$N9T$r;z2<$2$7$F!"(B
$B%W%m%0%i%`%=!<%9>e$G%F%-%9%H9T$,B7$&$h$&$K$9$k?M$b$$$^$9!#(B
$B$7$+$7!"(B@emph{$B$=$l$O$^$A$,$$$G$9(B}$B!#(B
$B8eB3$N9T$N;z2<$2$OJ8;zNs$NFbB&$K$"$j$^$9!#(B
$B%=!<%9%U%!%$%k$Ge:No$K8+$($F$b!"(B
$B%X%k%W%3%^%s%I$NI=<($G$OIT3f9%$K$J$j$^$9!#(B

@c   You may wonder how the documentation string could be optional, since
@c there are required components of the function that follow it (the body).
@c Since evaluation of a string returns that string, without any side effects,
@c it has no effect if it is not the last form in the body.  Thus, in
@c practice, there is no confusion between the first form of the body and the
@c documentation string; if the only body form is a string then it serves both
@c as the return value and as the documentation.
$B4X?t$NI,?\$N9=@.MWAG!JK\BN!K$,$"$H$KB3$/$N$K!"(B
$B@bL@J8;zNs$r>JN,$G$-$k$N$rIT;W5D$K;W$&$+$b$7$l$^$;$s!#(B
$BJ8;zNs$rI>2A$9$k$H!"I{:nMQ$J$7$K!"$=$NJ8;zNs$rJV$9$N$G!"(B
$B$=$l$,K\BN$N:G8e$N%U%)!<%`$G$J$1$l$P!"$J$s$N8z2L$b$"$j$^$;$s!#(B
$B$7$?$,$C$F!"<BMQ>e!"K\BN$N:G=i$N%U%)!<%`$H(B
$B@bL@J8;zNs$r:.F1$9$k$3$H$O$"$j$^$;$s!#(B
$BK\BN$N%U%)!<%`$,J8;zNs$@$1$G$"$k$H!"(B
$B$=$l$OLa$jCM$G$b$"$j@bL@J8;zNs$G$b$"$j$^$9!#(B

@node Function Names
@c @section Naming a Function
@section $B4X?t$rL?L>$9$k(B
@c @cindex function definition
@c @cindex named function
@c @cindex function name
@cindex $B4X?tDj5A(B
@cindex $BL>A0IU$-4X?t(B
@cindex $B4X?tL>(B

@c   In most computer languages, every function has a name; the idea of a
@c function without a name is nonsensical.  In Lisp, a function in the
@c strictest sense has no name.  It is simply a list whose first element is
@c @code{lambda}, a byte-code function object, or a primitive subr-object.
$B$[$H$s$I$N7W;;5!8@8l$G$O!"3F4X?t$K$OL>A0$,$"$j$^$9!#(B
$BL>A0$N$J$$4X?t$H$$$&9M$($OK\<AE*$G$O$"$j$^$;$s!#(B
Lisp$B$G$O!"$b$C$H$b87L)$K$$$($P!"4X?t$K$OL>A0$O$"$j$^$;$s!#(B
$B4X?t$O!"@hF,MWAG$,C1$K(B@code{lambda}$B$G$"$k%j%9%H!"(B
$B%P%$%H%3!<%I4X?t%*%V%8%'%/%H!"$"$k$$$O!"4pK\4X?t$N(Bsubr$B%*%V%8%'%/%H$G$9!#(B

@c   However, a symbol can serve as the name of a function.  This happens
@c when you put the function in the symbol's @dfn{function cell}
@c (@pxref{Symbol Components}).  Then the symbol itself becomes a valid,
@c callable function, equivalent to the list or subr-object that its
@c function cell refers to.  The contents of the function cell are also
@c called the symbol's @dfn{function definition}.  The procedure of using a
@c symbol's function definition in place of the symbol is called
@c @dfn{symbol function indirection}; see @ref{Function Indirection}.
$B$7$+$7$J$,$i!"%7%s%\%k$O4X?t$NL>A0$H$7$FF/$-$^$9!#(B
$B%7%s%\%k$N(B@dfn{$B4X?t%;%k(B}$B!J(Bfunction cell$B!"(B@pxref{Symbol Components}$B!K$K(B
$B4X?t$rF~$l$k$H!"$3$N$h$&$K$J$j$^$9!#(B
$B$=$&$9$k$H!"%7%s%\%k$=$N$b$N$O@5Ev$J8F$S=P$72DG=$J4X?t$H$J$j!"(B
$B4X?t%;%k$,;2>H$9$k%j%9%H$d(Bsubr$B%*%V%8%'%/%H$HEy2A$K$J$j$^$9!#(B
$B4X?t%;%k$NFbMF$r%7%s%\%k$N(B@dfn{$B4X?tDj5A(B}$B!J(Bfunction definition$B!K$H$b8F$S$^$9!#(B
$B%7%s%\%k$N$+$o$j$K%7%s%\%k$N4X?tDj5A$r;H$&=hM}$r(B
@dfn{$B%7%s%\%k$N4X?t4V@\(B}$B!J(Bsymbol function indirection$B!K$H8F$S$^$9!#(B
@xref{Function Indirection}$B!#(B

@c   In practice, nearly all functions are given names in this way and
@c referred to through their names.  For example, the symbol @code{car} works
@c as a function and does what it does because the primitive subr-object
@c @code{#<subr car>} is stored in its function cell.
$B<BMQ>e!"$[$H$s$I$9$Y$F$N4X?t$K$O!"$3$N$h$&$K$7$FL>A0$,IU$$$F$$$F!"(B
$B$=$NL>A0$G;2>H$7$^$9!#(B
$B$?$H$($P!"%7%s%\%k(B@code{car}$B$O!"(B
$B$=$N4X?t%;%k$K4pK\4X?t$N(Bsubr$B%*%V%8%'%/%H(B@code{#<subr car>}$B$,3JG<$7$F$"$k$N$G!"(B
$B$=$NF0:n$r9T$&4X?t$H$7$FF0:n$7$^$9!#(B

@c   We give functions names because it is convenient to refer to them by
@c their names in Lisp expressions.  For primitive subr-objects such as
@c @code{#<subr car>}, names are the only way you can refer to them: there
@c is no read syntax for such objects.  For functions written in Lisp, the
@c name is more convenient to use in a call than an explicit lambda
@c expression.  Also, a function with a name can refer to itself---it can
@c be recursive.  Writing the function's name in its own definition is much
@c more convenient than making the function definition point to itself
@c (something that is not impossible but that has various disadvantages in
@c practice).
$B4X?t$KL>A0$rM?$($k$N$O!"(BLisp$B<0$+$i$=$NL>A0$G;2>H$G$-$k$HJXMx$@$+$i$G$9!#(B
@code{#<subr car>}$B$N$h$&$J4pK\4X?t$N(Bsubr$B%*%V%8%'%/%H$G$O!"(B
$BL>A0$O$=$l$i$r;2>H$9$kM#0l$NJ}K!$G$9!#(B
$B$=$N$h$&$J%*%V%8%'%/%H$K$OF~NO9=J8$O$"$j$^$;$s!#(B
Lisp$B$G=q$$$?4X?t$G$O!"L@<(E*$J%i%`%@<0$h$jL>A0$r;H$&$[$&$,$h$jJXMx$G$9!#(B
$B$^$?!"4X?t$KL>A0$,$"$l$P$=$l$r;2>H$G$-$^$9!#(B
$B$D$^$j!":F5"8F$S=P$7$,$G$-$^$9!#(B
$B4X?t$NL>A0$r$=$NDj5A$=$N$b$N$K=q$/$3$H$O!"(B
$B4X?tDj5A$,$=$l<+?H$r;X$9$h$&$K$9$k(B
$B!J$3$l$OIT2DG=$G$O$J$$$K$7$F$b!"<BMQ>e$O$5$^$6$^$J7gE@$,$"$k!K$h$j$O!"(B
$B$H$F$bJXMx$G$9!#(B

@c   We often identify functions with the symbols used to name them.  For
@c example, we often speak of ``the function @code{car}'', not
@c distinguishing between the symbol @code{car} and the primitive
@c subr-object that is its function definition.  For most purposes, there
@c is no need to distinguish.
$B4X?t$r;XL>$9$k%7%s%\%k$G4X?t$r$7$P$7$P<1JL$7$^$9!#(B
$B$?$H$($P!"$7$P$7$P!X4X?t(B@code{car}$B!Y$H$$$C$F!"(B
$B%7%s%\%k(B@code{car}$B$H4X?tDj5A$G$"$k4pK\4X?t$N(Bsubr$B%*%V%8%'%/%H$H$r6hJL$7$^$;$s!#(B
$B$[$H$s$I$NL\E*$K$O!"6hJL$9$kI,MW$O$"$j$^$;$s!#(B

@c   Even so, keep in mind that a function need not have a unique name.  While
@c a given function object @emph{usually} appears in the function cell of only
@c one symbol, this is just a matter of convenience.  It is easy to store
@c it in several symbols using @code{fset}; then each of the symbols is
@c equally well a name for the same function.
$B$?$H$($=$&$G$"$C$F$b!"4X?t$K0l0U$JL>A0$OI,MW$J$$$3$H$r(B
$B?4$KN1$a$F$*$$$F$/$@$5$$!#(B
$B4X?t%*%V%8%'%/%H$O(B@emph{$BIaDL(B}1$B$D$N%7%s%\%k$N4X?t%;%k$@$1$K8=$l$^$9$,!"(B
$B$3$l$OC1$J$kJXK!$G$9!#(B
@code{fset}$B$r;H$C$F!"J#?t$N%7%s%\%k$K3JG<$9$k$N$O4JC1$G$9!#(B
$B$=$&$9$k$H!"3F%7%s%\%k$OF1$84X?t$rF1Ey$K;XL>$7$^$9!#(B

@c   A symbol used as a function name may also be used as a variable; these
@c two uses of a symbol are independent and do not conflict.  (Some Lisp
@c dialects, such as Scheme, do not distinguish between a symbol's value
@c and its function definition; a symbol's value as a variable is also its
@c function definition.)  If you have not given a symbol a function
@c definition, you cannot use it as a function; whether the symbol has a
@c value as a variable makes no difference to this.
$B4X?tL>$H$7$F;H$&%7%s%\%k$O!"JQ?t$H$7$F$b;H$($^$9!#(B
$B%7%s%\%k$N$3$l$i(B2$B$D$N;H$$J}$OFHN)$7$F$$$F>WFM$7$^$;$s!#(B
$B!J(BScheme$B$J$I$N(BLisp$B$NJ}8@$N$J$+$K$O!"(B
$B%7%s%\%k$NCM$H$=$N4X?tDj5A$r6hJL$7$J$$$b$N$b$"$k!#(B
$BJQ?t$H$7$F$N%7%s%\%k$NCM$O!"$=$N4X?tDj5A$G$b$"$k!#!K(B
$B%7%s%\%k$K4X?tDj5A$rM?$($F$$$J$$$H!"$=$N%7%s%\%k$r4X?t$H$7$F$O;H$($^$;$s!#(B
$B$3$l$O!"%7%s%\%k$KJQ?t$H$7$F$NCM$,$"$k$+$I$&$+$K$O4X78$7$^$;$s!#(B

@node Defining Functions
@c @section Defining Functions
@section $B4X?t$rDj5A$9$k(B
@c @cindex defining a function
@cindex $B4X?t$rDj5A$9$k(B

@c   We usually give a name to a function when it is first created.  This
@c is called @dfn{defining a function}, and it is done with the
@c @code{defun} special form.
$B4X?t$r:n@.$9$k$H$-$K$O!"IaDL!"4X?t$KL>A0$rM?$($^$9!#(B
$B$3$l$r(B@dfn{$B4X?t$rDj5A$9$k(B}$B$H8F$S!"(B
$B%9%Z%7%c%k%U%)!<%`(B@code{defun}$B$G9T$$$^$9!#(B

@defspec defun name argument-list body-forms
@c @code{defun} is the usual way to define new Lisp functions.  It
@c defines the symbol @var{name} as a function that looks like this:
@code{defun}$B$O!"?7$?$K(BLisp$B4X?t$rDj5A$9$kIaDL$NJ}K!$G$"$k!#(B
$B$3$l$O!"%7%s%\%k(B@var{name}$B$r$D$.$N$h$&$J4X?t$H$7$FDj5A$9$k!#(B

@example
(lambda @var{argument-list} . @var{body-forms})
@end example

@c @code{defun} stores this lambda expression in the function cell of
@c @var{name}.  It returns the value @var{name}, but usually we ignore this
@c value.
@code{defun}$B$O!"$3$N%i%`%@<0$r(B@var{name}$B$N4X?t%;%k$K3JG<$9$k!#(B
$BCM(B@var{name}$B$rJV$9$,!"IaDL!"$3$l$OL5;k$9$k!#(B

@c As described previously (@pxref{Lambda Expressions}),
@c @var{argument-list} is a list of argument names and may include the
@c keywords @code{&optional} and @code{&rest}.  Also, the first two of the
@c @var{body-forms} may be a documentation string and an interactive
@c declaration.
$BA0=R!J(B@pxref{Lambda Expressions}$B!K$N$h$&$K!"(B
@var{argument-list}$B$O0z?tL>$N%j%9%H$G$"$j!"(B
$B%-!<%o!<%I(B@code{&optional}$B$d(B@code{&rest}$B$,F~$C$F$$$F$b$h$$!#(B
$B$^$?!"(B@var{body-forms}$B$N:G=i$N(B2$B$D$O!"@bL@J8;zNs$HBPOC@k8@$G$b$h$$!#(B

@c There is no conflict if the same symbol @var{name} is also used as a
@c variable, since the symbol's value cell is independent of the function
@c cell.  @xref{Symbol Components}.
$BF10l$N%7%s%\%k(B@var{name}$B$rJQ?t$H$7$F;H$C$F$$$F$b>WFM$O$J$$!#(B
$B$H$$$&$N$O!"%7%s%\%k$NCM%;%k$O4X?t%;%k$H$OFHN)$@$+$i$G$"$k!#(B
@pxref{Symbol Components}$B!#(B

@c Here are some examples:
$BNc$r<($=$&!#(B

@example
@group
(defun foo () 5)
     @result{} foo
@end group
@group
(foo)
     @result{} 5
@end group

@group
(defun bar (a &optional b &rest c)
    (list a b c))
     @result{} bar
@end group
@group
(bar 1 2 3 4 5)
     @result{} (1 2 (3 4 5))
@end group
@group
(bar 1)
     @result{} (1 nil nil)
@end group
@group
(bar)
@error{} Wrong number of arguments.
@end group

@group
(defun capitalize-backwards ()
  "Upcase the last letter of a word."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))
     @result{} capitalize-backwards
@end group
@end example

@c Be careful not to redefine existing functions unintentionally.
@c @code{defun} redefines even primitive functions such as @code{car}
@c without any hesitation or notification.  Redefining a function already
@c defined is often done deliberately, and there is no way to distinguish
@c deliberate redefinition from unintentional redefinition.
$B4{B8$N4X?t$r0U?^$;$:$K:FDj5A$7$J$$$h$&$KCm0U$9$k$3$H!#(B
@code{defun}$B$O!"$?$H$((B@code{car}$B$J$I$N4pK\4X?t$G$"$C$F$b!"(B
$B$J$s$Nm4m0$bCm0U$b$;$:$K:FDj5A$7$F$7$^$&!#(B
$B4{B84X?t$N:FDj5A$OCm0U?<$/9T$&$,!"(B
$BITK\0U$J:FDj5A$H=O9M$7$?:FDj5A$r6hJL$9$kJ}K!$O$J$$!#(B
@end defspec

@defun defalias name definition
@c This special form defines the symbol @var{name} as a function, with
@c definition @var{definition} (which can be any valid Lisp function).
$B$3$N%9%Z%7%c%k%U%)!<%`$O!"(B
$B%7%s%\%k(B@var{name}$B$rDj5A(B@var{definition}$B!JG$0U$N@5$7$$(BLisp$B4X?t!K$H$9$k(B
$B4X?t$H$7$FDj5A$9$k!#(B

@c The proper place to use @code{defalias} is where a specific function
@c name is being defined---especially where that name appears explicitly in
@c the source file being loaded.  This is because @code{defalias} records
@c which file defined the function, just like @code{defun}
@c (@pxref{Unloading}).
@code{defalias}$B$r;H$&@5$7$$>l=j$O!"(B
$BFCDj$N4X?tL>$,Dj5A$5$l$F$$$k>l=j$G$"$k!#(B
$BFC$K!"%m!<%ICf$N%=!<%9%U%!%$%k$GL@<(E*$KL>A0$,8=$l$F$$$k>l=j$G$"$k!#(B
$B$H$$$&$N$O!"(B@code{defalias}$B$O!"(B@code{defun}$B$HF1MM$K!"(B
$B4X?t$,Dj5A$5$l$?%U%!%$%k$r5-O?$9$k$+$i$G$"$k!J(B@pxref{Unloading}$B!K!#(B

@c By contrast, in programs that manipulate function definitions for other
@c purposes, it is better to use @code{fset}, which does not keep such
@c records.
$B0lJ}!"B>$NL\E*$G4X?tDj5A$rA`:n$9$k%W%m%0%i%`$G$O!"(B
$B$=$N$h$&$J5-O?$rJ];}$7$J$$(B@code{fset}$B$r;H$&$N$,$h$$!#(B
@end defun

@c   See also @code{defsubst}, which defines a function like @code{defun}
@c and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.
@code{defun}$B$N$h$&$K4X?t$rDj5A$7!"$+$D!"(B
Lisp$B%3%s%Q%$%i$K4X?tDj5A$rE83+$9$k$h$&$K;X<($9$k(B
@code{defsubst}$B$b;2>H$7$F$/$@$5$$!#(B
@xref{Inline Functions}$B!#(B

@node Calling Functions
@c @section Calling Functions
@section $B4X?t8F$S=P$7(B
@c @cindex function invocation
@c @cindex calling a function
@cindex $B4X?t$N5/F0(B
@cindex $B4X?t8F$S=P$7(B

@c   Defining functions is only half the battle.  Functions don't do
@c anything until you @dfn{call} them, i.e., tell them to run.  Calling a
@c function is also known as @dfn{invocation}.
$B4X?t$rDj5A$9$k$3$H$O!"A4BN$NH>J,$G$7$+$"$j$^$;$s!#(B
$B4X?t$r(B@dfn{$B8F$V(B}$B$^$G$O!"$D$^$j!"<B9T$rL?$8$J$1$l$P!"4X?t$O$J$K$b$7$^$;$s!#(B
$B4X?t8F$S=P$7$O(B@dfn{$B5/F0(B}$B!J(Binvocation$B!K$H$b$$$$$^$9!#(B

@c   The most common way of invoking a function is by evaluating a list.
@c For example, evaluating the list @code{(concat "a" "b")} calls the
@c function @code{concat} with arguments @code{"a"} and @code{"b"}.
@c @xref{Evaluation}, for a description of evaluation.
$B4X?t$r5/F0$9$k$b$C$H$b0lHLE*$JJ}K!$O!"%j%9%H$rI>2A$9$k$3$H$G$9!#(B
$B$?$H$($P!"%j%9%H(B@code{(concat "a" "b")}$B$rI>2A$9$k$H!"(B
$B4X?t(B@code{concat}$B$r0z?t(B@code{"a"}$B$H(B@code{"b"}$B$G8F$S=P$7$^$9!#(B
$BI>2A$K$D$$$F$O(B@xref{Evaluation}$B!#(B

@c   When you write a list as an expression in your program, the function
@c name it calls is written in your program.  This means that you choose
@c which function to call, and how many arguments to give it, when you
@c write the program.  Usually that's just what you want.  Occasionally you
@c need to compute at run time which function to call.  To do that, use the
@c function @code{funcall}.  When you also need to determine at run time
@c how many arguments to pass, use @code{apply}.
$BFI<T$N%W%m%0%i%`$G<0$H$7$F%j%9%H$r=q$/$H$-$K$O!"(B
$B8F$S=P$94X?tL>$rFI<T$N%W%m%0%i%`$K=q$-$^$9!#(B
$B$D$^$j!"%W%m%0%i%`$r=q$/$H$-$K!"(B
$B$I$N4X?t$r$I$l$@$1$N0z?t$G8F$S=P$9$+$r;XDj$G$-$k$3$H$r0UL#$7$^$9!#(B
$B$3$l$,!"IaDL$K$7$?$$$3$H$G$7$g$&!#(B
$B8F$S=P$94X?t$r<B9T;~$K7W;;$9$kI,MW$,$"$k>l9g$b$"$k$G$7$g$&!#(B
$B$=$l$K$O!"4X?t(B@code{funcall}$B$r;H$$$^$9!#(B
$BEO$90z?t$N8D?t$r<B9T;~$K7hDj$9$kI,MW$,$"$k$H$-$K$O!"(B
@code{apply}$B$r;H$$$^$9!#(B

@defun funcall function &rest arguments
@c @code{funcall} calls @var{function} with @var{arguments}, and returns
@c whatever @var{function} returns.
@code{funcall}$B$O!"(B@var{function}$B$r(B@var{arguments}$B$G8F$S=P$7!"(B
@var{function}$B$,$J$K$rJV$=$&$H$b$=$l$rJV$9!#(B

@c Since @code{funcall} is a function, all of its arguments, including
@c @var{function}, are evaluated before @code{funcall} is called.  This
@c means that you can use any expression to obtain the function to be
@c called.  It also means that @code{funcall} does not see the expressions
@c you write for the @var{arguments}, only their values.  These values are
@c @emph{not} evaluated a second time in the act of calling @var{function};
@c @code{funcall} enters the normal procedure for calling a function at the
@c place where the arguments have already been evaluated.
@code{funcall}$B$O4X?t$J$N$G!"(B@var{function}$B$N8F$S=P$7$rI>2A$9$k$^$($K(B
@var{function}$B$r4^$a$?0z?t$9$Y$F$rI>2A$9$k!#(B
$B$D$^$j!"8F$S=P$94X?t$rF@$k$?$a$N$I$s$J<0$G$b;H$($k$3$H$r0UL#$9$k!#(B
$B$^$?!"(B@code{funcall}$B$O!"FI<T$,(B@var{arguments}$B$K=q$$$?<0$r8+$k$3$H$O$J$/!"(B
$B$=$l$i$NCM$@$1$r8+$k$3$H$K$J$k!#(B
$B$3$l$i$NCM$O!"(B@var{function}$B$r8F$S=P$9A`:n$K$*$$$F!"(B
2$B2sL\$NI>2A$r9T$&$3$H$O(B@emph{$B$J$$(B}$B!#(B
@code{funcall}$B$O!"DL>o$N4X?t8F$S=P$7=hM}$K$*$$$F!"(B
$B0z?t$rI>2A$7=*$($?$H$3$m$+$i;O$a$k!#(B

@c The argument @var{function} must be either a Lisp function or a
@c primitive function.  Special forms and macros are not allowed, because
@c they make sense only when given the ``unevaluated'' argument
@c expressions.  @code{funcall} cannot provide these because, as we saw
@c above, it never knows them in the first place.
$B0z?t(B@var{function}$B$O!"(BLisp$B4X?t$+4pK\4X?t$G$"$kI,MW$,$"$k!#(B
$B%9%Z%7%c%k%U%)!<%`$d%^%/%m$O5v$5$l$J$$!#(B
$B$=$l$i$K$O!"!XL$I>2A!Y$N0z?t<0$rM?$($?$H$-$@$10UL#$,$"$k$+$i$G$"$k!#(B
@code{funcall}$B$G$O$=$N$h$&$K$G$-$J$$!#(B
$B$J$<$J$i!">e$N@bL@$G$o$+$k$h$&$K!"(B
$BL$I>2A$N0z?t$r$^$C$?$/CN$i$J$$$+$i$G$"$k!#(B

@example
@group
(setq f 'list)
     @result{} list
@end group
@group
(funcall f 'x 'y 'z)
     @result{} (x y z)
@end group
@group
(funcall f 'x 'y '(z))
     @result{} (x y (z))
@end group
@group
(funcall 'and t nil)
@error{} Invalid function: #<subr and>
@end group
@end example

@c Compare these example with the examples of @code{apply}.
$B$3$l$i$NNc$r(B@code{apply}$B$NNc$HHf3S$7$F$[$7$$!#(B
@end defun

@defun apply function &rest arguments
@c @code{apply} calls @var{function} with @var{arguments}, just like
@c @code{funcall} but with one difference: the last of @var{arguments} is a
@c list of objects, which are passed to @var{function} as separate
@c arguments, rather than a single list.  We say that @code{apply}
@c @dfn{spreads} this list so that each individual element becomes an
@c argument.
@code{apply}$B$O!"(B@code{funcall}$B$N$h$&$K!"(B
@var{function}$B$r(B@var{arguments}$B$G8F$S=P$9$,!"(B1$BE@$@$10[$J$k!#(B
@var{arguments}$B$N:G8e$O%*%V%8%'%/%H$N%j%9%H$G$"$j!"(B
@var{function}$B$K$O$3$l$r!"C10l$N%j%9%H$G$O$J$/!"8D!9$N0z?t$H$7$FEO$9!#(B
$B$3$l$r!"(B@code{apply}$B$O!"(B
$B$3$N%j%9%H$N8D!9$NMWAG$,0z?t$H$J$k$h$&$K(B@dfn{$BJ,G[$9$k(B}$B$H$$$&!#(B

@c @code{apply} returns the result of calling @var{function}.  As with
@c @code{funcall}, @var{function} must either be a Lisp function or a
@c primitive function; special forms and macros do not make sense in
@c @code{apply}.
@code{apply}$B$O!"(B@var{function}$B$N8F$S=P$77k2L$rJV$9!#(B
@code{funcall}$B$HF1MM$K!"(B@var{function}$B$O(BLisp$B4X?t$+4pK\4X?t$G$"$kI,MW$,$"$k!#(B
$B%9%Z%7%c%k%U%)!<%`$d%^%/%m$O!"(B@code{apply}$B$G$O0UL#$,$J$$!#(B

@example
@group
(setq f 'list)
     @result{} list
@end group
@group
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
@end group
@group
(apply '+ 1 2 '(3 4))
     @result{} 10
@end group
@group
(apply '+ '(1 2 3 4))
     @result{} 10
@end group

@group
(apply 'append '((a b c) nil (x y z) nil))
     @result{} (a b c x y z)
@end group
@end example

@c For an interesting example of using @code{apply}, see the description of
@c @code{mapcar}, in @ref{Mapping Functions}.
@code{apply}$B$r;H$C$?6=L#?<$$Nc$H$7$F!"(B
@ref{Mapping Functions}$B$N(B@code{mapcar}$B$N@bL@$r8+$F$[$7$$!#(B
@end defun

@c @cindex functionals
@cindex $B%U%!%s%/%7%g%J%k(B
@c   It is common for Lisp functions to accept functions as arguments or
@c find them in data structures (especially in hook variables and property
@c lists) and call them using @code{funcall} or @code{apply}.  Functions
@c that accept function arguments are often called @dfn{functionals}.
Lisp$B4X?t$K$H$C$F$O!"0z?t$H$7$F4X?t$r<u$1<h$C$?$j!"(B
$B%G!<%?9=B$!JFC$K!"%U%C%/JQ?t$dB0@-%j%9%H!KFb$N4X?t$rC5$7$F(B
@code{funcall}$B$d(B@code{apply}$B$r;H$C$F$=$l$r8F$S=P$9$3$H$O0lHLE*$G$9!#(B
$B4X?t0z?t$r<u$1IU$1$k4X?t$r(B
$B$7$P$7$P(B@dfn{$B%U%!%s%/%7%g%J%k(B}$B!J(Bfunctionals$B!K$H8F$S$^$9!#(B

@c   Sometimes, when you call a functional, it is useful to supply a no-op
@c function as the argument.  Here are two different kinds of no-op
@c function:
$B>l9g$K$h$C$F$O!"%U%!%s%/%7%g%J%k$r8F$S=P$9$H$-$K$O!"(B
$B0z?t$H$7$F$J$K$b$7$J$$4X?t!J(Bno-op$B!K$r;XDj$G$-$k$HM-MQ$G$9!#(B
$B$D$.$N$b$N$O!"(B2$B<oN`$N$J$K$b$7$J$$4X?t$G$9!#(B

@defun identity arg
@c This function returns @var{arg} and has no side effects.
$B$3$N4X?t$O(B@var{arg}$B$rJV$7!"I{:nMQ$r;}$?$J$$!#(B
@end defun

@defun ignore &rest args
@c This function ignores any arguments and returns @code{nil}.
$B$3$N4X?t$O0z?t$rL5;k$7!"(B@code{nil}$B$rJV$9!#(B
@end defun

@node Mapping Functions
@c @section Mapping Functions
@section $B%^%C%W4X?t(B
@c @cindex mapping functions
@cindex $B%^%C%W4X?t(B

@c   A @dfn{mapping function} applies a given function to each element of a
@c list or other collection.  Emacs Lisp has several such functions;
@c @code{mapcar} and @code{mapconcat}, which scan a list, are described
@c here.  @xref{Creating Symbols}, for the function @code{mapatoms} which
@c maps over the symbols in an obarray.
@dfn{$B%^%C%W4X?t(B}$B!J(Bmapping function$B!K$O!"(B
$B%j%9%H$dB>$N=8$^$j$N3FMWAG$K;XDj$7$?4X?t$rE,MQ$7$^$9!#(B
Emacs Lisp$B$K$O$=$N$h$&$J4X?t$,$$$/$D$+$"$j$^$9!#(B
@code{mapcar}$B$H(B@code{mapconcat}$B$O%j%9%H$rAv::$9$k$b$N$G!"$3$3$G@bL@$7$^$9!#(B
$B%*%V%8%'%/%HG[Ns(Bobarray$BFb$N%7%s%\%k$K$D$$$F(B
$B%^%C%W$9$k4X?t(B@code{mapatoms}$B$K$D$$$F$O!"(B
@xref{Creating Symbols}$B!#(B

@c   These mapping functions do not allow char-tables because a char-table
@c is a sparse array whose nominal range of indices is very large.  To map
@c over a char-table in a way that deals properly with its sparse nature,
@c use the function @code{map-char-table} (@pxref{Char-Tables}).
$B$3$l$i$N%^%C%W4X?t$G$O!"J8;z%F!<%V%k$O07$($^$;$s!#(B
$B$H$$$&$N$O!"J8;z%F!<%V%k$OAB$JG[Ns$G$"$j!"$=$NE:;zHO0O$bHs>o$KBg$-$$$+$i$G$9!#(B
$BJ8;z%F!<%V%k$NAB$J@-<A$r9MN8$7$FJ8;z%F!<%V%k$K$D$$$F%^%C%W$9$k$K$O!"(B
$B4X?t(B@code{map-char-table}$B!J(B@pxref{Char-Tables}$B!K$r;H$$$^$9!#(B

@defun mapcar function sequence
@c @code{mapcar} applies @var{function} to each element of @var{sequence}
@c in turn, and returns a list of the results.
@code{mapcar}$B$O!"(B@var{sequence}$B$N3FMWAG$K=g$K(B@var{function}$B$rE,MQ$7!"(B
$B7k2L$N%j%9%H$rJV$9!#(B

@c The argument @var{sequence} can be any kind of sequence except a
@c char-table; that is, a list, a vector, a bool-vector, or a string.  The
@c result is always a list.  The length of the result is the same as the
@c length of @var{sequence}.
$B0z?t(B@var{sequence}$B$OJ8;z%F!<%V%k0J30$NG$0U$N<oN`$N%7!<%1%s%9$G$h$$!#(B
$B$D$^$j!"%j%9%H!"%Y%/%H%k!"%V!<%k%Y%/%H%k!"$"$k$$$O!"J8;zNs$G$"$k!#(B
$B7k2L$O$D$M$K%j%9%H$G$"$k!#(B
$B7k2L$ND9$5$O(B@var{sequence}$B$ND9$5$HF1$8$G$"$k!#(B

@smallexample
@group
@c @exdent @r{For example:}
@exdent @r{$B$?$H$($P!"$D$.$N$H$*$j!#(B}

(mapcar 'car '((a b) (c d) (e f)))
     @result{} (a c e)
(mapcar '1+ [1 2 3])
     @result{} (2 3 4)
(mapcar 'char-to-string "abc")
     @result{} ("a" "b" "c")
@end group

@group
@c ;; @r{Call each function in @code{my-hooks}.}
;; @r{@code{my-hooks}$B$N3F4X?t$r8F$S=P$9(B}
(mapcar 'funcall my-hooks)
@end group

@group
(defun mapcar* (function &rest args)
  "Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
@c   ;; @r{If no list is exhausted,}
  ;; @r{$B%j%9%H$r$D$/$7$F$$$J$1$l$P(B}
  (if (not (memq 'nil args))              
@c       ;; @r{apply function to @sc{car}s.}
      ;; @r{@sc{car}$B$K4X?t$rE,MQ$9$k(B}
      (cons (apply function (mapcar 'car args))  
            (apply 'mapcar* function             
                   ;; @r{Recurse for rest of elements.}
                   (mapcar 'cdr args)))))
@end group

@group
(mapcar* 'cons '(a b c) '(1 2 3 4))
     @result{} ((a . 1) (b . 2) (c . 3))
@end group
@end smallexample
@end defun

@defun mapconcat function sequence separator
@c @code{mapconcat} applies @var{function} to each element of
@c @var{sequence}: the results, which must be strings, are concatenated.
@c Between each pair of result strings, @code{mapconcat} inserts the string
@c @var{separator}.  Usually @var{separator} contains a space or comma or
@c other suitable punctuation.
@code{mapconcat}$B$O!"(B@var{sequence}$B$N3FMWAG$K(B@var{function}$B$rE,MQ$9$k!#(B
$B$=$l$i$N7k2L$O!"J8;zNs$G$"$kI,MW$,$"$j!"O"7k$5$l$k!#(B
@code{mapconcat}$B$O!"7k2L$NJ8;zNs$N$"$$$@$KJ8;zNs(B@var{separator}$B$rA^F~$9$k!#(B
$BIaDL!"(B@var{separator}$B$O!"6uGr$d%3%s%^!"$=$NB>$N6gFIE@$r4^$`!#(B

@c The argument @var{function} must be a function that can take one
@c argument and return a string.  The argument @var{sequence} can be any
@c kind of sequence except a char-table; that is, a list, a vector, a
@c bool-vector, or a string.
$B0z?t(B@var{function}$B$O!"0z?t$r(B1$B$D<h$k4X?t$G$"$j!"(B
$BJ8;zNs$rJV$9I,MW$,$"$k!#(B
$B0z?t(B@var{sequence}$B$O!"J8;z%F!<%V%k0J30$NG$0U$N<oN`$N%7!<%1%s%9$G$h$$!#(B
$B$D$^$j!"%j%9%H!"%Y%/%H%k!"%V!<%k%Y%/%H%k!"$"$k$$$O!"J8;zNs$G$"$k!#(B
  
@smallexample
@group
(mapconcat 'symbol-name
           '(The cat in the hat)
           " ")
     @result{} "The cat in the hat"
@end group

@group
(mapconcat (function (lambda (x) (format "%c" (1+ x))))
           "HAL-8000"
           "")
     @result{} "IBM.9111"
@end group
@end smallexample
@end defun

@node Anonymous Functions
@c @section Anonymous Functions
@section $BL5L>4X?t(B
@c @cindex anonymous function
@cindex $BL5L>4X?t(B

@c   In Lisp, a function is a list that starts with @code{lambda}, a
@c byte-code function compiled from such a list, or alternatively a
@c primitive subr-object; names are ``extra''.  Although usually functions
@c are defined with @code{defun} and given names at the same time, it is
@c occasionally more concise to use an explicit lambda expression---an
@c anonymous function.  Such a list is valid wherever a function name is.
Lisp$B$G$O!"4X?t$H$O!"(B@code{lambda}$B$G;O$^$k%j%9%H!"(B
$B$=$N$h$&$J%j%9%H$r%3%s%Q%$%k$7$?%P%$%H%3!<%I4X?t!"(B
$B$"$k$$$O!"4pK\4X?t$N(Bsubr$B%*%V%8%'%/%H$G$9!#(B
$BL>A0$O!XM>J,!Y$J$N$G$9!#(B
$BIaDL$N4X?t$O(B@code{defun}$B$GDj5A$7!"$=$N$H$-L>A0$rM?$($^$9$,!"(B
$BL@<(E*$J%i%`%@<0!"$D$^$j!"L5L>4X?t$r;H$C$?$[$&$,$h$j4JAG$J>l9g$b$"$j$^$9!#(B
$B$=$N$h$&$J%j%9%H$O!"4X?tL>$r;H$($k>lLL$J$i$P!"$I$3$G$b;H$($^$9!#(B

@c   Any method of creating such a list makes a valid function.  Even this:
$B$=$N$h$&$J%j%9%H$r$I$s$JJ}K!$G:n$C$F$b!"@5$7$$4X?t$H$J$j$^$9!#(B
$B$D$.$N$h$&$K$7$F$b$+$^$o$J$$$N$G$9!#(B

@smallexample
@group
(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
@result{} (lambda (x) (+ 12 x))
@end group
@end smallexample

@noindent
@c This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
@c makes it the value (@emph{not} the function definition!) of
@c @code{silly}.
$B$3$l$O!"(B@code{(lambda (x) (+ 12 x))}$B$N$h$&$J%j%9%H$r7W;;$7!"(B
$B$=$NCM$r(B@code{silly}$B$NCM!J4X?tDj5A$G$O(B@emph{$B$J$$(B}$B!*!K$H$7$^$9!#(B

@c   Here is how we might call this function:
$B$3$N4X?t$O$D$.$N$h$&$K8F$S=P$;$^$9!#(B

@example
@group
(funcall silly 1)
@result{} 13
@end group
@end example

@noindent
@c (It does @emph{not} work to write @code{(silly 1)}, because this function
@c is not the @emph{function definition} of @code{silly}.  We have not given
@c @code{silly} any function definition, just a value as a variable.)
$B!J(B@code{(silly 1)}$B$H=q$$$F$bF0:n(B@emph{$B$7$J$$(B}$B!#(B
$B$J$<$J$i!"$3$N4X?t$O!"(B@code{silly}$B$N(B@emph{$B4X?tDj5A(B}$B$G$O$J$$$+$i$G$"$k!#(B
@code{silly}$B$K$O4X?tDj5A$rM?$($F$J$/!"(B
$BJQ?t$H$7$F$NCM$rM?$($?$@$1$G$"$k!#!K(B

@c   Most of the time, anonymous functions are constants that appear in
@c your program.  For example, you might want to pass one as an argument to
@c the function @code{mapcar}, which applies any given function to each
@c element of a list.
$B$[$H$s$I$N>l9g!"L5L>4X?t$OFI<T$N%W%m%0%i%`$K8=$l$kDj?t$G$9!#(B
$B$?$H$($P!"4X?t(B@code{mapcar}$B$N0z?t$N(B1$B$D$KEO$7$?$$$H$-$J$I$G$9!#(B
@code{mapcar}$B$O!"%j%9%H$N3FMWAG$K;XDj$7$?4X?t$rE,MQ$7$^$9!#(B

@c   Here we define a function @code{change-property} which 
@c uses a function as its third argument:
$BBh(B3$B0z?t$K4X?t$r<h$k4X?t(B@code{change-property}$B$rDj5A$7$^$9!#(B

@example
@group
(defun change-property (symbol prop function)
  (let ((value (get symbol prop)))
    (put symbol prop (funcall function value))))
@end group
@end example

@noindent
@c Here we define a function that uses @code{change-property},
@c passing it a function to double a number:
$B$3$3$G!"?t$r(B2$BG\$9$k4X?t$rEO$7$F(B@code{change-property}$B$r;H$&(B
$B4X?t$rDj5A$7$^$9!#(B

@example
@group
(defun double-property (symbol prop)
  (change-property symbol prop '(lambda (x) (* 2 x))))
@end group
@end example

@noindent
@c In such cases, we usually use the special form @code{function} instead
@c of simple quotation to quote the anonymous function, like this:
$B$3$N$h$&$J>l9g!"$D$.$N$h$&$K!"L5L>4X?t$r%/%)!<%H$9$k$K$O!"(B
$BC1=c$J%/%)!<%H$N$+$o$j$K%9%Z%7%c%k%U%)!<%`(B@code{function}$B$r;H$$$^$9!#(B

@example
@group
(defun double-property (symbol prop)
  (change-property symbol prop
                   (function (lambda (x) (* 2 x)))))
@end group
@end example

@c Using @code{function} instead of @code{quote} makes a difference if you
@c compile the function @code{double-property}.  For example, if you
@c compile the second definition of @code{double-property}, the anonymous
@c function is compiled as well.  By contrast, if you compile the first
@c definition which uses ordinary @code{quote}, the argument passed to
@c @code{change-property} is the precise list shown:
@code{quote}$B$N$+$o$j$K(B@code{function}$B$r;H$C$?>l9g$K0c$$$,$G$k$N$O!"(B
$B4X?t(B@code{double-property}$B$r%3%s%Q%$%k$7$?$H$-$G$9!#(B
$B$?$H$($P!"(B@code{double-property}$B$N(B2$BHVL\$NDj5A$r%3%s%Q%$%k$9$k$H!"(B
$BL5L>4X?t$b%3%s%Q%$%k$5$l$^$9!#(B
$B0lJ}!"IaDL$N(B@code{quote}$B$r;H$C$?:G=i$NDj5A$r%3%s%Q%$%k$9$k$H!"(B
@code{change-property}$B$XEO$90z?t$O!"=q$$$?$H$*$j$N%j%9%H$G$9!#(B

@example
(lambda (x) (* x 2))
@end example

@noindent
@c The Lisp compiler cannot assume this list is a function, even though it
@c looks like one, since it does not know what @code{change-property} will
@c do with the list.  Perhaps it will check whether the @sc{car} of the third
@c element is the symbol @code{*}!  Using @code{function} tells the
@c compiler it is safe to go ahead and compile the constant function.
Lisp$B%3%s%Q%$%i$O!"$3$N%j%9%H$,4X?t$K8+$($?$H$7$F$b!"(B
$B$3$N%j%9%H$r4X?t$H$O$_$J$7$^$;$s!#(B
$B$H$$$&$N$O!"%3%s%Q%$%i$K$O(B@code{change-property}$B$,%j%9%H$K$J$K$r9T$&$+(B
$B$o$+$i$J$$$+$i$G$9!#(B
$B$?$V$s!"Bh(B3$BMWAG$N(B@sc{car}$B$,%7%s%\%k(B@code{*}$B$+(B
$B$I$&$+D4$Y$l$P$h$$$N$G$7$g$&!*(B@code{ }
@code{function}$B$r;H$&$H!"%3%s%Q%$%i$KBP$7$F@h$X?J$s$G(B
$BDj?t$N4X?t$r%3%s%Q%$%k$7$F$b0BA4$G$"$k$3$H$rEA$($^$9!#(B

@c   We sometimes write @code{function} instead of @code{quote} when
@c quoting the name of a function, but this usage is just a sort of
@c comment:
$B4X?tL>$r%/%)!<%H$9$k$H$-$K(B@code{quote}$B$N$+$o$j$K(B@code{function}$B$r(B
$B=q$/$3$H$b$"$j$^$9$,!"$3$NMQK!$O%3%a%s%H$N$h$&$J$b$N$G$9!#(B

@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example

@c   The read syntax @code{#'} is a short-hand for using @code{function}.
@c For example, 
$BF~NO9=J8(B@code{#'}$B$O!"(B@code{function}$B$N>JN,7A$G$9!#(B
$B$?$H$($P!"(B

@example
#'(lambda (x) (* x x))
@end example

@noindent
@c is equivalent to
$B$O!"$D$.$HEy2A$G$9!#(B

@example
(function (lambda (x) (* x x)))
@end example

@defspec function function-object
@c @cindex function quoting
@cindex $B4X?t$r%/%)!<%H$9$k(B
@c This special form returns @var{function-object} without evaluating it.
@c In this, it is equivalent to @code{quote}.  However, it serves as a
@c note to the Emacs Lisp compiler that @var{function-object} is intended
@c to be used only as a function, and therefore can safely be compiled.
@c Contrast this with @code{quote}, in @ref{Quoting}.
$B$3$N%9%Z%7%c%k%U%)!<%`$O!"(B@var{function-object}$B$rI>2A$;$:$K(B
@var{function-object}$B$rJV$9!#(B
$B$3$N0UL#$G$O(B@code{quote}$B$KEy2A$G$"$k!#(B
$B$7$+$7!"$3$l$O!"(BEmacs Lisp$B%3%s%Q%$%i$KBP$7$F$OCm0U=q$-$H$7$FF/$-!"(B
@var{function-object}$B$r4X?t$H$7$F$N$_;H$&0U?^$,$"$j!"(B
$B$7$?$,$C$F!"%3%s%Q%$%k$7$F$b0BA4$G$"$k$3$H$r0UL#$9$k!#(B
@ref{Quoting}$B$N(B@code{quote}$B$HHf3S$7$F$[$7$$!#(B
@end defspec

@c   See @code{documentation} in @ref{Accessing Documentation}, for a
@c realistic example using @code{function} and an anonymous function.
@code{function}$B$HL5L>4X?t$rMQ$$$?<B:]E*$JNc$O!"(B
@ref{Accessing Documentation}$B$N(B@code{documentation}$B$r;2>H$7$F$/$@$5$$!#(B

@node Function Cells
@c @section Accessing Function Cell Contents
@section $B4X?t%;%k$NFbMF$N;2>H(B

@c   The @dfn{function definition} of a symbol is the object stored in the
@c function cell of the symbol.  The functions described here access, test,
@c and set the function cell of symbols.
$B%7%s%\%k$N(B@dfn{$B4X?tDj5A(B}$B!J(Bfunction definition$B!K$H$O!"(B
$B%7%s%\%k$N4X?t%;%k$K3JG<$5$l$?%*%V%8%'%/%H$G$9!#(B
$B$3$3$G@bL@$9$k4X?t$O!"%7%s%\%k$N4X?t%;%k$r;2>H$7$?$j!"D4$Y$?$j!"(B
$B@_Dj$7$?$j$7$^$9!#(B

@c   See also the function @code{indirect-function} in @ref{Function
@c Indirection}.
@ref{Function Indirection}$B$N4X?t(B@code{indirect-function}$B$b;2>H$7$F$/$@$5$$!#(B

@defun symbol-function symbol
@kindex void-function
@c This returns the object in the function cell of @var{symbol}.  If the
@c symbol's function cell is void, a @code{void-function} error is
@c signaled.
$B$3$l$O!"(B@var{symbol}$B$N4X?t%;%k$N%*%V%8%'%/%H$rJV$9!#(B
$B%7%s%\%k$N4X?t%;%k$,6u$G$"$k$H!"%(%i!<(B@code{void-function}$B$rDLCN$9$k!#(B

@c This function does not check that the returned object is a legitimate
@c function.
$B$3$N4X?t$O!"JV$9%*%V%8%'%/%H$,@5$7$$4X?t$G$"$k$+$I$&$+8!::$7$J$$!#(B

@example
@group
(defun bar (n) (+ n 2))
     @result{} bar
@end group
@group
(symbol-function 'bar)
     @result{} (lambda (n) (+ n 2))
@end group
@group
(fset 'baz 'bar)
     @result{} bar
@end group
@group
(symbol-function 'baz)
     @result{} bar
@end group
@end example
@end defun

@c @cindex void function cell
@cindex $B6u$N4X?t%;%k(B
@c   If you have never given a symbol any function definition, we say that
@c that symbol's function cell is @dfn{void}.  In other words, the function
@c cell does not have any Lisp object in it.  If you try to call such a symbol
@c as a function, it signals a @code{void-function} error.
$B%7%s%\%k$K0lEY$b4X?tDj5A$rM?$($F$$$J$$$H!"(B
$B$=$N%7%s%\%k$N4X?t%;%k$O(B@dfn{$B6u(B}$B!J(Bvoid$B!K$G$"$k$H$$$$$^$9!#(B
$B$$$$$+$($l$P!"4X?t%;%k$K$O$I$s$J(BLisp$B%*%V%8%'%/%H$bF~$C$F$$$^$;$s!#(B
$B$=$N$h$&$J%7%s%\%k$r4X?t$H$7$F8F$S=P$=$&$H$9$k$H!"(B
$B%(%i!<(B@code{void-function}$B$rDLCN$7$^$9!#(B

@c   Note that void is not the same as @code{nil} or the symbol
@c @code{void}.  The symbols @code{nil} and @code{void} are Lisp objects,
@c and can be stored into a function cell just as any other object can be
@c (and they can be valid functions if you define them in turn with
@c @code{defun}).  A void function cell contains no object whatsoever.
$B6u!J(Bvoid$B!K$O!"(B@code{nil}$B$d%7%s%\%k(B@code{void}$B$H0c$&$3$H$KCm0U$7$F$/$@$5$$!#(B
$B%7%s%\%k(B@code{nil}$B$b(B@code{void}$B$b(BLisp$B%*%V%8%'%/%H$G$"$j!"(B
$B$=$l$i$OB>$N%*%V%8%'%/%H$HF1MM$K4X?t%;%k$K3JG<$G$-$^$9(B
$B!J$=$7$F!"$=$l$i$r(B@code{defun}$B$GDj5A$7$F$*$1$P!"@5$7$$4X?t$G$"$k!K!#(B
$B6u$N4X?t%;%k$K$O!"$I$s$J%*%V%8%'%/%H$b4^$^$l$F$$$^$;$s!#(B

@c   You can test the voidness of a symbol's function definition with
@c @code{fboundp}.  After you have given a symbol a function definition, you
@c can make it void once more using @code{fmakunbound}.
$B%7%s%\%k$N4X?tDj5A$,6u$+$I$&$+$O(B@code{fboundp}$B$GD4$Y$k$3$H$,$G$-$^$9!#(B
$B%7%s%\%k$K4X?tDj5A$rM?$($?$"$H$G$b!"(B
@code{fmakunbound}$B$r;H$C$F$U$?$?$S6u$K$G$-$^$9!#(B

@defun fboundp symbol
@c This function returns @code{t} if the symbol has an object in its
@c function cell, @code{nil} otherwise.  It does not check that the object
@c is a legitimate function.
$B$3$N4X?t$O!"%7%s%\%k$N4X?t%;%k$K%*%V%8%'%/%H$,F~$C$F$$$l$P(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B%*%V%8%'%/%H$,@5$7$$4X?t$G$"$k$+$I$&$+8!::$7$J$$!#(B
@end defun

@defun fmakunbound symbol
@c This function makes @var{symbol}'s function cell void, so that a
@c subsequent attempt to access this cell will cause a @code{void-function}
@c error.  (See also @code{makunbound}, in @ref{Void Variables}.)
$B$3$N4X?t$O(B@var{symbol}$B$N4X?t%;%k$r6u$K$9$k!#(B
$B$3$l0J9_$K$3$N%;%k$r;2>H$7$h$&$H$9$k$H!"(B
$B%(%i!<(B@code{void-function}$B$r0z$-5/$3$9!#(B
$B!J(B@ref{Void Variables}$B$N(B@code{makunbound}$B$b;2>H!K!#(B

@example
@group
(defun foo (x) x)
     @result{} foo
@end group
@group
(foo 1)
     @result{}1
@end group
@group
(fmakunbound 'foo)
     @result{} foo
@end group
@group
(foo 1)
@error{} Symbol's function definition is void: foo
@end group
@end example
@end defun

@defun fset symbol definition
@c This function stores @var{definition} in the function cell of
@c @var{symbol}.  The result is @var{definition}.  Normally
@c @var{definition} should be a function or the name of a function, but
@c this is not checked.  The argument @var{symbol} is an ordinary evaluated
@c argument.
$B$3$N4X?t$O!"(B@var{symbol}$B$N4X?t%;%k$K(B@var{definition}$B$r3JG<$9$k!#(B
$B7k2L$O(B@var{definition}$B$G$"$k!#(B
$BDL>o!"(B@var{definition}$B$O4X?t$+4X?tL>$G$"$k$Y$-$@$,!"(B
$B$=$&$G$"$k$+$I$&$+8!::$7$J$$!#(B
$B0z?t(B@var{symbol}$B$ODL>o$I$*$jI>2A$5$l$k0z?t$G$"$k!#(B

@c There are three normal uses of this function:
$B$3$N4X?t$NIaDL$N(B3$B$D$N;H$$J}$O$D$.$N$H$*$j!#(B

@itemize @bullet
@item
@c Copying one symbol's function definition to another---in other words,
@c making an alternate name for a function.  (If you think of this as the
@c definition of the new name, you should use @code{defalias} instead of
@c @code{fset}; see @ref{Defining Functions}.)
$B$"$k%7%s%\%k$N4X?tDj5A$rJL$N$b$N$K%3%T!<$9$k!#(B
$B$$$$$+$($l$P!"4X?t$NJLL>$r:n$k!#(B
$B!J$3$l$r?7$?$JL>A0$NDj5A$H9M$($k$J$i$P!"(B
@code{fset}$B$N$+$o$j$K(B@code{defalias}$B$r;H$&$Y$-$G$"$k!#(B
@pxref{Defining Functions}$B!#!K(B

@item
@c Giving a symbol a function definition that is not a list and therefore
@c cannot be made with @code{defun}.  For example, you can use @code{fset}
@c to give a symbol @code{s1} a function definition which is another symbol
@c @code{s2}; then @code{s1} serves as an alias for whatever definition
@c @code{s2} presently has.  (Once again use @code{defalias} instead of
@c @code{fset} if you think of this as the definition of @code{s1}.)
$B%j%9%H$G$O$J$$4X?tDj5A$r%7%s%\%k$KM?$($k!#(B
$B$3$l$O!"(B@code{defun}$B$G$O$G$-$J$$!#(B
$B$?$H$($P!"(B@code{fset}$B$r;H$C$F!"(B@code{s1}$B$K4X?tDj5A$H$7$F(B
$BJL$N%7%s%\%k(B@code{s2}$B$rM?$($k$3$H$,$G$-$k!#(B
$B$9$k$H!"(B@code{s1}$B$O!"(B@code{s2}$B$N8=:_$NDj5A$NJLL>$H$7$FF/$/!#(B
$B!J$3$l$r(B@code{s1}$B$NDj5A$H9M$($k$N$G$"$l$P!"(B
$B$d$O$j!"(B@code{fset}$B$N$+$o$j$K(B@code{defalias}$B$r;H$&!#!K(B

@item
@c In constructs for defining or altering functions.  If @code{defun}
@c were not a primitive, it could be written in Lisp (as a macro) using
@c @code{fset}.
$B4X?t$rDj5A$7$?$jJQ99$7$?$j$9$k9=J8$G;H$&!#(B
@code{defun}$B$,4pK\4X?t$G$J$+$C$?$J$i$P!"(B
@code{fset}$B$r;H$C$F!J%^%/%m$H$7$F!K(BLisp$B$G(B@code{defun}$B$r=q$/$3$H$,$G$-$k!#(B
@end itemize

@c Here are examples of these uses:
$B$3$l$i$N;HMQNc$r<($9!#(B

@example
@group
@c ;; @r{Save @code{foo}'s definition in @code{old-foo}.}
;; @r{@code{foo}$B$NDj5A$r(B@code{old-foo}$B$KJ]B8$9$k(B}
(fset 'old-foo (symbol-function 'foo))
@end group

@group
@c ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
@c ;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
;; @r{$B%7%s%\%k(B@code{car}$B$r(B@code{xfirst}$B$N4X?tDj5A$K$9$k(B}
;; @r{$B!J$3$l$K$O!"(B@code{fset}$B$h$j(B@code{defalias}$B$N$[$&$,$h$$!K(B}
(fset 'xfirst 'car)
     @result{} car
@end group
@group
(xfirst '(1 2 3))
     @result{} 1
@end group
@group
(symbol-function 'xfirst)
     @result{} car
@end group
@group
(symbol-function (symbol-function 'xfirst))
     @result{} #<subr car>
@end group

@group
@c ;; @r{Define a named keyboard macro.}
;; @r{$BL>A0IU$-$N%-!<%\!<%I%^%/%m$rDj5A$9$k(B}
(fset 'kill-two-lines "\^u2\^k")
     @result{} "\^u2\^k"
@end group

@group
@c ;; @r{Here is a function that alters other functions.}
;; @r{$BB>$N4X?t$rJQ99$9$k4X?t(B}
(defun copy-function-definition (new old)
  "Define NEW with the same function definition as OLD."
  (fset new (symbol-function old)))
@end group
@end example
@end defun

@c   When writing a function that extends a previously defined function,
@c the following idiom is sometimes used:
$B4{B8$N4X?tDj5A$r3HD%$9$k4X?t$r=q$/$H$-$K$O!"(B
$B$D$.$N$h$&$J>oEe6g$r;H$&$3$H$b$"$j$^$9!#(B

@example
(fset 'old-foo (symbol-function 'foo))
(defun foo ()
  "Just like old-foo, except more so."
@group
  (old-foo)
  (more-so))
@end group
@end example

@noindent
@c This does not work properly if @code{foo} has been defined to autoload.
@c In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
@c to define @code{old-foo} by loading a file.  Since this presumably
@c defines @code{foo} rather than @code{old-foo}, it does not produce the
@c proper results.  The only way to avoid this problem is to make sure the
@c file is loaded before moving aside the old definition of @code{foo}.
@code{foo}$B$,<+F0%m!<%I$HDj5A$5$l$F$$$k$H!"$3$l$O@5$7$/F0:n$7$^$;$s!#(B
$B$=$N$h$&$J>l9g$K$O!"(B@code{foo}$B$,(B@code{old-foo}$B$r8F$S=P$9$H!"(B
Lisp$B$O%U%!%$%k$r%m!<%I$7$F(B@code{old-foo}$B$rDj5A$7$h$&$H$7$^$9!#(B
$B$7$+$7!"$3$l$O(B@code{old-foo}$B$G$O$J$/(B@code{foo}$B$rDj5A$9$k$N$G!"(B
$B@5$7$$7k2L$rF@$i$l$^$;$s!#(B
$B$3$NLdBj$r2sHr$9$kM#0l$NJ}K!$O!"(B
@code{foo}$B$N8E$$Dj5A$r0\$9$^$($K!"3N<B$K%U%!%$%k$r%m!<%I$7$F$*$/$3$H$G$9!#(B

@c   But it is unmodular and unclean, in any case, for a Lisp file to
@c redefine a function defined elsewhere.  It is cleaner to use the advice
@c facility (@pxref{Advising Functions}).
$B$7$+$7!"JL$N2U=j$GDj5A$5$l$?4X?t$r:FDj5A$9$k(BLisp$B%U%!%$%k$KBP$7$F$O!"(B
$B$$$:$l$K$7$F$b!"$3$l$G$O%b%8%e!<%k2=$b8+DL$7$b$h$/$"$j$^$;$s!#(B
$B%"%I%P%$%:5!G=!J(B@pxref{Advising Functions}$B!K$r;H$($P!"8+DL$7$,$h$/$J$j$^$9!#(B

@node Inline Functions
@c @section Inline Functions
@section $B%$%s%i%$%s4X?t(B
@c @cindex inline functions
@cindex $B%$%s%i%$%s4X?t(B

@findex defsubst
@c You can define an @dfn{inline function} by using @code{defsubst} instead
@c of @code{defun}.  An inline function works just like an ordinary
@c function except for one thing: when you compile a call to the function,
@c the function's definition is open-coded into the caller.
@code{defun}$B$N$+$o$j$K(B@code{defsubst}$B$r;H$&$3$H$G!"(B
@dfn{$B%$%s%i%$%s4X?t(B}$B!J(Binline function$B!K$rDj5A$G$-$^$9!#(B
$B%$%s%i%$%s4X?t$O!"(B1$B$D$NE@$r=|$$$F!"IaDL$N4X?t$HF1MM$KF0:n$7$^$9!#(B
$B$=$N$h$&$J4X?t$N8F$S=P$7$r%3%s%Q%$%k$9$k$H!"(B
$B4X?tDj5A$O8F$S=P$7B&$GE83+$5$l$^$9!#(B

@c Making a function inline makes explicit calls run faster.  But it also
@c has disadvantages.  For one thing, it reduces flexibility; if you change
@c the definition of the function, calls already inlined still use the old
@c definition until you recompile them.  Since the flexibility of
@c redefining functions is an important feature of Emacs, you should not
@c make a function inline unless its speed is really crucial.
$B4X?t$rE83+$9$k$HL@<(E*$J8F$S=P$7$,9bB.$K$J$j$^$9!#(B
$B$7$+$7!"$=$l$K$O7gE@$b$"$j$^$9!#(B
$B$=$N(B1$B$D$O!"=@Fp@-$r8:$i$9$3$H$G$9!#(B
$B4X?t$NDj5A$rJQ99$7$F$b!"%3%s%Q%$%k$7D>$9$^$G$O!"(B
$B$9$G$KE83+$5$l$?8F$S=P$7$O8E$$Dj5A$r;H$$B3$1$^$9!#(B
$B4X?t$r:FDj5A$G$-$k=@Fp@-$O(BEmacs$B$G$O=EMW$J5!G=$G$9$+$i!"(B
$BB.EY$,K\Ev$K=EMW$G$J$1$l$P!"4X?t$rE83+$9$Y$-$G$O$"$j$^$;$s!#(B

@c Another disadvantage is that making a large function inline can increase
@c the size of compiled code both in files and in memory.  Since the speed
@c advantage of inline functions is greatest for small functions, you
@c generally should not make large functions inline.
$BJL$N7gE@$O!"Bg$-$J4X?t$rE83+$9$k$H!"%3%s%Q%$%k$7$?4X?t$N%5%$%:$,(B
$B%U%!%$%kFb$G$b%a%b%j>e$G$bA}2C$7$^$9!#(B
$B%$%s%i%$%s4X?t$N%9%T!<%I$NMxE@$O!">.$5$J4X?t$G$b$C$H$bBg$-$$$N$G!"(B
$B0lHL$K$OBg$-$J4X?t$rE83+$9$Y$-$G$O$"$j$^$;$s!#(B

@c It's possible to define a macro to expand into the same code that an
@c inline function would execute.  (@xref{Macros}.)  But the macro would be
@c limited to direct use in expressions---a macro cannot be called with
@c @code{apply}, @code{mapcar} and so on.  Also, it takes some work to
@c convert an ordinary function into a macro.  To convert it into an inline
@c function is very easy; simply replace @code{defun} with @code{defsubst}.
@c Since each argument of an inline function is evaluated exactly once, you
@c needn't worry about how many times the body uses the arguments, as you
@c do for macros.  (@xref{Argument Evaluation}.)
$B%$%s%i%$%s4X?t$,<B9T$9$k$N$HF1$8%3!<%I$KE83+$9$k$h$&$K%^%/%m$rDj5A$9$k(B
$B$3$H$b2DG=$G$9!#(B
$B!J(B@pxref{Macros}$B!#!K(B
$B$7$+$7!"%^%/%m$O<0$GD>@\;H$C$?>l9g$K@)8B$5$l$^$9!#(B
$B%^%/%m$O!"(B@code{apply}$B$d(B@code{mapcar}$B$J$I$G8F$S=P$;$^$;$s!#(B
$B$5$i$K!"IaDL$N4X?t$r%^%/%m$KJQ49$9$k$K$O!"B?>/$N:n6H$,I,MW$G$9!#(B
$BIaDL$N4X?t$r%$%s%i%$%s4X?t$KJQ49$9$k$N$O$H$F$b4JC1$G$9!#(B
$BC1$K!"(B@code{defun}$B$r(B@code{defsubst}$B$GCV$-49$($k$@$1$G$9!#(B
$B%$%s%i%$%s4X?t$N3F0z?t$O!"$A$g$&$I(B1$B2s$@$1I>2A$5$l$k$N$G!"(B
$B%^%/%m$N$h$&$KK\BN$G0z?t$r2?2s;H$&$+$r9MN8$9$kI,MW$O$"$j$^$;$s!#(B
$B!J(B@pxref{Argument Evaluation}$B!#!K(B

@c Inline functions can be used and open-coded later on in the same file,
@c following the definition, just like macros.
$B%$%s%i%$%s4X?t$O!"%^%/%m$HF1MM$K!"(B
$BF1$8%U%!%$%kFb$NDj5A0LCV$h$j$&$7$m$G;H$o$lE83+$5$l$^$9!#(B

@c Emacs versions prior to 19 did not have inline functions.

@node Related Topics
@c @section Other Topics Related to Functions
@section $B4X?t$K4XO"$7$?$=$NB>$NOCBj(B

@c   Here is a table of several functions that do things related to
@c function calling and function definitions.  They are documented
@c elsewhere, but we provide cross references here.
$B4X?t8F$S=P$7$H4X?tDj5A$K4XO"$7$?$$$/$D$+$N4X?t$N0lMw$r$"$2$F$*$-$^$9!#(B
$B$3$l$i$OJL$N>l=j$G@bL@$7$F$"$j$^$9$,!"Aj8_;2>H$r$"$2$F$*$-$^$9!#(B

@table @code
@item apply
@c See @ref{Calling Functions}.
@pxref{Calling Functions}$B!#(B

@item autoload
@c See @ref{Autoload}.
@pxref{Autoload}$B!#(B

@item call-interactively
@c See @ref{Interactive Call}.
@pxref{Interactive Call}$B!#(B

@item commandp
@c See @ref{Interactive Call}.
@pxref{Interactive Call}$B!#(B

@item documentation
@c See @ref{Accessing Documentation}.
@pxref{Accessing Documentation}$B!#(B

@item eval
@c See @ref{Eval}.
@pxref{Eval}$B!#(B

@item funcall
@c See @ref{Calling Functions}.
@pxref{Calling Functions}$B!#(B

@item function
@c See @ref{Anonymous Functions}.
@pxref{Anonymous Functions}$B!#(B

@item ignore
@c See @ref{Calling Functions}.
@pxref{Calling Functions}$B!#(B

@item indirect-function
@c See @ref{Function Indirection}.
@pxref{Function Indirection}$B!#(B

@item interactive
@c See @ref{Using Interactive}.
@pxref{Using Interactive}$B!#(B

@item interactive-p
@c See @ref{Interactive Call}.
@pxref{Interactive Call}$B!#(B

@item mapatoms
@c See @ref{Creating Symbols}.
@pxref{Creating Symbols}$B!#(B

@item mapcar
@c See @ref{Mapping Functions}.
@pxref{Mapping Functions}$B!#(B

@item map-char-table
@c See @ref{Char-Tables}.
@pxref{Char-Tables}$B!#(B

@item mapconcat
@c See @ref{Mapping Functions}.
@pxref{Mapping Functions}$B!#(B

@item undefined
@c See @ref{Key Lookup}.
@pxref{Key Lookup}$B!#(B
@end table