@c -*-texinfo-*-
@setfilename ../info/functions
@node Functions, Macros, Variables, Top
@chapter Functions

  A Lisp program is composed mainly of Lisp functions.  This chapter
explains what functions are, how they accept arguments, and how to
define them.

@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.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.
@end menu

@node What Is a Function, Lambda Expressions, Functions, Functions
@section What Is a Function?

  In a general sense, a function is a rule for carrying on a computation
given several values called @dfn{arguments}.  The result of the
computation is called the value of the function.  The computation can
also have side effects: lasting changes in the values of variables or
the contents of data structures.

  Here are important terms for functions in Emacs Lisp and for other
function-like objects.

@table @dfn
@item function
@cindex function
In Emacs Lisp, a @dfn{function} is anything that can be applied to
arguments in a Lisp program.  In some cases, we will use it more
specifically to mean a function written in Lisp.  Special forms and
macros are not functions.

@item primitive
@cindex primitive
@cindex subr
@cindex built-in function
A @dfn{primitive} is a function callable from Lisp that is written in C,
such as @code{car} or @code{append}.  These functions are also called
@dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
considered primitives.)

Primitives provide the lowest-level interfaces to editing functions or
operating system services, or in a few cases they perform important
operations more quickly than a Lisp program could.  Primitives can be
modified or added only by changing the C sources and recompiling the
editor.  See @ref{Writing Emacs Primitives}.

@item lambda expression
A @dfn{lambda expression} is a function written in Lisp.
These are described in the following section.
@ifinfo
@xref{Lambda Expressions}.
@end ifinfo

@item special form
A @dfn{special form} is a primitive that is like a function but does not
evaluate all of its arguments in the usual way.  It may evaluate only
some of the arguments, or may evaluate them in an unusual order, or
several times.  Many special forms are described in @ref{Control
Structures}.

@item macro
@cindex macro
A @dfn{macro} is a construct defined in Lisp by the programmer.  It
differs from a function in that it translates a Lisp expression that you
write into an equivalent expression to be evaluated instead of the
original expression.  @xref{Macros}, for how to define and use macros.

@item command
@cindex command
A @dfn{command} is an object that @code{command-execute} can invoke; it
is a possible definition for a key sequence.  Some functions are
commands; a function written in Lisp is a command if it contains an
interactive declaration (@pxref{Defining Commands}).  Such a function
can be called from Lisp expressions like other functions; in this case,
the fact that the function is a command makes no difference.

Strings are commands also, even though they are not functions.  A symbol
is a command if its function definition is a command; such symbols can
be invoked with @kbd{M-x}.  The symbol is a function as well if the 
definition is a function.  @xref{Command Overview}.

@item keystroke command
@cindex keystroke command
A @dfn{keystroke command} is a command that is bound to a key sequence
(typically one to three keystrokes).  The distinction is made here
merely to avoid confusion with the meaning of ``command'' in non-Emacs
editors; for programmers, the distinction is normally unimportant.
@end table

@defun subrp object
This function returns @code{t} if @var{object} is a built-in function
(i.e. a Lisp primitive).

