2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 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 we implement a function as a primitive is because it
58 is 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. Macros enable Lisp programmers to do the sorts of
83 things that special forms can do. @xref{Macros}, for how to define and
88 A @dfn{command} is an object that @code{command-execute} can invoke; it
89 is a possible definition for a key sequence. Some functions are
90 commands; a function written in Lisp is a command if it contains an
91 interactive declaration (@pxref{Defining Commands}). Such a function
92 can be called from Lisp expressions like other functions; in this case,
93 the fact that the function is a command makes no difference.
95 Keyboard macros (strings and vectors) are commands also, even though
96 they are not functions. A symbol is a command if its function
97 definition is a command; such symbols can be invoked with @kbd{M-x}.
98 The symbol is a function as well if the definition is a function.
99 @xref{Command Overview}.
101 @item keystroke command
102 @cindex keystroke command
103 A @dfn{keystroke command} is a command that is bound to a key sequence
104 (typically one to three keystrokes). The distinction is made here
105 merely to avoid confusion with the meaning of ``command'' in non-Emacs
106 editors; for Lisp programs, the distinction is normally unimportant.
108 @item byte-code function
109 A @dfn{byte-code function} is a function that has been compiled by the
110 byte compiler. @xref{Byte-Code Type}.
114 @defun functionp object
115 This function returns @code{t} if @var{object} is any kind of function;
116 that is, anything that could be called as a function.
120 This function returns @code{t} if @var{object} is a built-in function
121 (i.e., a Lisp primitive).
125 (subrp 'message) ; @r{@code{message} is a symbol,}
126 @result{} nil ; @r{not a subr object.}
129 (subrp (symbol-function 'message))
135 @defun byte-code-function-p object
136 This function returns @code{t} if @var{object} is a byte-code
137 function. For example:
141 (byte-code-function-p (symbol-function 'next-line))
147 @node Lambda Expressions
148 @section Lambda Expressions
149 @cindex lambda expression
151 A function written in Lisp is a list that looks like this:
154 (lambda (@var{arg-variables}@dots{})
155 @r{[}@var{documentation-string}@r{]}
156 @r{[}@var{interactive-declaration}@r{]}
157 @var{body-forms}@dots{})
161 Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
162 actually is valid as an expression---it evaluates to itself. In some
163 other Lisp dialects, a lambda expression is not a valid expression at
164 all. In either case, its main use is not to be evaluated as an
165 expression, but to be called as a function.
168 * Lambda Components:: The parts of a lambda expression.
169 * Simple Lambda:: A simple example.
170 * Argument List:: Details and special features of argument lists.
171 * Function Documentation:: How to put documentation in a function.
174 @node Lambda Components
175 @subsection Components of a Lambda Expression
179 A function written in Lisp (a ``lambda expression'') is a list that
183 (lambda (@var{arg-variables}@dots{})
184 [@var{documentation-string}]
185 [@var{interactive-declaration}]
186 @var{body-forms}@dots{})
191 The first element of a lambda expression is always the symbol
192 @code{lambda}. This indicates that the list represents a function. The
193 reason functions are defined to start with @code{lambda} is so that
194 other lists, intended for other uses, will not accidentally be valid as
197 The second element is a list of symbols---the argument variable names.
198 This is called the @dfn{lambda list}. When a Lisp function is called,
199 the argument values are matched up against the variables in the lambda
200 list, which are given local bindings with the values provided.
201 @xref{Local Variables}.
203 The documentation string is a Lisp string object placed within the
204 function definition to describe the function for the Emacs help
205 facilities. @xref{Function Documentation}.
207 The interactive declaration is a list of the form @code{(interactive
208 @var{code-string})}. This declares how to provide arguments if the
209 function is used interactively. Functions with this declaration are called
210 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
211 Functions not intended to be called in this way should not have interactive
212 declarations. @xref{Defining Commands}, for how to write an interactive
215 @cindex body of function
216 The rest of the elements are the @dfn{body} of the function: the Lisp
217 code to do the work of the function (or, as a Lisp programmer would say,
218 ``a list of Lisp forms to evaluate''). The value returned by the
219 function is the value returned by the last element of the body.
222 @subsection A Simple Lambda-Expression Example
224 Consider for example the following function:
227 (lambda (a b c) (+ a b c))
231 We can call this function by writing it as the @sc{car} of an
232 expression, like this:
236 ((lambda (a b c) (+ a b c))
242 This call evaluates the body of the lambda expression with the variable
243 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
244 Evaluation of the body adds these three numbers, producing the result 6;
245 therefore, this call to the function returns the value 6.
247 Note that the arguments can be the results of other function calls, as in
252 ((lambda (a b c) (+ a b c))
258 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
259 4)} from left to right. Then it applies the lambda expression to the
260 argument values 1, 6 and 1 to produce the value 8.
262 It is not often useful to write a lambda expression as the @sc{car} of
263 a form in this way. You can get the same result, of making local
264 variables and giving them values, using the special form @code{let}
265 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
266 In practice, lambda expressions are either stored as the function
267 definitions of symbols, to produce named functions, or passed as
268 arguments to other functions (@pxref{Anonymous Functions}).
270 However, calls to explicit lambda expressions were very useful in the
271 old days of Lisp, before the special form @code{let} was invented. At
272 that time, they were the only way to bind and initialize local
276 @subsection Other Features of Argument Lists
277 @kindex wrong-number-of-arguments
278 @cindex argument binding
279 @cindex binding arguments
281 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
282 specifies three argument variables, so it must be called with three
283 arguments: if you try to call it with only two arguments or four
284 arguments, you get a @code{wrong-number-of-arguments} error.
286 It is often convenient to write a function that allows certain
287 arguments to be omitted. For example, the function @code{substring}
288 accepts three arguments---a string, the start index and the end
289 index---but the third argument defaults to the @var{length} of the
290 string if you omit it. It is also convenient for certain functions to
291 accept an indefinite number of arguments, as the functions @code{list}
294 @cindex optional arguments
295 @cindex rest arguments
298 To specify optional arguments that may be omitted when a function
299 is called, simply include the keyword @code{&optional} before the optional
300 arguments. To specify a list of zero or more extra arguments, include the
301 keyword @code{&rest} before one final argument.
303 Thus, the complete syntax for an argument list is as follows:
307 (@var{required-vars}@dots{}
308 @r{[}&optional @var{optional-vars}@dots{}@r{]}
309 @r{[}&rest @var{rest-var}@r{]})
314 The square brackets indicate that the @code{&optional} and @code{&rest}
315 clauses, and the variables that follow them, are optional.
317 A call to the function requires one actual argument for each of the
318 @var{required-vars}. There may be actual arguments for zero or more of
319 the @var{optional-vars}, and there cannot be any actual arguments beyond
320 that unless the lambda list uses @code{&rest}. In that case, there may
321 be any number of extra actual arguments.
323 If actual arguments for the optional and rest variables are omitted,
324 then they always default to @code{nil}. There is no way for the
325 function to distinguish between an explicit argument of @code{nil} and
326 an omitted argument. However, the body of the function is free to
327 consider @code{nil} an abbreviation for some other meaningful value.
328 This is what @code{substring} does; @code{nil} as the third argument to
329 @code{substring} means to use the length of the string supplied.
331 @cindex CL note---default optional arg
333 @b{Common Lisp note:} Common Lisp allows the function to specify what
334 default value to use when an optional argument is omitted; Emacs Lisp
335 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
336 variables that tell you whether an argument was explicitly passed.
339 For example, an argument list that looks like this:
342 (a b &optional c d &rest e)
346 binds @code{a} and @code{b} to the first two actual arguments, which are
347 required. If one or two more arguments are provided, @code{c} and
348 @code{d} are bound to them respectively; any arguments after the first
349 four are collected into a list and @code{e} is bound to that list. If
350 there are only two arguments, @code{c} is @code{nil}; if two or three
351 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
354 There is no way to have required arguments following optional
355 ones---it would not make sense. To see why this must be so, suppose
356 that @code{c} in the example were optional and @code{d} were required.
357 Suppose three actual arguments are given; which variable would the third
358 argument be for? Similarly, it makes no sense to have any more
359 arguments (either required or optional) after a @code{&rest} argument.
361 Here are some examples of argument lists and proper calls:
364 ((lambda (n) (1+ n)) ; @r{One required:}
365 1) ; @r{requires exactly one argument.}
367 ((lambda (n &optional n1) ; @r{One required and one optional:}
368 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
371 ((lambda (n &rest ns) ; @r{One required and one rest:}
372 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
377 @node Function Documentation
378 @subsection Documentation Strings of Functions
379 @cindex documentation of function
381 A lambda expression may optionally have a @dfn{documentation string} just
382 after the lambda list. This string does not affect execution of the
383 function; it is a kind of comment, but a systematized comment which
384 actually appears inside the Lisp world and can be used by the Emacs help
385 facilities. @xref{Documentation}, for how the @var{documentation-string} is
388 It is a good idea to provide documentation strings for all the
389 functions in your program, even those that are only called from within
390 your program. Documentation strings are like comments, except that they
391 are easier to access.
393 The first line of the documentation string should stand on its own,
394 because @code{apropos} displays just this first line. It should consist
395 of one or two complete sentences that summarize the function's purpose.
397 The start of the documentation string is usually indented in the source file,
398 but since these spaces come before the starting double-quote, they are not part of
399 the string. Some people make a practice of indenting any additional
400 lines of the string so that the text lines up in the program source.
401 @emph{This is a mistake.} The indentation of the following lines is
402 inside the string; what looks nice in the source code will look ugly
403 when displayed by the help commands.
405 You may wonder how the documentation string could be optional, since
406 there are required components of the function that follow it (the body).
407 Since evaluation of a string returns that string, without any side effects,
408 it has no effect if it is not the last form in the body. Thus, in
409 practice, there is no confusion between the first form of the body and the
410 documentation string; if the only body form is a string then it serves both
411 as the return value and as the documentation.
414 @section Naming a Function
415 @cindex function definition
416 @cindex named function
417 @cindex function name
419 In most computer languages, every function has a name; the idea of a
420 function without a name is nonsensical. In Lisp, a function in the
421 strictest sense has no name. It is simply a list whose first element is
422 @code{lambda}, or a primitive subr-object.
424 However, a symbol can serve as the name of a function. This happens
425 when you put the function in the symbol's @dfn{function cell}
426 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
427 callable function, equivalent to the list or subr-object that its
428 function cell refers to. The contents of the function cell are also
429 called the symbol's @dfn{function definition}. The procedure of using a
430 symbol's function definition in place of the symbol is called
431 @dfn{symbol function indirection}; see @ref{Function Indirection}.
433 In practice, nearly all functions are given names in this way and
434 referred to through their names. For example, the symbol @code{car} works
435 as a function and does what it does because the primitive subr-object
436 @code{#<subr car>} is stored in its function cell.
438 We give functions names because it is convenient to refer to them by
439 their names in Lisp expressions. For primitive subr-objects such as
440 @code{#<subr car>}, names are the only way you can refer to them: there
441 is no read syntax for such objects. For functions written in Lisp, the
442 name is more convenient to use in a call than an explicit lambda
443 expression. Also, a function with a name can refer to itself---it can
444 be recursive. Writing the function's name in its own definition is much
445 more convenient than making the function definition point to itself
446 (something that is not impossible but that has various disadvantages in
449 We often identify functions with the symbols used to name them. For
450 example, we often speak of ``the function @code{car}'', not
451 distinguishing between the symbol @code{car} and the primitive
452 subr-object that is its function definition. For most purposes, there
453 is no need to distinguish.
455 Even so, keep in mind that a function need not have a unique name. While
456 a given function object @emph{usually} appears in the function cell of only
457 one symbol, this is just a matter of convenience. It is easy to store
458 it in several symbols using @code{fset}; then each of the symbols is
459 equally well a name for the same function.
461 A symbol used as a function name may also be used as a variable;
462 these two uses of a symbol are independent and do not conflict.
463 (Some Lisp dialects, such as Scheme, do not distinguish between a
464 symbol's value and its function definition; a symbol's value as a variable
465 is also its function definition.)
467 @node Defining Functions
468 @section Defining Functions
469 @cindex defining a function
471 We usually give a name to a function when it is first created. This
472 is called @dfn{defining a function}, and it is done with the
473 @code{defun} special form.
475 @defspec defun name argument-list body-forms
476 @code{defun} is the usual way to define new Lisp functions. It
477 defines the symbol @var{name} as a function that looks like this:
480 (lambda @var{argument-list} . @var{body-forms})
483 @code{defun} stores this lambda expression in the function cell of
484 @var{name}. It returns the value @var{name}, but usually we ignore this
487 As described previously (@pxref{Lambda Expressions}),
488 @var{argument-list} is a list of argument names and may include the
489 keywords @code{&optional} and @code{&rest}. Also, the first two of the
490 @var{body-forms} may be a documentation string and an interactive
493 There is no conflict if the same symbol @var{name} is also used as a
494 variable, since the symbol's value cell is independent of the function
495 cell. @xref{Symbol Components}.
497 Here are some examples:
510 (defun bar (a &optional b &rest c)
516 @result{} (1 2 (3 4 5))
520 @result{} (1 nil nil)
524 @error{} Wrong number of arguments.
528 (defun capitalize-backwards ()
529 "Upcase the last letter of a word."
535 @result{} capitalize-backwards
539 Be careful not to redefine existing functions unintentionally.
540 @code{defun} redefines even primitive functions such as @code{car}
541 without any hesitation or notification. Redefining a function already
542 defined is often done deliberately, and there is no way to distinguish
543 deliberate redefinition from unintentional redefinition.
546 @defun defalias name definition
547 This special form defines the symbol @var{name} as a function, with
548 definition @var{definition} (which can be any valid Lisp function).
550 The proper place to use @code{defalias} is where a specific function
551 name is being defined---especially where that name appears explicitly in
552 the source file being loaded. This is because @code{defalias} records
553 which file defined the function, just like @code{defun}
556 By contrast, in programs that manipulate function definitions for other
557 purposes, it is better to use @code{fset}, which does not keep such
561 See also @code{defsubst}, which defines a function like @code{defun}
562 and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
564 @node Calling Functions
565 @section Calling Functions
566 @cindex function invocation
567 @cindex calling a function
569 Defining functions is only half the battle. Functions don't do
570 anything until you @dfn{call} them, i.e., tell them to run. Calling a
571 function is also known as @dfn{invocation}.
573 The most common way of invoking a function is by evaluating a list.
574 For example, evaluating the list @code{(concat "a" "b")} calls the
575 function @code{concat} with arguments @code{"a"} and @code{"b"}.
576 @xref{Evaluation}, for a description of evaluation.
578 When you write a list as an expression in your program, the function
579 name it calls is written in your program. This means that you choose
580 which function to call, and how many arguments to give it, when you
581 write the program. Usually that's just what you want. Occasionally you
582 need to compute at run time which function to call. To do that, use the
583 functions @code{funcall} and @code{apply}.
585 @defun funcall function &rest arguments
586 @code{funcall} calls @var{function} with @var{arguments}, and returns
587 whatever @var{function} returns.
589 Since @code{funcall} is a function, all of its arguments, including
590 @var{function}, are evaluated before @code{funcall} is called. This
591 means that you can use any expression to obtain the function to be
592 called. It also means that @code{funcall} does not see the expressions
593 you write for the @var{arguments}, only their values. These values are
594 @emph{not} evaluated a second time in the act of calling @var{function};
595 @code{funcall} enters the normal procedure for calling a function at the
596 place where the arguments have already been evaluated.
598 The argument @var{function} must be either a Lisp function or a
599 primitive function. Special forms and macros are not allowed, because
600 they make sense only when given the ``unevaluated'' argument
601 expressions. @code{funcall} cannot provide these because, as we saw
602 above, it never knows them in the first place.
614 (funcall f 'x 'y '(z))
619 @error{} Invalid function: #<subr and>
623 Compare these example with the examples of @code{apply}.
626 @defun apply function &rest arguments
627 @code{apply} calls @var{function} with @var{arguments}, just like
628 @code{funcall} but with one difference: the last of @var{arguments} is a
629 list of objects, which are passed to @var{function} as separate
630 arguments, rather than a single list. We say that @code{apply}
631 @dfn{spreads} this list so that each individual element becomes an
634 @code{apply} returns the result of calling @var{function}. As with
635 @code{funcall}, @var{function} must either be a Lisp function or a
636 primitive function; special forms and macros do not make sense in
646 @error{} Wrong type argument: listp, z
649 (apply '+ 1 2 '(3 4))
653 (apply '+ '(1 2 3 4))
658 (apply 'append '((a b c) nil (x y z) nil))
659 @result{} (a b c x y z)
663 For an interesting example of using @code{apply}, see the description of
664 @code{mapcar}, in @ref{Mapping Functions}.
668 It is common for Lisp functions to accept functions as arguments or
669 find them in data structures (especially in hook variables and property
670 lists) and call them using @code{funcall} or @code{apply}. Functions
671 that accept function arguments are often called @dfn{functionals}.
673 Sometimes, when you call a functional, it is useful to supply a no-op
674 function as the argument. Here are two different kinds of no-op
678 This function returns @var{arg} and has no side effects.
681 @defun ignore &rest args
682 This function ignores any arguments and returns @code{nil}.
685 @node Mapping Functions
686 @section Mapping Functions
687 @cindex mapping functions
689 A @dfn{mapping function} applies a given function to each element of a
690 list or other collection. Emacs Lisp has several such functions;
691 @code{mapcar} and @code{mapconcat}, which scan a list, are described
692 here. @xref{Creating Symbols}, for the function @code{mapatoms} which
693 maps over the symbols in an obarray. @xref{Char-Tables}, for the
694 function @code{map-char-table}, which maps over the elements in a
697 @defun mapcar function sequence
698 @code{mapcar} applies @var{function} to each element of @var{sequence}
699 in turn, and returns a list of the results.
701 The argument @var{sequence} may be a list, a vector, or a string. The
702 result is always a list. The length of the result is the same as the
703 length of @var{sequence}.
707 @exdent @r{For example:}
709 (mapcar 'car '((a b) (c d) (e f)))
713 (mapcar 'char-to-string "abc")
714 @result{} ("a" "b" "c")
718 ;; @r{Call each function in @code{my-hooks}.}
719 (mapcar 'funcall my-hooks)
723 (defun mapcar* (f &rest args)
724 "Apply FUNCTION to successive cars of all ARGS.
725 Return the list of results."
726 ;; @r{If no list is exhausted,}
727 (if (not (memq 'nil args))
728 ;; @r{apply function to @sc{CAR}s.}
729 (cons (apply f (mapcar 'car args))
731 ;; @r{Recurse for rest of elements.}
732 (mapcar 'cdr args)))))
736 (mapcar* 'cons '(a b c) '(1 2 3 4))
737 @result{} ((a . 1) (b . 2) (c . 3))
742 @defun mapconcat function sequence separator
743 @code{mapconcat} applies @var{function} to each element of
744 @var{sequence}: the results, which must be strings, are concatenated.
745 Between each pair of result strings, @code{mapconcat} inserts the string
746 @var{separator}. Usually @var{separator} contains a space or comma or
747 other suitable punctuation.
749 The argument @var{function} must be a function that can take one
750 argument and return a string.
754 (mapconcat 'symbol-name
755 '(The cat in the hat)
757 @result{} "The cat in the hat"
761 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
769 @node Anonymous Functions
770 @section Anonymous Functions
771 @cindex anonymous function
773 In Lisp, a function is a list that starts with @code{lambda}, a
774 byte-code function compiled from such a list, or alternatively a
775 primitive subr-object; names are ``extra''. Although usually functions
776 are defined with @code{defun} and given names at the same time, it is
777 occasionally more concise to use an explicit lambda expression---an
778 anonymous function. Such a list is valid wherever a function name is.
780 Any method of creating such a list makes a valid function. Even this:
784 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
785 @result{} (lambda (x) (+ 12 x))
790 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
791 makes it the value (@emph{not} the function definition!) of
794 Here is how we might call this function:
804 (It does @emph{not} work to write @code{(silly 1)}, because this function
805 is not the @emph{function definition} of @code{silly}. We have not given
806 @code{silly} any function definition, just a value as a variable.)
808 Most of the time, anonymous functions are constants that appear in
809 your program. For example, you might want to pass one as an argument to
810 the function @code{mapcar}, which applies any given function to each
813 Here we define a function @code{change-property} which
814 uses a function as its third argument:
818 (defun change-property (symbol prop function)
819 (let ((value (get symbol prop)))
820 (put symbol prop (funcall function value))))
825 Here we define a function that uses @code{change-property},
826 passing a function that doubles its argument:
830 (defun double-property (symbol prop)
831 (change-property symbol prop '(lambda (x) (* 2 x))))
836 In such cases, we usually use the special form @code{function} instead
837 of simple quotation to quote the anonymous function, like this:
841 (defun double-property (symbol prop)
842 (change-property symbol prop (function (lambda (x) (* 2 x)))))
846 Using @code{function} instead of @code{quote} makes a difference if you
847 compile the function @code{double-property}. For example, if you
848 compile the second definition of @code{double-property}, the anonymous
849 function is compiled as well. By contrast, if you compile the first
850 definition which uses ordinary @code{quote}, the argument passed to
851 @code{change-property} is the precise list shown:
858 The Lisp compiler cannot assume this list is a function, even though it
859 looks like one, since it does not know what @code{change-property} will
860 do with the list. Perhaps will check whether the @sc{car} of the third
861 element is the symbol @code{*}! Using @code{function} tells the
862 compiler it is safe to go ahead and compile the constant function.
864 We sometimes write @code{function} instead of @code{quote} when
865 quoting the name of a function, but this usage is just a sort of
869 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
872 @defspec function function-object
873 @cindex function quoting
874 This special form returns @var{function-object} without evaluating it.
875 In this, it is equivalent to @code{quote}. However, it serves as a
876 note to the Emacs Lisp compiler that @var{function-object} is intended
877 to be used only as a function, and therefore can safely be compiled.
878 Contrast this with @code{quote}, in @ref{Quoting}.
881 See @code{documentation} in @ref{Accessing Documentation}, for a
882 realistic example using @code{function} and an anonymous function.
885 @section Accessing Function Cell Contents
887 The @dfn{function definition} of a symbol is the object stored in the
888 function cell of the symbol. The functions described here access, test,
889 and set the function cell of symbols.
891 See also the function @code{indirect-function} in @ref{Function
894 @defun symbol-function symbol
895 @kindex void-function
896 This returns the object in the function cell of @var{symbol}. If the
897 symbol's function cell is void, a @code{void-function} error is
900 This function does not check that the returned object is a legitimate
905 (defun bar (n) (+ n 2))
909 (symbol-function 'bar)
910 @result{} (lambda (n) (+ n 2))
917 (symbol-function 'baz)
923 @cindex void function cell
924 If you have never given a symbol any function definition, we say that
925 that symbol's function cell is @dfn{void}. In other words, the function
926 cell does not have any Lisp object in it. If you try to call such a symbol
927 as a function, it signals a @code{void-function} error.
929 Note that void is not the same as @code{nil} or the symbol
930 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
931 and can be stored into a function cell just as any other object can be
932 (and they can be valid functions if you define them in turn with
933 @code{defun}). A void function cell contains no object whatsoever.
935 You can test the voidness of a symbol's function definition with
936 @code{fboundp}. After you have given a symbol a function definition, you
937 can make it void once more using @code{fmakunbound}.
939 @defun fboundp symbol
940 This function returns @code{t} if the symbol has an object in its
941 function cell, @code{nil} otherwise. It does not check that the object
942 is a legitimate function.
945 @defun fmakunbound symbol
946 This function makes @var{symbol}'s function cell void, so that a
947 subsequent attempt to access this cell will cause a @code{void-function}
948 error. (See also @code{makunbound}, in @ref{Local Variables}.)
965 @error{} Symbol's function definition is void: foo
970 @defun fset symbol definition
971 This function stores @var{definition} in the function cell of
972 @var{symbol}. The result is @var{definition}. Normally
973 @var{definition} should be a function or the name of a function, but
974 this is not checked. The argument @var{symbol} is an ordinary evaluated
977 There are three normal uses of this function:
981 Copying one symbol's function definition to another. (In other words,
982 making an alternate name for a function.)
985 Giving a symbol a function definition that is not a list and therefore
986 cannot be made with @code{defun}. For example, you can use @code{fset}
987 to give a symbol @code{s1} a function definition which is another symbol
988 @code{s2}; then @code{s1} serves as an alias for whatever definition
989 @code{s2} presently has.
992 In constructs for defining or altering functions. If @code{defun}
993 were not a primitive, it could be written in Lisp (as a macro) using
997 Here are examples of the first two uses:
1001 ;; @r{Give @code{first} the same definition @code{car} has.}
1002 (fset 'first (symbol-function 'car))
1003 @result{} #<subr car>
1011 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
1020 (symbol-function 'xfirst)
1024 (symbol-function (symbol-function 'xfirst))
1025 @result{} #<subr car>
1029 ;; @r{Define a named keyboard macro.}
1030 (fset 'kill-two-lines "\^u2\^k")
1035 See also the related function @code{defalias}, in @ref{Defining
1039 When writing a function that extends a previously defined function,
1040 the following idiom is sometimes used:
1043 (fset 'old-foo (symbol-function 'foo))
1045 "Just like old-foo, except more so."
1053 This does not work properly if @code{foo} has been defined to autoload.
1054 In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
1055 to define @code{old-foo} by loading a file. Since this presumably
1056 defines @code{foo} rather than @code{old-foo}, it does not produce the
1057 proper results. The only way to avoid this problem is to make sure the
1058 file is loaded before moving aside the old definition of @code{foo}.
1060 But it is unmodular and unclean, in any case, for a Lisp file to
1061 redefine a function defined elsewhere.
1063 @node Inline Functions
1064 @section Inline Functions
1065 @cindex inline functions
1068 You can define an @dfn{inline function} by using @code{defsubst} instead
1069 of @code{defun}. An inline function works just like an ordinary
1070 function except for one thing: when you compile a call to the function,
1071 the function's definition is open-coded into the caller.
1073 Making a function inline makes explicit calls run faster. But it also
1074 has disadvantages. For one thing, it reduces flexibility; if you change
1075 the definition of the function, calls already inlined still use the old
1076 definition until you recompile them. Since the flexibility of
1077 redefining functions is an important feature of Emacs, you should not
1078 make a function inline unless its speed is really crucial.
1080 Another disadvantage is that making a large function inline can increase
1081 the size of compiled code both in files and in memory. Since the speed
1082 advantage of inline functions is greatest for small functions, you
1083 generally should not make large functions inline.
1085 It's possible to define a macro to expand into the same code that an
1086 inline function would execute. But the macro would have a limitation:
1087 you can use it only explicitly---a macro cannot be called with
1088 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1089 convert an ordinary function into a macro. (@xref{Macros}.) To convert
1090 it into an inline function is very easy; simply replace @code{defun}
1091 with @code{defsubst}. Since each argument of an inline function is
1092 evaluated exactly once, you needn't worry about how many times the
1093 body uses the arguments, as you do for macros. (@xref{Argument
1096 Inline functions can be used and open-coded later on in the same file,
1097 following the definition, just like macros.
1099 @c Emacs versions prior to 19 did not have inline functions.
1101 @node Related Topics
1102 @section Other Topics Related to Functions
1104 Here is a table of several functions that do things related to
1105 function calling and function definitions. They are documented
1106 elsewhere, but we provide cross references here.
1110 See @ref{Calling Functions}.
1115 @item call-interactively
1116 See @ref{Interactive Call}.
1119 See @ref{Interactive Call}.
1122 See @ref{Accessing Documentation}.
1128 See @ref{Calling Functions}.
1131 See @ref{Calling Functions}.
1133 @item indirect-function
1134 See @ref{Function Indirection}.
1137 See @ref{Using Interactive}.
1140 See @ref{Interactive Call}.
1143 See @ref{Creating Symbols}.
1146 See @ref{Mapping Functions}.
1149 See @ref{Mapping Functions}.
1152 See @ref{Key Lookup}.