2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/functions
6 @node Functions, Macros, Variables, Top
9 A Lisp program is composed mainly of Lisp functions. This chapter
10 explains what functions are, how they accept arguments, and how to
14 * What Is a Function:: Lisp functions vs. primitives; terminology.
15 * Lambda Expressions:: How functions are expressed as Lisp objects.
16 * Function Names:: A symbol can serve as the name of a function.
17 * Defining Functions:: Lisp expressions for defining functions.
18 * Calling Functions:: How to use an existing function.
19 * Mapping Functions:: Applying a function to each element of a list, etc.
20 * Anonymous Functions:: Lambda expressions are functions with no names.
21 * Function Cells:: Accessing or setting the function definition
23 * Inline Functions:: Defining functions that the compiler will open code.
24 * Related Topics:: Cross-references to specific Lisp primitives
25 that have a special bearing on how functions work.
28 @node What Is a Function
29 @section What Is a Function?
31 In a general sense, a function is a rule for carrying on a computation
32 given several values called @dfn{arguments}. The result of the
33 computation is called the value of the function. The computation can
34 also have side effects: lasting changes in the values of variables or
35 the contents of data structures.
37 Here are important terms for functions in Emacs Lisp and for other
38 function-like objects.
43 In Emacs Lisp, a @dfn{function} is anything that can be applied to
44 arguments in a Lisp program. In some cases, we use it more
45 specifically to mean a function written in Lisp. Special forms and
46 macros are not functions.
51 @cindex built-in function
52 A @dfn{primitive} is a function callable from Lisp that is written in C,
53 such as @code{car} or @code{append}. These functions are also called
54 @dfn{built-in} functions or @dfn{subrs}. (Special forms are also
55 considered primitives.)
57 Usually the reason that a function is a primitives is because it is
58 fundamental, because it provides a low-level interface to operating
59 system services, or because it needs to run fast. Primitives can be
60 modified or added only by changing the C sources and recompiling the
61 editor. See @ref{Writing Emacs Primitives}.
63 @item lambda expression
64 A @dfn{lambda expression} is a function written in Lisp.
65 These are described in the following section.
67 @xref{Lambda Expressions}.
71 A @dfn{special form} is a primitive that is like a function but does not
72 evaluate all of its arguments in the usual way. It may evaluate only
73 some of the arguments, or may evaluate them in an unusual order, or
74 several times. Many special forms are described in @ref{Control
79 A @dfn{macro} is a construct defined in Lisp by the programmer. It
80 differs from a function in that it translates a Lisp expression that you
81 write into an equivalent expression to be evaluated instead of the
82 original expression. @xref{Macros}, for how to define and use macros.
86 A @dfn{command} is an object that @code{command-execute} can invoke; it
87 is a possible definition for a key sequence. Some functions are
88 commands; a function written in Lisp is a command if it contains an
89 interactive declaration (@pxref{Defining Commands}). Such a function
90 can be called from Lisp expressions like other functions; in this case,
91 the fact that the function is a command makes no difference.
93 Keyboard macros (strings and vectors) are commands also, even though
94 they are not functions. A symbol is a command if its function
95 definition is a command; such symbols can be invoked with @kbd{M-x}.
96 The symbol is a function as well if the definition is a function.
97 @xref{Command Overview}.
99 @item keystroke command
100 @cindex keystroke command
101 A @dfn{keystroke command} is a command that is bound to a key sequence
102 (typically one to three keystrokes). The distinction is made here
103 merely to avoid confusion with the meaning of ``command'' in non-Emacs
104 editors; for Lisp programs, the distinction is normally unimportant.
106 @item byte-code function
107 A @dfn{byte-code function} is a function that has been compiled by the
108 byte compiler. @xref{Byte-Code Type}.
112 This function returns @code{t} if @var{object} is a built-in function
113 (i.e., a Lisp primitive).
117 (subrp 'message) ; @r{@code{message} is a symbol,}
118 @result{} nil ; @r{not a subr object.}
121 (subrp (symbol-function 'message))
127 @defun byte-code-function-p object
128 This function returns @code{t} if @var{object} is a byte-code
129 function. For example:
133 (byte-code-function-p (symbol-function 'next-line))
139 @node Lambda Expressions
140 @section Lambda Expressions
141 @cindex lambda expression
143 A function written in Lisp is a list that looks like this:
146 (lambda (@var{arg-variables}@dots{})
147 @r{[}@var{documentation-string}@r{]}
148 @r{[}@var{interactive-declaration}@r{]}
149 @var{body-forms}@dots{})
153 (Such a list is called a @dfn{lambda expression} for historical reasons,
154 even though it is not really an expression at all---it is not a form
155 that can be evaluated meaningfully.)
158 * Lambda Components:: The parts of a lambda expression.
159 * Simple Lambda:: A simple example.
160 * Argument List:: Details and special features of argument lists.
161 * Function Documentation:: How to put documentation in a function.
164 @node Lambda Components
165 @subsection Components of a Lambda Expression
169 A function written in Lisp (a ``lambda expression'') is a list that
173 (lambda (@var{arg-variables}@dots{})
174 [@var{documentation-string}]
175 [@var{interactive-declaration}]
176 @var{body-forms}@dots{})
181 The first element of a lambda expression is always the symbol
182 @code{lambda}. This indicates that the list represents a function. The
183 reason functions are defined to start with @code{lambda} is so that
184 other lists, intended for other uses, will not accidentally be valid as
187 The second element is a list of symbols--the argument variable names.
188 This is called the @dfn{lambda list}. When a Lisp function is called,
189 the argument values are matched up against the variables in the lambda
190 list, which are given local bindings with the values provided.
191 @xref{Local Variables}.
193 The documentation string is an actual string that serves to describe
194 the function for the Emacs help facilities. @xref{Function Documentation}.
196 The interactive declaration is a list of the form @code{(interactive
197 @var{code-string})}. This declares how to provide arguments if the
198 function is used interactively. Functions with this declaration are called
199 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
200 Functions not intended to be called in this way should not have interactive
201 declarations. @xref{Defining Commands}, for how to write an interactive
204 @cindex body of function
205 The rest of the elements are the @dfn{body} of the function: the Lisp
206 code to do the work of the function (or, as a Lisp programmer would say,
207 ``a list of Lisp forms to evaluate''). The value returned by the
208 function is the value returned by the last element of the body.
211 @subsection A Simple Lambda-Expression Example
213 Consider for example the following function:
216 (lambda (a b c) (+ a b c))
220 We can call this function by writing it as the @sc{car} of an
221 expression, like this:
225 ((lambda (a b c) (+ a b c))
231 This call evaluates the body of the lambda expression with the variable
232 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
233 Evaluation of the body adds these three numbers, producing the result 6;
234 therefore, this call to the function returns the value 6.
236 Note that the arguments can be the results of other function calls, as in
241 ((lambda (a b c) (+ a b c))
247 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
248 4)} from left to right. Then it applies the lambda expression applied
249 to the argument values 1, 6 and 1 to produce the value 8.
251 It is not often useful to write a lambda expression as the @sc{car} of
252 a form in this way. You can get the same result, of making local
253 variables and giving them values, using the special form @code{let}
254 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
255 In practice, lambda expressions are either stored as the function
256 definitions of symbols, to produce named functions, or passed as
257 arguments to other functions (@pxref{Anonymous Functions}).
259 However, calls to explicit lambda expressions were very useful in the
260 old days of Lisp, before the special form @code{let} was invented. At
261 that time, they were the only way to bind and initialize local
265 @subsection Advanced Features of Argument Lists
266 @kindex wrong-number-of-arguments
267 @cindex argument binding
268 @cindex binding arguments
270 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
271 specifies three argument variables, so it must be called with three
272 arguments: if you try to call it with only two arguments or four
273 arguments, you get a @code{wrong-number-of-arguments} error.
275 It is often convenient to write a function that allows certain
276 arguments to be omitted. For example, the function @code{substring}
277 accepts three arguments---a string, the start index and the end
278 index---but the third argument defaults to the @var{length} of the
279 string if you omit it. It is also convenient for certain functions to
280 accept an indefinite number of arguments, as the functions @code{and}
283 @cindex optional arguments
284 @cindex rest arguments
287 To specify optional arguments that may be omitted when a function
288 is called, simply include the keyword @code{&optional} before the optional
289 arguments. To specify a list of zero or more extra arguments, include the
290 keyword @code{&rest} before one final argument.
292 Thus, the complete syntax for an argument list is as follows:
296 (@var{required-vars}@dots{}
297 @r{[}&optional @var{optional-vars}@dots{}@r{]}
298 @r{[}&rest @var{rest-var}@r{]})
303 The square brackets indicate that the @code{&optional} and @code{&rest}
304 clauses, and the variables that follow them, are optional.
306 A call to the function requires one actual argument for each of the
307 @var{required-vars}. There may be actual arguments for zero or more of
308 the @var{optional-vars}, and there cannot be any actual arguments beyond
309 that unless the lambda list uses @code{&rest}. In that case, there may
310 be any number of extra actual arguments.
312 If actual arguments for the optional and rest variables are omitted,
313 then they always default to @code{nil}. However, the body of the function
314 is free to consider @code{nil} an abbreviation for some other meaningful
315 value. This is what @code{substring} does; @code{nil} as the third argument
316 means to use the length of the string supplied. There is no way for the
317 function to distinguish between an explicit argument of @code{nil} and
320 @cindex CL note---default optional arg
322 @b{Common Lisp note:} Common Lisp allows the function to specify what
323 default value to use when an optional argument is omitted; Emacs Lisp
324 always uses @code{nil}.
327 For example, an argument list that looks like this:
330 (a b &optional c d &rest e)
334 binds @code{a} and @code{b} to the first two actual arguments, which are
335 required. If one or two more arguments are provided, @code{c} and
336 @code{d} are bound to them respectively; any arguments after the first
337 four are collected into a list and @code{e} is bound to that list. If
338 there are only two arguments, @code{c} is @code{nil}; if two or three
339 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
342 There is no way to have required arguments following optional
343 ones---it would not make sense. To see why this must be so, suppose
344 that @code{c} in the example were optional and @code{d} were required.
345 Suppose three actual arguments are given; which variable would the third
346 argument be for? Similarly, it makes no sense to have any more
347 arguments (either required or optional) after a @code{&rest} argument.
349 Here are some examples of argument lists and proper calls:
352 ((lambda (n) (1+ n)) ; @r{One required:}
353 1) ; @r{requires exactly one argument.}
355 ((lambda (n &optional n1) ; @r{One required and one optional:}
356 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
359 ((lambda (n &rest ns) ; @r{One required and one rest:}
360 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
365 @node Function Documentation
366 @subsection Documentation Strings of Functions
367 @cindex documentation of function
369 A lambda expression may optionally have a @dfn{documentation string} just
370 after the lambda list. This string does not affect execution of the
371 function; it is a kind of comment, but a systematized comment which
372 actually appears inside the Lisp world and can be used by the Emacs help
373 facilities. @xref{Documentation}, for how the @var{documentation-string} is
376 It is a good idea to provide documentation strings for all commands,
377 and for all other functions in your program that users of your program
378 should know about; internal functions might as well have only comments,
379 since comments don't take up any room when your program is loaded.
381 The first line of the documentation string should stand on its own,
382 because @code{apropos} displays just this first line. It should consist
383 of one or two complete sentences that summarize the function's purpose.
385 The start of the documentation string is usually indented, but since
386 these spaces come before the starting double-quote, they are not part of
387 the string. Some people make a practice of indenting any additional
388 lines of the string so that the text lines up. @emph{This is a
389 mistake.} The indentation of the following lines is inside the string;
390 what looks nice in the source code will look ugly when displayed by the
393 You may wonder how the documentation string could be optional, since
394 there are required components of the function that follow it (the body).
395 Since evaluation of a string returns that string, without any side effects,
396 it has no effect if it is not the last form in the body. Thus, in
397 practice, there is no confusion between the first form of the body and the
398 documentation string; if the only body form is a string then it serves both
399 as the return value and as the documentation.
402 @section Naming a Function
403 @cindex function definition
404 @cindex named function
405 @cindex function name
407 In most computer languages, every function has a name; the idea of a
408 function without a name is nonsensical. In Lisp, a function in the
409 strictest sense has no name. It is simply a list whose first element is
410 @code{lambda}, or a primitive subr-object.
412 However, a symbol can serve as the name of a function. This happens
413 when you put the function in the symbol's @dfn{function cell}
414 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
415 callable function, equivalent to the list or subr-object that its
416 function cell refers to. The contents of the function cell are also
417 called the symbol's @dfn{function definition}. The procedure of using a
418 symbol's function definition in place of the symbol is called
419 @dfn{symbol function indirection}; see @ref{Function Indirection}.
421 In practice, nearly all functions are given names in this way and
422 referred to through their names. For example, the symbol @code{car} works
423 as a function and does what it does because the primitive subr-object
424 @code{#<subr car>} is stored in its function cell.
426 We give functions names because it is convenient to refer to them by
427 their names in Lisp expressions. For primitive subr-objects such as
428 @code{#<subr car>}, names are the only way you can refer to them: there
429 is no read syntax for such objects. For functions written in Lisp, the
430 name is more convenient to use in a call than an explicit lambda
431 expression. Also, a function with a name can refer to itself---it can
432 be recursive. Writing the function's name in its own definition is much
433 more convenient than making the function definition point to itself
434 (something that is not impossible but that has various disadvantages in
437 We often identify functions with the symbols used to name them. For
438 example, we often speak of ``the function @code{car}'', not
439 distinguishing between the symbol @code{car} and the primitive
440 subr-object that is its function definition. For most purposes, there
441 is no need to distinguish.
443 Even so, keep in mind that a function need not have a unique name. While
444 a given function object @emph{usually} appears in the function cell of only
445 one symbol, this is just a matter of convenience. It is easy to store
446 it in several symbols using @code{fset}; then each of the symbols is
447 equally well a name for the same function.
449 A symbol used as a function name may also be used as a variable;
450 these two uses of a symbol are independent and do not conflict.
452 @node Defining Functions
453 @section Defining Named Functions
454 @cindex defining a function
456 We usually give a name to a function when it is first created. This
457 is called @dfn{defining a function}, and it is done with the
458 @code{defun} special form.
460 @defspec defun name argument-list body-forms
461 @code{defun} is the usual way to define new Lisp functions. It
462 defines the symbol @var{name} as a function that looks like this:
465 (lambda @var{argument-list} . @var{body-forms})
468 @code{defun} stores this lambda expression in the function cell of
469 @var{name}. It returns the value @var{name}, but usually we ignore this
472 As described previously (@pxref{Lambda Expressions}),
473 @var{argument-list} is a list of argument names and may include the
474 keywords @code{&optional} and @code{&rest}. Also, the first two forms
475 in @var{body-forms} may be a documentation string and an interactive
478 There is no conflict if the same symbol @var{name} is also used as a
479 variable, since the symbol's value cell is independent of the function
480 cell. @xref{Symbol Components}.
482 Here are some examples:
495 (defun bar (a &optional b &rest c)
501 @result{} (1 2 (3 4 5))
505 @result{} (1 nil nil)
509 @error{} Wrong number of arguments.
513 (defun capitalize-backwards ()
514 "Upcase the last letter of a word."
520 @result{} capitalize-backwards
524 Be careful not to redefine existing functions unintentionally.
525 @code{defun} redefines even primitive functions such as @code{car}
526 without any hesitation or notification. Redefining a function already
527 defined is often done deliberately, and there is no way to distinguish
528 deliberate redefinition from unintentional redefinition.
531 @defun defalias name definition
532 This special form defines the symbol @var{name} as a function, with
533 definition @var{definition}. It's best to use this rather than
534 @code{fset} when defining a function in a file, because @code{defalias}
535 records which file defined the function (@pxref{Unloading}).
538 @node Calling Functions
539 @section Calling Functions
540 @cindex function invocation
541 @cindex calling a function
543 Defining functions is only half the battle. Functions don't do
544 anything until you @dfn{call} them, i.e., tell them to run. Calling a
545 function is also known as @dfn{invocation}.
547 The most common way of invoking a function is by evaluating a list. For
548 example, evaluating the list @code{(concat "a" "b")} calls the function
549 @code{concat}. @xref{Evaluation}, for a description of evaluation.
551 When you write a list as an expression in your program, the function
552 name is part of the program. This means that you choose which function
553 to call, and how many arguments to give it, when you write the program.
554 Usually that's just what you want. Occasionally you need to decide at
555 run time which function to call. To do that, use the functions
556 @code{funcall} and @code{apply}.
558 @defun funcall function &rest arguments
559 @code{funcall} calls @var{function} with @var{arguments}, and returns
560 whatever @var{function} returns.
562 Since @code{funcall} is a function, all of its arguments, including
563 @var{function}, are evaluated before @code{funcall} is called. This
564 means that you can use any expression to obtain the function to be
565 called. It also means that @code{funcall} does not see the expressions
566 you write for the @var{arguments}, only their values. These values are
567 @emph{not} evaluated a second time in the act of calling @var{function};
568 @code{funcall} enters the normal procedure for calling a function at the
569 place where the arguments have already been evaluated.
571 The argument @var{function} must be either a Lisp function or a
572 primitive function. Special forms and macros are not allowed, because
573 they make sense only when given the ``unevaluated'' argument
574 expressions. @code{funcall} cannot provide these because, as we saw
575 above, it never knows them in the first place.
587 (funcall f 'x 'y '(z))
592 @error{} Invalid function: #<subr and>
596 Compare these example with the examples of @code{apply}.
599 @defun apply function &rest arguments
600 @code{apply} calls @var{function} with @var{arguments}, just like
601 @code{funcall} but with one difference: the last of @var{arguments} is a
602 list of arguments to give to @var{function}, rather than a single
603 argument. We also say that this list is @dfn{appended} to the other
606 @code{apply} returns the result of calling @var{function}. As with
607 @code{funcall}, @var{function} must either be a Lisp function or a
608 primitive function; special forms and macros do not make sense in
618 @error{} Wrong type argument: listp, z
621 (apply '+ 1 2 '(3 4))
625 (apply '+ '(1 2 3 4))
630 (apply 'append '((a b c) nil (x y z) nil))
631 @result{} (a b c x y z)
635 For an interesting example of using @code{apply}, see the description of
636 @code{mapcar}, in @ref{Mapping Functions}.
640 It is common for Lisp functions to accept functions as arguments or
641 find them in data structures (especially in hook variables and property
642 lists) and call them using @code{funcall} or @code{apply}. Functions
643 that accept function arguments are often called @dfn{functionals}.
645 Sometimes, when you call such a function, it is useful to supply a
646 no-op function as the argument. Here are two different kinds of no-op
650 This function returns @var{arg} and has no side effects.
653 @defun ignore &rest args
654 This function ignores any arguments and returns @code{nil}.
657 @node Mapping Functions
658 @section Mapping Functions
659 @cindex mapping functions
661 A @dfn{mapping function} applies a given function to each element of a
662 list or other collection. Emacs Lisp has three such functions;
663 @code{mapcar} and @code{mapconcat}, which scan a list, are described
664 here. For the third mapping function, @code{mapatoms}, see
665 @ref{Creating Symbols}.
667 @defun mapcar function sequence
668 @code{mapcar} applies @var{function} to each element of @var{sequence} in
669 turn. The results are made into a @code{nil}-terminated list.
671 The argument @var{sequence} may be a list, a vector or a string. The
672 result is always a list. The length of the result is the same as the
673 length of @var{sequence}.
677 @exdent @r{For example:}
679 (mapcar 'car '((a b) (c d) (e f)))
683 (mapcar 'char-to-string "abc")
684 @result{} ("a" "b" "c")
688 ;; @r{Call each function in @code{my-hooks}.}
689 (mapcar 'funcall my-hooks)
693 (defun mapcar* (f &rest args)
694 "Apply FUNCTION to successive cars of all ARGS.
695 Return the list of results."
696 ;; @r{If no list is exhausted,}
697 (if (not (memq 'nil args))
698 ;; @r{apply function to @sc{CAR}s.}
699 (cons (apply f (mapcar 'car args))
701 ;; @r{Recurse for rest of elements.}
702 (mapcar 'cdr args)))))
706 (mapcar* 'cons '(a b c) '(1 2 3 4))
707 @result{} ((a . 1) (b . 2) (c . 3))
712 @defun mapconcat function sequence separator
713 @code{mapconcat} applies @var{function} to each element of
714 @var{sequence}: the results, which must be strings, are concatenated.
715 Between each pair of result strings, @code{mapconcat} inserts the string
716 @var{separator}. Usually @var{separator} contains a space or comma or
717 other suitable punctuation.
719 The argument @var{function} must be a function that can take one
720 argument and return a string.
724 (mapconcat 'symbol-name
725 '(The cat in the hat)
727 @result{} "The cat in the hat"
731 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
739 @node Anonymous Functions
740 @section Anonymous Functions
741 @cindex anonymous function
743 In Lisp, a function is a list that starts with @code{lambda}, a
744 byte-code function compiled from such a list, or alternatively a
745 primitive subr-object; names are ``extra''. Although usually functions
746 are defined with @code{defun} and given names at the same time, it is
747 occasionally more concise to use an explicit lambda expression---an
748 anonymous function. Such a list is valid wherever a function name is.
750 Any method of creating such a list makes a valid function. Even this:
754 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
755 @result{} (lambda (x) (+ 12 x))
760 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
761 makes it the value (@emph{not} the function definition!) of
764 Here is how we might call this function:
774 (It does @emph{not} work to write @code{(silly 1)}, because this function
775 is not the @emph{function definition} of @code{silly}. We have not given
776 @code{silly} any function definition, just a value as a variable.)
778 Most of the time, anonymous functions are constants that appear in
779 your program. For example, you might want to pass one as an argument
780 to the function @code{mapcar}, which applies any given function to each
781 element of a list. Here we pass an anonymous function that multiplies
786 (defun double-each (list)
787 (mapcar '(lambda (x) (* 2 x)) list))
788 @result{} double-each
791 (double-each '(2 11))
797 In such cases, we usually use the special form @code{function} instead
798 of simple quotation to quote the anonymous function.
800 @defspec function function-object
801 @cindex function quoting
802 This special form returns @var{function-object} without evaluating it.
803 In this, it is equivalent to @code{quote}. However, it serves as a
804 note to the Emacs Lisp compiler that @var{function-object} is intended
805 to be used only as a function, and therefore can safely be compiled.
806 Contrast this with @code{quote}, in @ref{Quoting}.
809 Using @code{function} instead of @code{quote} makes a difference
810 inside a function or macro that you are going to compile. For example:
814 (defun double-each (list)
815 (mapcar (function (lambda (x) (* 2 x))) list))
816 @result{} double-each
819 (double-each '(2 11))
825 If this definition of @code{double-each} is compiled, the anonymous
826 function is compiled as well. By contrast, in the previous definition
827 where ordinary @code{quote} is used, the argument passed to
828 @code{mapcar} is the precise list shown:
835 The Lisp compiler cannot assume this list is a function, even though it
836 looks like one, since it does not know what @code{mapcar} does with the
837 list. Perhaps @code{mapcar} will check that the @sc{car} of the third
838 element is the symbol @code{*}! The advantage of @code{function} is
839 that it tells the compiler to go ahead and compile the constant
842 We sometimes write @code{function} instead of @code{quote} when
843 quoting the name of a function, but this usage is just a sort of
847 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
850 See @code{documentation} in @ref{Accessing Documentation}, for a
851 realistic example using @code{function} and an anonymous function.
854 @section Accessing Function Cell Contents
856 The @dfn{function definition} of a symbol is the object stored in the
857 function cell of the symbol. The functions described here access, test,
858 and set the function cell of symbols.
860 @defun symbol-function symbol
861 @kindex void-function
862 This returns the object in the function cell of @var{symbol}. If the
863 symbol's function cell is void, a @code{void-function} error is
866 This function does not check that the returned object is a legitimate
871 (defun bar (n) (+ n 2))
875 (symbol-function 'bar)
876 @result{} (lambda (n) (+ n 2))
883 (symbol-function 'baz)
889 @cindex void function cell
890 If you have never given a symbol any function definition, we say that
891 that symbol's function cell is @dfn{void}. In other words, the function
892 cell does not have any Lisp object in it. If you try to call such a symbol
893 as a function, it signals a @code{void-function} error.
895 Note that void is not the same as @code{nil} or the symbol
896 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
897 and can be stored into a function cell just as any other object can be
898 (and they can be valid functions if you define them in turn with
899 @code{defun}); but @code{nil} or @code{void} is @emph{an object}. A
900 void function cell contains no object whatsoever.
902 You can test the voidness of a symbol's function definition with
903 @code{fboundp}. After you have given a symbol a function definition, you
904 can make it void once more using @code{fmakunbound}.
906 @defun fboundp symbol
907 This function returns @code{t} if the symbol has an object in its
908 function cell, @code{nil} otherwise. It does not check that the object
909 is a legitimate function.
912 @defun fmakunbound symbol
913 This function makes @var{symbol}'s function cell void, so that a
914 subsequent attempt to access this cell will cause a @code{void-function}
915 error. (See also @code{makunbound}, in @ref{Local Variables}.)
928 @error{} Symbol's function definition is void: foo
933 @defun fset symbol object
934 This function stores @var{object} in the function cell of @var{symbol}.
935 The result is @var{object}. Normally @var{object} should be a function
936 or the name of a function, but this is not checked.
938 There are three normal uses of this function:
942 Copying one symbol's function definition to another. (In other words,
943 making an alternate name for a function.)
946 Giving a symbol a function definition that is not a list and therefore
947 cannot be made with @code{defun}. @xref{Classifying Lists}, for an
948 example of this usage.
951 In constructs for defining or altering functions. If @code{defun}
952 were not a primitive, it could be written in Lisp (as a macro) using
956 Here are examples of the first two uses:
960 ;; @r{Give @code{first} the same definition @code{car} has.}
961 (fset 'first (symbol-function 'car))
962 @result{} #<subr car>
970 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
979 (symbol-function 'xfirst)
983 (symbol-function (symbol-function 'xfirst))
984 @result{} #<subr car>
988 ;; @r{Define a named keyboard macro.}
989 (fset 'kill-two-lines "\^u2\^k")
995 When writing a function that extends a previously defined function,
996 the following idiom is often used:
999 (fset 'old-foo (symbol-function 'foo))
1001 "Just like old-foo, except more so."
1009 This does not work properly if @code{foo} has been defined to autoload.
1010 In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
1011 to define @code{old-foo} by loading a file. Since this presumably
1012 defines @code{foo} rather than @code{old-foo}, it does not produce the
1013 proper results. The only way to avoid this problem is to make sure the
1014 file is loaded before moving aside the old definition of @code{foo}.
1016 See also the function @code{indirect-function} in @ref{Function
1019 @node Inline Functions
1020 @section Inline Functions
1021 @cindex inline functions
1024 You can define an @dfn{inline function} by using @code{defsubst} instead
1025 of @code{defun}. An inline function works just like an ordinary
1026 function except for one thing: when you compile a call to the function,
1027 the function's definition is open-coded into the caller.
1029 Making a function inline makes explicit calls run faster. But it also
1030 has disadvantages. For one thing, it reduces flexibility; if you change
1031 the definition of the function, calls already inlined still use the old
1032 definition until you recompile them. Since the flexibility of
1033 redefining functions is an important feature of Emacs, you should not
1034 make a function inline unless its speed is really crucial.
1036 Another disadvantage is that making a large function inline can increase
1037 the size of compiled code both in files and in memory. Since the speed
1038 advantage of inline functions is greatest for small functions, you
1039 generally should not make large functions inline.
1041 It's possible to define a macro to expand into the same code that an
1042 inline function would execute. But the macro would have a limitation:
1043 you can use it only explicitly---a macro cannot be called with
1044 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1045 convert an ordinary function into a macro. (@xref{Macros}.) To convert
1046 it into an inline function is very easy; simply replace @code{defun}
1047 with @code{defsubst}. Since each argument of an inline function is
1048 evaluated exactly once, you needn't worry about how many times the
1049 body uses the arguments, as you do for macros. (@xref{Argument
1052 Inline functions can be used and open coded later on in the same file,
1053 following the definition, just like macros.
1055 Emacs versions prior to 19 did not have inline functions.
1057 @node Related Topics
1058 @section Other Topics Related to Functions
1060 Here is a table of several functions that do things related to
1061 function calling and function definitions. They are documented
1062 elsewhere, but we provide cross references here.
1066 See @ref{Calling Functions}.
1071 @item call-interactively
1072 See @ref{Interactive Call}.
1075 See @ref{Interactive Call}.
1078 See @ref{Accessing Documentation}.
1084 See @ref{Calling Functions}.
1087 See @ref{Calling Functions}.
1089 @item indirect-function
1090 See @ref{Function Indirection}.
1093 See @ref{Using Interactive}.
1096 See @ref{Interactive Call}.
1099 See @ref{Creating Symbols}.
1102 See @ref{Mapping Functions}.
1105 See @ref{Mapping Functions}.
1108 See @ref{Key Lookup}.