@example
(subrp 'message)                ; @r{@code{message} is a symbol,}
     @result{} nil                     ; @r{not a subr object.}
(subrp (symbol-function 'message))
     @result{} t
@end example
@end defun

@node Lambda Expressions, Function Names, What Is a Function, Functions
@section Lambda Expressions
@cindex lambda expression

  A function written in Lisp is a list that looks like this:

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

@noindent
(Such a list is called a @dfn{lambda expression}, even though it is not
an expression at all, for historical reasons.)

@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, Simple Lambda, Lambda Expressions, Lambda Expressions
@subsection Components of a Lambda Expression

@ifinfo

  A function written in Lisp (a ``lambda expression'') is a list that
looks like this:

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

@cindex lambda list
  The first element of a lambda expression is always the symbol
@code{lambda}.  This indicates that the list represents a function.  The
reason functions are defined to start with @code{lambda} is so that
other lists, intended for other uses, will not accidentally be valid as
functions.

  The second element is a list of argument variable names (symbols).
This is called the @dfn{lambda list}.  When a Lisp function is called,
the argument values are matched up against the variables in the lambda
list, which are given local bindings with the values provided.
@xref{Local Variables}.

  The documentation string is an actual string that serves to describe
the function for the Emacs help facilities.  @xref{Function Documentation}.

  The interactive declaration is a list of the form @code{(interactive
@var{code-string})}.  This declares how to provide arguments if the
function is used interactively.  Functions with this declaration are called
@dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
Functions not intended to be called in this way should not have interactive
declarations.  @xref{Defining Commands}, for how to write an interactive
declaration.

@cindex body of function
  The rest of the elements are the @dfn{body} of the function: the Lisp
code to do the work of the function (or, as a Lisp programmer would say,
``a list of Lisp forms to evaluate'').  The value returned by the
function is the value returned by the last element of the body.

@node Simple Lambda, Argument List, Lambda Components, Lambda Expressions
@subsection A Simple Lambda-Expression Example

  Consider for example the following function:

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

@noindent
We can call this function by writing it as the @sc{car} of an
expression, like this:

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

@noindent
The body of this lambda expression is evaluated with the variable
@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
Evaluation of the body adds these three numbers, producing the result 6;
therefore, this call to the function returns the value 6.

  Note that the arguments can be the results of other function calls, as in
this example:

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

@noindent
Here all the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 4)} are
evaluated, left to right.  Then the lambda expression is applied to the
argument values 1, 6 and 1 to produce the value 8.

  It is not often useful to write a lambda expression as the @sc{car} of
a form in this way.  You can get the same result, of making local
variables and giving them values, using the special form @code{let}
(@pxref{Local Variables}).  And @code{let} is clearer and easier to use.
In practice, lambda expressions are either stored as the function
definitions of symbols, to produce named functions, or passed as
arguments to other functions (@pxref{Anonymous Functions}).

  However, calls to explicit lambda expressions were very useful in the
old days of Lisp, before the special form @code{let} was invented.  At
that time, they were the only way to bind and initialize local
variables.

@node Argument List, Function Documentation, Simple Lambda, Lambda Expressions
@subsection Advanced Features of Argument Lists
@kindex wrong-number-of-arguments
@cindex argument binding
@cindex binding arguments

  Our simple sample function, @code{(lambda (a b c) (+ a b c))},
specifies three argument variables, so it must be called with three
arguments: if you try to call it with only two arguments or four
arguments, you will get a @code{wrong-number-of-arguments} error.

  It is often convenient to write a function that allows certain arguments
to be omitted.  For example, the function @code{substring} accepts three
arguments---a string, the start index and the end index---but the third
argument defaults to the end of the string if you omit it.  It is also
convenient for certain functions to accept an indefinite number of
arguments, as the functions @code{and} and @code{+} do.

@cindex optional arguments
@cindex rest arguments
@kindex &optional
@kindex &rest
  To specify optional arguments that may be omitted when a function
is called, simply include the keyword @code{&optional} before the optional
arguments.  To specify a list of zero or more extra arguments, include the
keyword @code{&rest} before one final argument.

  Thus, the complete syntax for an argument list is as follows:

@example
(@var{required-vars}@dots{}
 @r{[}&optional @var{optional-vars}@dots{}@r{]}
 @r{[}&rest @var{rest-var}@r{]})
@end example

@noindent
The square brackets indicate that the @code{&optional} and @code{&rest}
clauses, and the variables that follow them, are optional.

  A call to the function requires one actual argument for each of the
@var{required-vars}.  There may be actual arguments for zero or more of the
@var{optional-vars}, and there cannot be any more actual arguments than
these unless @code{&rest} exists.  In that case, there may be any number of
extra actual arguments.

  If actual arguments for the optional and rest variables are omitted,
then they always default to @code{nil}.  However, the body of the function
is free to consider @code{nil} an abbreviation for some other meaningful
value.  This is what @code{substring} does; @code{nil} as the third argument
means to use the length of the string supplied.  There is no way for the
function to distinguish between an explicit argument of @code{nil} and
an omitted argument.

@quotation
@b{Common Lisp note:} Common Lisp allows the function to specify what
default values will be used when an optional argument is omitted; GNU Emacs
Lisp always uses @code{nil}.
@end quotation

  For example, an argument list that looks like this:

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

@noindent
binds @code{a} and @code{b} to the first two actual arguments, which are
required.  If one or two more arguments are provided, @code{c} and
@code{d} are bound to them respectively; any arguments after the first
four are collected into a list and @code{e} is bound to that list.  If
there are only two arguments, @code{c} is @code{nil}; if two or three
arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
is @code{nil}.

  There is no way to have required arguments following optional
ones---it would not make sense.  To see why this must be so, suppose
that @code{c} in the example were optional and @code{d} were required.
If three actual arguments are given; then which variable would the third
argument be for?  Similarly, it makes no sense to have any more
arguments (either required or optional) after a @code{&rest} argument.

  Here are some examples of argument lists and proper calls:

@example
((lambda (n) (1+ n))                ; @r{One required:}
 1)                                 ; @r{requires exactly one argument.}
     @result{} 2
((lambda (n &optional n1)           ; @r{One required and one optional:}
         (if n1 (+ n n1) (1+ n)))   ; @r{1 or 2 arguments.}
 1 2)
     @result{} 3
((lambda (n &rest ns)               ; @r{One required and one rest:}
         (+ n (apply '+ ns)))       ; @r{1 or more arguments.}
 1 2 3 4 5)
     @result{} 15
@end example

@node Function Documentation,  , Argument List, Lambda Expressions
@subsection Documentation Strings of Functions
@cindex documentation of function

  A lambda expression may optionally have a @dfn{documentation string} just
after the lambda list.  This string does not affect execution of the
function; it is a kind of comment, but a systematized comment which
actually appears inside the Lisp world and can be used by the Emacs help
facilities.  @xref{Documentation}, for how the @var{documentation-string} is
accessed.

  It is a good idea to provide documentation strings for all commands,
and for all other functions in your program that users of your program
should know about; internal functions might as well have only comments,
since comments don't take up any room when your program is loaded.

  The first line of the documentation string should stand on its own,
because @code{apropos} displays just this first line.  It should consist
of one or two complete sentences that summarize the function's purpose.

  The start of the documentation string is usually indented, but since
these spaces come before the starting double-quote, they are not part of
the string.  Some people make a practice of indenting any additional
lines of the string so that the text lines up.  @emph{This is a
mistake.}  The indentation of the following lines is inside the string;
what looks nice in the source code will look ugly when displayed by the
help commands.

  You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
Since evaluation of a string returns that string, without any side effects,
it has no effect if it is not the last form in the body.  Thus, in
practice, there is no confusion between the first form of the body and the
documentation string; if the only body form is a string then it serves both
as the return value and as the documentation.

@node Function Names, Defining Functions, Lambda Expressions, Functions
@section Naming a Function
@cindex function definition
@cindex named function
@cindex function name

  In most computer languages, every function has a name; the idea of a
function without a name is nonsensical.  In Lisp, a function in the
strictest sense has no name.  It is simply a list whose first element is
@code{lambda}, or a primitive subr-object.

  However, a symbol can serve as the name of a function.  This happens
when you put the function in the symbol's @dfn{function cell}
(@pxref{Symbol Components}).  Then the symbol itself becomes a valid,
callable function, equivalent to the list or subr-object that its
function cell refers to.  The contents of the function cell are also
called the symbol's @dfn{function definition}.

  In practice, nearly all functions are given names in this way and
referred to through their names.  For example, the symbol @code{car} works
as a function and does what it does because the primitive subr-object
@code{#<subr car>} is stored in its function cell.

  We give functions names because it is more convenient to refer to them
by their names in other functions.  For primitive subr-objects such as
@code{#<subr car>}, names are the only way you can refer to them: there
is no read syntax for such objects.  For functions written in Lisp, the
name is more convenient to use in a call than an explicit lambda
expression.  Also, a function with a name can refer to itself---it can
be recursive.  Writing the function's name in its own definition is much
more convenient than making the function definition point to itself
(something that is not impossible but that has various disadvantages in
practice).

  Functions are often identified with the symbols used to name them.  For
example, we often speak of ``the function @code{car}'', not distinguishing
between the symbol @code{car} and the primitive subr-object that is its
function definition.  For most purposes, there is no need to distinguish.

  Even so, keep in mind that a function need not have a unique name.  While
a given function object @emph{usually} appears in the function cell of only
one symbol, this is just a matter of convenience.  It is very easy to store
it in several symbols using @code{fset}; then each of the symbols is
equally well a name for the same function.

  A symbol used as a function name may also be used as a variable;
these two uses of a symbol are independent and do not conflict.

@node Defining Functions, Calling Functions, Function Names, Functions
@section Defining Named Functions
@cindex defining a function

  We usually give a name to a function when it is first created.  This
is called @dfn{defining a function}, and it is done with the
@code{defun} special form.

@defspec defun name argument-list body-forms
@code{defun} is the usual way to define new Lisp functions.  It
defines the symbol @var{name} as a function that looks like this:

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

This lambda expression is stored in the function cell of @var{name}.
The value returned by evaluating the @code{defun} form is @var{name},
but usually we ignore this value.

As described previously (@pxref{Lambda Expressions}),
@var{argument-list} is a list of argument names and may include the
keywords @code{&optional} and @code{&rest}.  Also, the first two forms
in @var{body-forms} may be a documentation string and an interactive
declaration.

Note that the same symbol @var{name} may also be used as a global
variable, since the value cell is independent of the function cell.

Here are some examples:

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

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

(defun capitalize-backwards ()
  "This function makes the last letter of a word upper case."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))
     @result{} capitalize-backwards
@end example

Be careful not to redefine existing functions unintentionally.
@code{defun} will redefine even primitive functions such as @code{car}
without any hesitation or notification.  Redefining a function already
defined is often done deliberately, and there is no way to distinguish
deliberate redefinition from unintentional redefinition.
@end defspec

@node Calling Functions, Mapping Functions, Defining Functions, Functions
@section Calling Functions
@cindex function invocation
@cindex calling a function

  Defining functions is only half the battle.  Functions don't do
anything until you @dfn{call} them, i.e., tell them to run.  This
process is also known as @dfn{invocation}.

  The most common way of invoking a function is by evaluating a list.  For
example, evaluating the list @code{(concat "a" "b")} calls the function
@code{concat}.  @xref{Evaluation}, for a description of evaluation.

  When you write a list as an expression in your program, the function
name is part of the program.  This means that the choice of which
function to call is made when you write the program.  Usually that's
just what you want.  Occasionally you need to decide at run time which
function to call.  Then you can use the functions @code{funcall} and
@code{apply}.

@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
whatever @var{function} returns.

Since @code{funcall} is a function, all of its arguments, including
@var{function}, are evaluated before @code{funcall} is called.  This
means that you can use any expression to obtain the function to be
called.  It also means that @code{funcall} does not see the expressions
you write for the @var{arguments}, only their values.  These values are
@emph{not} evaluated a second time in the act of calling @var{function};
@code{funcall} enters the normal procedure for calling a function at the
place where the arguments have already been evaluated.

The argument @var{function} must be either a Lisp function or a
primitive function.  Special forms and macros are not allowed, because
they make sense only when given the ``unevaluated'' argument
expressions.  @code{funcall} cannot provide these because, as we saw
above, it never knows them in the first place.

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

Compare this example with that of @code{apply}.
@end defun

@defun apply function &rest arguments
@code{apply} calls @var{function} with @var{arguments}, just like
@code{funcall} but with one difference: the last of @var{arguments} is a
list of arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended} to the other
arguments.

@code{apply} returns the result of calling @var{function}.  As with
@code{funcall}, @var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make sense in
@code{apply}.

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

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

An interesting example of using @code{apply} is found in the description
of @code{mapcar}; see the following section.
@end defun

@cindex functionals
  It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using @code{funcall} or @code{apply}.  Functions
that accept function arguments are often called @dfn{functionals}.

  Sometimes, when you call such a function, it is useful to supply a
no-op function as the argument.  Here are two different kinds of no-op
function:

@defun identity arg
This function returns @var{arg} and has no side effects.
@end defun

@defun ignore &rest args
This function ignores any arguments and returns @code{nil}.
@end defun

@node Mapping Functions, Anonymous Functions, Calling Functions, Functions
@section Mapping Functions
@cindex mapping functions

  A @dfn{mapping function} applies a given function to each element of a
list or other collection.  Emacs Lisp has three such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
here.  For the third mapping function, @code{mapatoms}, see
@ref{Creating Symbols}.

@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence} in
turn.  The results are made into a @code{nil}-terminated list.

The argument @var{sequence} may be a list, a vector or a string.  The
result is always a list.  The length of the result is the same as the
length of @var{sequence}.

For example: 

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

;; @r{Call each function in @code{my-hooks}.}
(mapcar 'funcall my-hooks)

(defun mapcar* (f &rest args)
  "Apply FUNCTION to successive cars of all ARGS, until one ends.
Return the list of results."
  (if (not (memq 'nil args))              ; @r{If no list is exhausted,}
      (cons (apply f (mapcar 'car args))  ; @r{Apply function to @sc{CAR}s.}
            (apply 'mapcar* f             ; @r{Recurse for rest of elements.}
                   (mapcar 'cdr args)))))

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

@defun mapconcat function sequence separator
@code{mapconcat} applies @var{function} to each element of
@var{sequence}: the results, which must be strings, are concatenated.
Between each pair of result strings, @code{mapconcat} inserts the string
@var{separator}.  Usually @var{separator} contains a space or comma or
other suitable punctuation.

The argument @var{function} must be a function that can take one
argument and returns a string.
  
@example
(mapconcat 'symbol-name
           '(The cat in the hat)
           " ")
     @result{} "The cat in the hat"

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

@node Anonymous Functions, Function Cells, Mapping Functions, Functions
@section Anonymous Functions
@cindex anonymous function

  In Lisp, a function is a list that starts with @code{lambda} (or
alternatively a primitive subr-object); names are ``extra''.  Although
usually functions are defined with @code{defun} and given names at the
same time, it is occasionally more concise to use an explicit lambda
expression---an anonymous function.  Such a list is valid wherever a
function name is.

  Any method of creating such a list makes a valid function.  Even this:

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

@noindent
This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
makes it the value (@emph{not} the function definition!) of
@code{silly}.

  Here is how we might call this function:

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

@noindent
(It does @emph{not} work to write @code{(silly 1)}, because this function
is not the @emph{function definition} of @code{silly}.  We have not given
@code{silly} any function definition, just a value as a variable.)

  Most of the time, anonymous functions are constants that appear in
your program.  For example, you might want to pass one as an argument
to the function @code{mapcar}, which applies any given function to each
element of a list.  Here we pass an anonymous function that multiplies
a number by two:

@example
(defun double-each (list)
  (mapcar '(lambda (x) (* 2 x)) list))
     @result{} double-each
(double-each '(2 11))
     @result{} (4 22)
@end example

@noindent
In such cases, we usually use the special form @code{function} instead
of simple quotation to quote the anonymous function.

@defspec function function-object
@cindex function quoting
This special form returns @var{function-object} without evaluating it.
In this, it is equivalent to @code{quote}.  However, it serves as a
note to the Emacs Lisp compiler that @var{function-object} is intended
to be used only as a function, and therefore can safely be compiled.
@xref{Quoting}, for comparison.
@end defspec

  Using @code{function} instead of @code{quote} makes a difference
inside a function or macro that you are going to compile.  For example:

@example
(defun double-each (list)
  (mapcar (function (lambda (x) (* 2 x))) list))
     @result{} double-each
(double-each '(2 11))
     @result{} (4 22)
@end example

@noindent
If this definition of @code{double-each} is compiled, the anonymous
function is compiled as well.  By contrast, in the previous definition
where ordinary @code{quote} is used, the argument passed to
@code{mapcar} is the precise list shown:

@example
(lambda (arg) (+ arg 5))
@end example

@noindent
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what @code{mapcar} does with the
list.  Perhaps @code{mapcar} will check that the @sc{car} of the third
element is the symbol @code{+}!  The advantage of @code{function} is
that it tells the compiler to go ahead and compile the constant
function.

  We sometimes write @code{function} instead of @code{quote} when
quoting the name of a function, but this usage is just a sort of
comment.

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

  See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example using @code{function} and an anonymous function.

@node Function Cells, Related Topics, Anonymous Functions, Functions
@section Accessing Function Cell Contents

  The @dfn{function definition} of a symbol is the object stored in the
function cell of the symbol.  The functions described here access, test,
and set the function cell of symbols.

@defun symbol-function symbol
@kindex void-function
This returns the object in the function cell of @var{symbol}.  If the
symbol's function cell is void, a @code{void-function} error is
signaled.

This function does not check that the returned object is a legitimate
function.

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

@cindex void function cell
  If you have never given a symbol any function definition, we say that
that symbol's function cell is @dfn{void}.  In other words, the function
cell does not have any Lisp object in it.  If you try to call such a symbol
as a function, it signals a @code{void-function} error.

  Note that void is not the same as @code{nil} or the symbol
@code{void}.  The symbols @code{nil} and @code{void} are Lisp objects,
and can be stored into a function cell just as any other object can be
(and they can be valid functions if you define them in turn with
@code{defun}); but @code{nil} or @code{void} is @emph{an object}.  A
void function cell contains no object whatsoever.

  You can test the voidness of a symbol's function definition with
@code{fboundp}.  After you have given a symbol a function definition, you
can make it void once more using @code{fmakunbound}.

@defun fboundp symbol
Returns @code{t} if the symbol has an object in its function cell,
@code{nil} otherwise.  It does not check that the object is a legitimate
function.
@end defun

@defun fmakunbound symbol
This function makes @var{symbol}'s function cell void, so that a
subsequent attempt to access this cell will cause a @code{void-function}
error.  (See also @code{makunbound}, in @ref{Local Variables}.)

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

@defun fset symbol object
This function stores @var{object} in the function cell of @var{symbol}.
The result is @var{object}.  Normally @var{object} should be a function
or the name of a function, but this is not checked.

There are three normal uses of this function:

@itemize @bullet
@item
Copying one symbol's function definition to another.  (In other words,
making an alternate name for a function.)

@item
Giving a symbol a function definition that is not a list and therefore
cannot be made with @code{defun}.  @xref{Classifying Lists}, for an
example of this usage.

@item
In constructs for defining or altering functions.  If @code{defun}
were not a primitive, it could be written in Lisp (as a macro) using
@code{fset}.
@end itemize

Here are examples of the first two uses:

@example
;; @r{Give @code{first} the same definition @code{car} has.}
(fset 'first (symbol-function 'car))
     @result{} #<subr car>
(first '(1 2 3))
     @result{} 1

;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
(fset 'xfirst 'car)
     @result{} car
(xfirst '(1 2 3))
     @result{} 1
(symbol-function 'xfirst)
     @result{} car
(symbol-function (symbol-function 'xfirst))
     @result{} #<subr car>

@group
;; @r{Define a named keyboard macro.}
(fset 'kill-two-lines "\^u2\^k")
     @result{} "\^u2\^k"
@end group
@end example
@end defun

  When writing a function that extends a previously defined function,
the following idiom is often used:

@example
(fset 'old-foo (symbol-function 'foo))

(defun foo ()
  "Just like old-foo, except more so."
  (old-foo)
  (more-so))
@end example

@noindent
This does not work properly if @code{foo} has been defined to autoload.
In such a case, when @code{foo} calls @code{old-foo}, Lisp will attempt
to define @code{old-foo} by loading a file.  Since this presumably
defines @code{foo} rather than @code{old-foo}, it will not produce the
proper results.  The only way to avoid this problem is to make sure the
file is loaded before moving aside the old definition of @code{foo}.

@node Related Topics,, Function Cells, Functions
@section Other Topics Related to Functions

  Here is a table of several functions that do things related to
function calling and function definitions.

@table @code
@item apply
@xref{Calling Functions}.

@item autoload
@xref{Autoload}.

@item call-interactively
@xref{Interactive Call}.

@item commandp
@xref{Interactive Call}.

@item documentation
@xref{Accessing Documentation}.

@item eval
@xref{Eval}.

@item funcall
@xref{Calling Functions}.

@item ignore
@xref{Calling Functions}.

@item interactive
@xref{Using Interactive}.

@item interactive-p
@xref{Interactive Call}.

@item mapatoms
@xref{Creating Symbols}.

@item mapcar
@xref{Mapping Functions}.

@item mapconcat
@xref{Mapping Functions}.

@item undefined
@xref{Key Lookup}.
@end table
