2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/functions.info
8 @node Functions and Commands, Macros, Variables, Top
9 @chapter Functions and Commands
11 A Lisp program is composed mainly of Lisp functions. This chapter
12 explains what functions are, how they accept arguments, and how to
16 * What Is a Function:: Lisp functions vs. primitives; terminology.
17 * Lambda Expressions:: How functions are expressed as Lisp objects.
18 * Function Names:: A symbol can serve as the name of a function.
19 * Defining Functions:: Lisp expressions for defining functions.
20 * Calling Functions:: How to use an existing function.
21 * Mapping Functions:: Applying a function to each element of a list, etc.
22 * Anonymous Functions:: Lambda expressions are functions with no names.
23 * Function Cells:: Accessing or setting the function definition
25 * Inline Functions:: Defining functions that the compiler will open code.
26 * Related Topics:: Cross-references to specific Lisp primitives
27 that have a special bearing on how functions work.
31 @node What Is a Function
32 @section What Is a Function?
34 In a general sense, a function is a rule for carrying on a computation
35 given several values called @dfn{arguments}. The result of the
36 computation is called the value of the function. The computation can
37 also have side effects: lasting changes in the values of variables or
38 the contents of data structures.
40 Here are important terms for functions in SXEmacs Lisp and for other
41 function-like objects.
46 In SXEmacs Lisp, a @dfn{function} is anything that can be applied to
47 arguments in a Lisp program. In some cases, we use it more
48 specifically to mean a function written in Lisp. Special forms and
49 macros are not functions.
54 A @dfn{command} is a possible definition for a key sequence---we count
55 mouse events and menu accesses as key sequences for this purpose. More
56 formally, within SXEmacs lisp, a command is something that
57 @code{command-execute} can invoke.
59 Some functions are commands; a function written in Lisp is a command if
60 it contains an interactive declaration. A trivial interactive
61 declaration is a line @code{(interactive)} immediately after the
62 documentation string. For more complex examples, with prompting and
63 completion, see @xref{Defining Commands}. Such a function can be called
64 from Lisp expressions like other functions; in this case, the fact that
65 the function is a command makes no difference.
67 Keyboard macros (strings and vectors) are commands also, even though
68 they are not functions. A symbol is a command if its function
69 definition is a command; such symbols can be invoked with @kbd{M-x}.
70 The symbol is a function as well if the definition is a function.
72 In the case where you want to call a command in reaction to a
73 user-generated event, you'll need to bind it to that event. For how to
74 do this, see @xref{Key Binding Commands}.
75 @xref{Command Overview}.
77 @item keystroke command
78 @cindex keystroke command
79 A @dfn{keystroke command} is a command that is bound to a key sequence
80 (typically one to three keystrokes). The distinction is made here
81 merely to avoid confusion with the meaning of ``command'' in non-Emacs
82 editors; for Lisp programs, the distinction is normally unimportant.
87 @cindex built-in function
88 A @dfn{primitive} is a function callable from Lisp that is written in C,
89 such as @code{car} or @code{append}. These functions are also called
90 @dfn{built-in} functions or @dfn{subrs}. (Special forms are also
91 considered primitives.)
93 Usually the reason that a function is a primitives is because it is
94 fundamental, because it provides a low-level interface to operating
95 system services, or because it needs to run fast. Primitives can be
96 modified or added only by changing the C sources and recompiling the
97 editor. See @ref{Writing Lisp Primitives,,, internals, SXEmacs
100 @item lambda expression
101 A @dfn{lambda expression} is a function written in Lisp.
102 These are described in the following section.
104 @xref{Lambda Expressions}.
108 A @dfn{special form} is a primitive that is like a function but does not
109 evaluate all of its arguments in the usual way. It may evaluate only
110 some of the arguments, or may evaluate them in an unusual order, or
111 several times. Many special forms are described in @ref{Control
116 A @dfn{macro} is a construct defined in Lisp by the programmer. It
117 differs from a function in that it translates a Lisp expression that you
118 write into an equivalent expression to be evaluated instead of the
119 original expression. Macros enable Lisp programmers to do the sorts of
120 things that special forms can do. @xref{Macros}, for how to define and
123 @item compiled function
124 A @dfn{compiled function} is a function that has been compiled by the
125 byte compiler. @xref{Compiled-Function Type}.
129 This function returns @code{t} if @var{object} is a built-in function
130 (i.e., a Lisp primitive).
134 (subrp 'message) ; @r{@code{message} is a symbol,}
135 @result{} nil ; @r{not a subr object.}
138 (subrp (symbol-function 'message))
144 @defun compiled-function-p object
145 This function returns @code{t} if @var{object} is a compiled
146 function. For example:
150 (compiled-function-p (symbol-function 'next-line))
157 @node Lambda Expressions
158 @section Lambda Expressions
159 @cindex lambda expression
161 A function written in Lisp is a list that looks like this:
164 (lambda (@var{arg-variables}@dots{})
165 @r{[}@var{documentation-string}@r{]}
166 @r{[}@var{interactive-declaration}@r{]}
167 @var{body-forms}@dots{})
171 Such a list is called a @dfn{lambda expression}. In SXEmacs Lisp, it
172 actually is valid as an expression---it evaluates to itself. In some
173 other Lisp dialects, a lambda expression is not a valid expression at
174 all. In either case, its main use is not to be evaluated as an
175 expression, but to be called as a function.
178 * Lambda Components:: The parts of a lambda expression.
179 * Simple Lambda:: A simple example.
180 * Argument List:: Details and special features of argument lists.
181 * Function Documentation:: How to put documentation in a function.
185 @node Lambda Components
186 @subsection Components of a Lambda Expression
190 A function written in Lisp (a ``lambda expression'') is a list that
194 (lambda (@var{arg-variables}@dots{})
195 [@var{documentation-string}]
196 [@var{interactive-declaration}]
197 @var{body-forms}@dots{})
202 The first element of a lambda expression is always the symbol
203 @code{lambda}. This indicates that the list represents a function. The
204 reason functions are defined to start with @code{lambda} is so that
205 other lists, intended for other uses, will not accidentally be valid as
208 The second element is a list of symbols--the argument variable names.
209 This is called the @dfn{lambda list}. When a Lisp function is called,
210 the argument values are matched up against the variables in the lambda
211 list, which are given local bindings with the values provided.
212 @xref{Local Variables}.
214 The documentation string is a Lisp string object placed within the
215 function definition to describe the function for the SXEmacs help
216 facilities. @xref{Function Documentation}.
218 The interactive declaration is a list of the form @code{(interactive
219 @var{code-string})}. This declares how to provide arguments if the
220 function is used interactively. Functions with this declaration are called
221 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
222 Functions not intended to be called in this way should not have interactive
223 declarations. @xref{Defining Commands}, for how to write an interactive
226 @cindex body of function
227 The rest of the elements are the @dfn{body} of the function: the Lisp
228 code to do the work of the function (or, as a Lisp programmer would say,
229 ``a list of Lisp forms to evaluate''). The value returned by the
230 function is the value returned by the last element of the body.
234 @subsection A Simple Lambda-Expression Example
236 Consider for example the following function:
239 (lambda (a b c) (+ a b c))
243 We can call this function by writing it as the @sc{car} of an
244 expression, like this:
248 ((lambda (a b c) (+ a b c))
254 This call evaluates the body of the lambda expression with the variable
255 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
256 Evaluation of the body adds these three numbers, producing the result 6;
257 therefore, this call to the function returns the value 6.
259 Note that the arguments can be the results of other function calls, as in
264 ((lambda (a b c) (+ a b c))
270 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
271 4)} from left to right. Then it applies the lambda expression to the
272 argument values 1, 6 and 1 to produce the value 8.
274 It is not often useful to write a lambda expression as the @sc{car} of
275 a form in this way. You can get the same result, of making local
276 variables and giving them values, using the special form @code{let}
277 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
278 In practice, lambda expressions are either stored as the function
279 definitions of symbols, to produce named functions, or passed as
280 arguments to other functions (@pxref{Anonymous Functions}).
282 However, calls to explicit lambda expressions were very useful in the
283 old days of Lisp, before the special form @code{let} was invented. At
284 that time, they were the only way to bind and initialize local
289 @subsection Advanced Features of Argument Lists
290 @kindex wrong-number-of-arguments
291 @cindex argument binding
292 @cindex binding arguments
294 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
295 specifies three argument variables, so it must be called with three
296 arguments: if you try to call it with only two arguments or four
297 arguments, you get a @code{wrong-number-of-arguments} error.
299 It is often convenient to write a function that allows certain
300 arguments to be omitted. For example, the function @code{substring}
301 accepts three arguments---a string, the start index and the end
302 index---but the third argument defaults to the @var{length} of the
303 string if you omit it. It is also convenient for certain functions to
304 accept an indefinite number of arguments, as the functions @code{list}
307 @cindex optional arguments
308 @cindex rest arguments
311 To specify optional arguments that may be omitted when a function
312 is called, simply include the keyword @code{&optional} before the optional
313 arguments. To specify a list of zero or more extra arguments, include the
314 keyword @code{&rest} before one final argument.
316 Thus, the complete syntax for an argument list is as follows:
320 (@var{required-vars}@dots{}
321 @r{[}&optional @var{optional-vars}@dots{}@r{]}
322 @r{[}&rest @var{rest-var}@r{]})
327 The square brackets indicate that the @code{&optional} and @code{&rest}
328 clauses, and the variables that follow them, are optional.
330 A call to the function requires one actual argument for each of the
331 @var{required-vars}. There may be actual arguments for zero or more of
332 the @var{optional-vars}, and there cannot be any actual arguments beyond
333 that unless the lambda list uses @code{&rest}. In that case, there may
334 be any number of extra actual arguments.
336 If actual arguments for the optional and rest variables are omitted,
337 then they always default to @code{nil}. There is no way for the
338 function to distinguish between an explicit argument of @code{nil} and
339 an omitted argument. However, the body of the function is free to
340 consider @code{nil} an abbreviation for some other meaningful value.
341 This is what @code{substring} does; @code{nil} as the third argument to
342 @code{substring} means to use the length of the string supplied.
344 @cindex CL note---default optional arg
346 @b{Common Lisp note:} Common Lisp allows the function to specify what
347 default value to use when an optional argument is omitted; SXEmacs Lisp
348 always uses @code{nil}.
351 For example, an argument list that looks like this:
354 (a b &optional c d &rest e)
358 binds @code{a} and @code{b} to the first two actual arguments, which are
359 required. If one or two more arguments are provided, @code{c} and
360 @code{d} are bound to them respectively; any arguments after the first
361 four are collected into a list and @code{e} is bound to that list. If
362 there are only two arguments, @code{c} is @code{nil}; if two or three
363 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
366 There is no way to have required arguments following optional
367 ones---it would not make sense. To see why this must be so, suppose
368 that @code{c} in the example were optional and @code{d} were required.
369 Suppose three actual arguments are given; which variable would the third
370 argument be for? Similarly, it makes no sense to have any more
371 arguments (either required or optional) after a @code{&rest} argument.
373 Here are some examples of argument lists and proper calls:
376 ((lambda (n) (1+ n)) ; @r{One required:}
377 1) ; @r{requires exactly one argument.}
379 ((lambda (n &optional n1) ; @r{One required and one optional:}
380 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
383 ((lambda (n &rest ns) ; @r{One required and one rest:}
384 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
390 @node Function Documentation
391 @subsection Documentation Strings of Functions
392 @cindex documentation of function
394 A lambda expression may optionally have a @dfn{documentation string} just
395 after the lambda list. This string does not affect execution of the
396 function; it is a kind of comment, but a systematized comment which
397 actually appears inside the Lisp world and can be used by the SXEmacs help
398 facilities. @xref{Documentation}, for how the @var{documentation-string} is
401 It is a good idea to provide documentation strings for all the
402 functions in your program, even those that are only called from within
403 your program. Documentation strings are like comments, except that they
404 are easier to access.
406 The first line of the documentation string should stand on its own,
407 because @code{apropos} displays just this first line. It should consist
408 of one or two complete sentences that summarize the function's purpose.
410 The start of the documentation string is usually indented in the source file,
411 but since these spaces come before the starting double-quote, they are not part of
412 the string. Some people make a practice of indenting any additional
413 lines of the string so that the text lines up in the program source.
414 @emph{This is a mistake.} The indentation of the following lines is
415 inside the string; what looks nice in the source code will look ugly
416 when displayed by the help commands.
418 You may wonder how the documentation string could be optional, since
419 there are required components of the function that follow it (the body).
420 Since evaluation of a string returns that string, without any side effects,
421 it has no effect if it is not the last form in the body. Thus, in
422 practice, there is no confusion between the first form of the body and the
423 documentation string; if the only body form is a string then it serves both
424 as the return value and as the documentation.
428 @section Naming a Function
429 @cindex function definition
430 @cindex named function
431 @cindex function name
433 In most computer languages, every function has a name; the idea of a
434 function without a name is nonsensical. In Lisp, a function in the
435 strictest sense has no name. It is simply a list whose first element is
436 @code{lambda}, or a primitive subr-object.
438 However, a symbol can serve as the name of a function. This happens
439 when you put the function in the symbol's @dfn{function cell}
440 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
441 callable function, equivalent to the list or subr-object that its
442 function cell refers to. The contents of the function cell are also
443 called the symbol's @dfn{function definition}. The procedure of using a
444 symbol's function definition in place of the symbol is called
445 @dfn{symbol function indirection}; see @ref{Function Indirection}.
447 In practice, nearly all functions are given names in this way and
448 referred to through their names. For example, the symbol @code{car} works
449 as a function and does what it does because the primitive subr-object
450 @code{#<subr car>} is stored in its function cell.
452 We give functions names because it is convenient to refer to them by
453 their names in Lisp expressions. For primitive subr-objects such as
454 @code{#<subr car>}, names are the only way you can refer to them: there
455 is no read syntax for such objects. For functions written in Lisp, the
456 name is more convenient to use in a call than an explicit lambda
457 expression. Also, a function with a name can refer to itself---it can
458 be recursive. Writing the function's name in its own definition is much
459 more convenient than making the function definition point to itself
460 (something that is not impossible but that has various disadvantages in
463 We often identify functions with the symbols used to name them. For
464 example, we often speak of ``the function @code{car}'', not
465 distinguishing between the symbol @code{car} and the primitive
466 subr-object that is its function definition. For most purposes, there
467 is no need to distinguish.
469 Even so, keep in mind that a function need not have a unique name. While
470 a given function object @emph{usually} appears in the function cell of only
471 one symbol, this is just a matter of convenience. It is easy to store
472 it in several symbols using @code{fset}; then each of the symbols is
473 equally well a name for the same function.
475 A symbol used as a function name may also be used as a variable;
476 these two uses of a symbol are independent and do not conflict.
479 @node Defining Functions
480 @section Defining Functions
481 @cindex defining a function
483 We usually give a name to a function when it is first created. This
484 is called @dfn{defining a function}, and it is done with the
485 @code{defun} special form.
487 @defspec defun name argument-list body-forms
488 @code{defun} is the usual way to define new Lisp functions. It
489 defines the symbol @var{name} as a function that looks like this:
492 (lambda @var{argument-list} . @var{body-forms})
495 @code{defun} stores this lambda expression in the function cell of
496 @var{name}. It returns the value @var{name}, but usually we ignore this
499 As described previously (@pxref{Lambda Expressions}),
500 @var{argument-list} is a list of argument names and may include the
501 keywords @code{&optional} and @code{&rest}. Also, the first two forms
502 in @var{body-forms} may be a documentation string and an interactive
505 There is no conflict if the same symbol @var{name} is also used as a
506 variable, since the symbol's value cell is independent of the function
507 cell. @xref{Symbol Components}.
509 Here are some examples:
522 (defun bar (a &optional b &rest c)
528 @result{} (1 2 (3 4 5))
532 @result{} (1 nil nil)
536 @error{} Wrong number of arguments.
540 (defun capitalize-backwards ()
541 "Upcase the last letter of a word."
547 @result{} capitalize-backwards
551 Be careful not to redefine existing functions unintentionally.
552 @code{defun} redefines even primitive functions such as @code{car}
553 without any hesitation or notification. Redefining a function already
554 defined is often done deliberately, and there is no way to distinguish
555 deliberate redefinition from unintentional redefinition.
558 @defun define-function name definition
559 @defunx defalias name definition
560 These equivalent special forms define the symbol @var{name} as a
561 function, with definition @var{definition} (which can be any valid Lisp
564 The proper place to use @code{define-function} or @code{defalias} is
565 where a specific function name is being defined---especially where that
566 name appears explicitly in the source file being loaded. This is
567 because @code{define-function} and @code{defalias} record which file
568 defined the function, just like @code{defun}.
571 By contrast, in programs that manipulate function definitions for other
572 purposes, it is better to use @code{fset}, which does not keep such
576 See also @code{defsubst}, which defines a function like @code{defun}
577 and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
580 @node Calling Functions
581 @section Calling Functions
582 @cindex function invocation
583 @cindex calling a function
585 Defining functions is only half the battle. Functions don't do
586 anything until you @dfn{call} them, i.e., tell them to run. Calling a
587 function is also known as @dfn{invocation}.
589 The most common way of invoking a function is by evaluating a list.
590 For example, evaluating the list @code{(concat "a" "b")} calls the
591 function @code{concat} with arguments @code{"a"} and @code{"b"}.
592 @xref{Evaluation}, for a description of evaluation.
594 When you write a list as an expression in your program, the function
595 name is part of the program. This means that you choose which function
596 to call, and how many arguments to give it, when you write the program.
597 Usually that's just what you want. Occasionally you need to decide at
598 run time which function to call. To do that, use the functions
599 @code{funcall} and @code{apply}.
601 @defun funcall function &rest arguments
602 @code{funcall} calls @var{function} with @var{arguments}, and returns
603 whatever @var{function} returns.
605 Since @code{funcall} is a function, all of its arguments, including
606 @var{function}, are evaluated before @code{funcall} is called. This
607 means that you can use any expression to obtain the function to be
608 called. It also means that @code{funcall} does not see the expressions
609 you write for the @var{arguments}, only their values. These values are
610 @emph{not} evaluated a second time in the act of calling @var{function};
611 @code{funcall} enters the normal procedure for calling a function at the
612 place where the arguments have already been evaluated.
614 The argument @var{function} must be either a Lisp function or a
615 primitive function. Special forms and macros are not allowed, because
616 they make sense only when given the ``unevaluated'' argument
617 expressions. @code{funcall} cannot provide these because, as we saw
618 above, it never knows them in the first place.
630 (funcall f 'x 'y '(z))
635 @error{} Invalid function: #<subr and>
639 Compare these example with the examples of @code{apply}.
642 @defun apply function &rest arguments
643 @code{apply} calls @var{function} with @var{arguments}, just like
644 @code{funcall} but with one difference: the last of @var{arguments} is a
645 list of arguments to give to @var{function}, rather than a single
646 argument. We also say that @code{apply} @dfn{spreads} this list so that
647 each individual element becomes an argument.
649 @code{apply} returns the result of calling @var{function}. As with
650 @code{funcall}, @var{function} must either be a Lisp function or a
651 primitive function; special forms and macros do not make sense in
661 @error{} Wrong type argument: listp, z
664 (apply '+ 1 2 '(3 4))
668 (apply '+ '(1 2 3 4))
673 (apply 'append '((a b c) nil (x y z) nil))
674 @result{} (a b c x y z)
678 For an interesting example of using @code{apply}, see the description of
679 @code{mapcar}, in @ref{Mapping Functions}.
683 It is common for Lisp functions to accept functions as arguments or
684 find them in data structures (especially in hook variables and property
685 lists) and call them using @code{funcall} or @code{apply}. Functions
686 that accept function arguments are often called @dfn{functionals}.
688 Sometimes, when you call a functional, it is useful to supply a no-op
689 function as the argument. Here are two different kinds of no-op
693 This function returns @var{arg} and has no side effects.
696 @deffn Command ignore &rest args
697 This function ignores any arguments and returns @code{nil}.
701 @node Mapping Functions
702 @section Mapping Functions
703 @cindex mapping functions
705 A @dfn{mapping function} applies a given function to each element of a
706 list or other collection. SXEmacs Lisp has several such functions;
707 @code{mapcar} and @code{mapconcat}, which scan a list, are described
708 here. @xref{Creating Symbols}, for the function @code{mapatoms} which
709 maps over the symbols in an obarray.
711 Mapping functions should never modify the sequence being mapped over.
712 The results are unpredictable. If in-place modification is explicitly
713 what you want use the special function @code{mapc-inplace}.
715 @defun mapcar function sequence
716 @code{mapcar} applies @var{function} to each element of @var{sequence}
717 in turn, and returns a list of the results.
719 The argument @var{sequence} can be any kind of sequence; that is, a
720 list, a dllist, a vector, a bit vector, or a string. The result is
721 always a list. The length of the result is the same as the length of
726 @exdent @r{For example:}
728 (mapcar 'car '((a b) (c d) (e f)))
732 (mapcar 'char-to-string "abc")
733 @result{} ("a" "b" "c")
737 ;; @r{Call each function in @code{my-hooks}.}
738 (mapcar 'funcall my-hooks)
742 (defun mapcar* (f &rest args)
743 "Apply FUNCTION to successive cars of all ARGS.
744 Return the list of results."
745 ;; @r{If no list is exhausted,}
746 (if (not (memq 'nil args))
747 ;; @r{apply function to @sc{car}s.}
748 (cons (apply f (mapcar 'car args))
750 ;; @r{Recurse for rest of elements.}
751 (mapcar 'cdr args)))))
755 (mapcar* 'cons '(a b c) '(1 2 3 4))
756 @result{} ((a . 1) (b . 2) (c . 3))
761 @defun mapconcat function sequence separator
762 @code{mapconcat} applies @var{function} to each element of
763 @var{sequence}: the results, which must be strings, are concatenated.
764 Between each pair of result strings, @code{mapconcat} inserts the string
765 @var{separator}. Usually @var{separator} contains a space or comma or
766 other suitable punctuation.
768 The argument @var{function} must be a function that can take one
769 argument and return a string. The argument @var{sequence} can be any
770 kind of sequence; that is, a list, a vector, a bit vector, or a string.
774 (mapconcat 'symbol-name
775 '(The cat in the hat)
777 @result{} "The cat in the hat"
781 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
789 In case the result is of minor importance, or the mapping function
790 works by side-effect somehow you can prevent elisp from gathering the
791 results. This will save you some time and memory.
793 @defun mapc function sequence
794 Apply @var{function} to each element of @var{sequence}.
795 @var{sequence} may be a list, a dllist, a vector, a bit vector, or a
796 string. This function is like @code{mapcar} but does not accumulate
797 the results, which is more efficient if you do not use the results.
799 The difference between @code{mapc} and @code{mapc-internal} is that
800 @code{mapc} supports all the spiffy Common Lisp arguments. You should
801 normally use @code{mapc}.
805 (let ((all-prime-p t) ;; @r{all numbers are assumed to be prime initially}
806 (list-of-numbers '(2 3 5 7 11 13)))
808 (when (and all-prime-p (not (primep x))
809 (setq all-prime-p nil))))
816 (let ((all-prime-p t) ;; @r{all numbers are assumed to be prime initially}
817 (list-of-numbers '(2 4 6 8 10 13)))
819 (when (and all-prime-p (not (primep x))
820 (setq all-prime-p nil))))
828 However, if you plan to use @code{mapc} with mapping functions which
829 modify the current element of the sequence being mapped over by
830 side-effect, don't do it! The safer way is to use
831 @code{mapc-inplace} which is even faster and less memory intensive
834 @defun mapc-inplace function sequence
835 Apply @var{function} to each element of @var{sequence} and replace the
836 element with the result.
837 Return the (destructively) modified sequence.
839 At the moment, @var{sequence} can be a list, a dllist, a vector,
840 a bit-vector, or a string.
842 Containers with type restrictions -- strings or bit-vectors here --
843 cannot handle all results of @var{function}. In case of bit-vectors,
844 if the function yields @code{nil} or @code{0} the current bit is set
845 to @code{0}, if the function yields anything else, the bit is set to
847 Similarly in the string case any non-char result of @var{function}
848 sets the currently processed character to @code{^@@} (octal value:
853 ;; @r{replace the elements of a list by the next-prime number}
854 (let ((list-of-numbers '(22 59 104 193)))
855 (mapc-inplace #'next-prime list-of-numbers)
857 @result{} (23 61 107 197)
861 ;; @r{replace a vector of lisp objects by their hash-value}
862 (let ((vec-of-objects [22 foobar "string" nil]))
863 (mapc-inplace #'sxhash vec-of-objects)
865 @result{} [45 912820644 212821792 912999036]
872 @node Anonymous Functions
873 @section Anonymous Functions
874 @cindex anonymous function
876 In Lisp, a function is a list that starts with @code{lambda}, a
877 byte-code function compiled from such a list, or alternatively a
878 primitive subr-object; names are ``extra''. Although usually functions
879 are defined with @code{defun} and given names at the same time, it is
880 occasionally more concise to use an explicit lambda expression---an
881 anonymous function. Such a list is valid wherever a function name is.
883 Any method of creating such a list makes a valid function. Even this:
887 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
888 @result{} (lambda (x) (+ 12 x))
893 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
894 makes it the value (@emph{not} the function definition!) of
897 Here is how we might call this function:
907 (It does @emph{not} work to write @code{(silly 1)}, because this function
908 is not the @emph{function definition} of @code{silly}. We have not given
909 @code{silly} any function definition, just a value as a variable.)
911 Most of the time, anonymous functions are constants that appear in
912 your program. For example, you might want to pass one as an argument
913 to the function @code{mapcar}, which applies any given function to each
914 element of a list. Here we pass an anonymous function that multiplies
919 (defun double-each (list)
920 (mapcar '(lambda (x) (* 2 x)) list))
921 @result{} double-each
924 (double-each '(2 11))
930 In such cases, we usually use the special form @code{function} instead
931 of simple quotation to quote the anonymous function. @xref{Quoting
934 Using @code{function} instead of @code{quote} makes a difference
935 inside a function or macro that you are going to compile. For example:
939 (defun double-each (list)
940 (mapcar (function (lambda (x) (* 2 x))) list))
941 @result{} double-each
944 (double-each '(2 11))
950 If this definition of @code{double-each} is compiled, the anonymous
951 function is compiled as well. By contrast, in the previous definition
952 where ordinary @code{quote} is used, the argument passed to
953 @code{mapcar} is the precise list shown:
960 The Lisp compiler cannot assume this list is a function, even though it
961 looks like one, since it does not know what @code{mapcar} does with the
962 list. Perhaps @code{mapcar} will check that the @sc{car} of the third
963 element is the symbol @code{*}! The advantage of @code{function} is
964 that it tells the compiler to go ahead and compile the constant
967 We sometimes write @code{function} instead of @code{quote} when
968 quoting the name of a function, but this usage is just a sort of
972 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
975 See @code{documentation} in @ref{Accessing Documentation}, for a
976 realistic example using @code{function} and an anonymous function.
980 @section Accessing Function Cell Contents
982 The @dfn{function definition} of a symbol is the object stored in the
983 function cell of the symbol. The functions described here access, test,
984 and set the function cell of symbols.
986 See also the function @code{indirect-function} in @ref{Function
989 @defun symbol-function symbol
990 @kindex void-function
991 This returns the object in the function cell of @var{symbol}. If the
992 symbol's function cell is void, a @code{void-function} error is
995 This function does not check that the returned object is a legitimate
1000 (defun bar (n) (+ n 2))
1004 (symbol-function 'bar)
1005 @result{} (lambda (n) (+ n 2))
1012 (symbol-function 'baz)
1018 @cindex void function cell
1019 If you have never given a symbol any function definition, we say that
1020 that symbol's function cell is @dfn{void}. In other words, the function
1021 cell does not have any Lisp object in it. If you try to call such a symbol
1022 as a function, it signals a @code{void-function} error.
1024 Note that void is not the same as @code{nil} or the symbol
1025 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1026 and can be stored into a function cell just as any other object can be
1027 (and they can be valid functions if you define them in turn with
1028 @code{defun}). A void function cell contains no object whatsoever.
1030 You can test the voidness of a symbol's function definition with
1031 @code{fboundp}. After you have given a symbol a function definition, you
1032 can make it void once more using @code{fmakunbound}.
1034 @defun fboundp symbol
1035 This function returns @code{t} if @var{symbol} has an object in its
1036 function cell, @code{nil} otherwise. It does not check that the object
1037 is a legitimate function.
1040 @defun fmakunbound symbol
1041 This function makes @var{symbol}'s function cell void, so that a
1042 subsequent attempt to access this cell will cause a @code{void-function}
1043 error. (See also @code{makunbound}, in @ref{Local Variables}.)
1060 @error{} Symbol's function definition is void: foo
1065 @defun fset symbol object
1066 This function stores @var{object} in the function cell of @var{symbol}.
1067 The result is @var{object}. Normally @var{object} should be a function
1068 or the name of a function, but this is not checked.
1070 There are three normal uses of this function:
1074 Copying one symbol's function definition to another. (In other words,
1075 making an alternate name for a function.)
1078 Giving a symbol a function definition that is not a list and therefore
1079 cannot be made with @code{defun}. For example, you can use @code{fset}
1080 to give a symbol @var{symbol1} a function definition which is another symbol
1081 @var{symbol2}; then @var{symbol1} serves as an alias for whatever definition
1082 @var{symbol2} presently has.
1085 In constructs for defining or altering functions. If @code{defun}
1086 were not a primitive, it could be written in Lisp (as a macro) using
1090 Here are examples of the first two uses:
1094 ;; @r{Give @code{first} the same definition @code{car} has.}
1095 (fset 'first (symbol-function 'car))
1096 @result{} #<subr car>
1104 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
1113 (symbol-function 'xfirst)
1117 (symbol-function (symbol-function 'xfirst))
1118 @result{} #<subr car>
1122 ;; @r{Define a named keyboard macro.}
1123 (fset 'kill-two-lines "\^u2\^k")
1128 See also the related functions @code{define-function} and
1129 @code{defalias}, in @ref{Defining Functions}.
1132 When writing a function that extends a previously defined function,
1133 the following idiom is sometimes used:
1136 (fset 'old-foo (symbol-function 'foo))
1138 "Just like old-foo, except more so."
1146 This does not work properly if @code{foo} has been defined to autoload.
1147 In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
1148 to define @code{old-foo} by loading a file. Since this presumably
1149 defines @code{foo} rather than @code{old-foo}, it does not produce the
1150 proper results. The only way to avoid this problem is to make sure the
1151 file is loaded before moving aside the old definition of @code{foo}.
1153 But it is unmodular and unclean, in any case, for a Lisp file to
1154 redefine a function defined elsewhere.
1157 @node Inline Functions
1158 @section Inline Functions
1159 @cindex inline functions
1162 You can define an @dfn{inline function} by using @code{defsubst} instead
1163 of @code{defun}. An inline function works just like an ordinary
1164 function except for one thing: when you compile a call to the function,
1165 the function's definition is open-coded into the caller.
1167 Making a function inline makes explicit calls run faster. But it also
1168 has disadvantages. For one thing, it reduces flexibility; if you change
1169 the definition of the function, calls already inlined still use the old
1170 definition until you recompile them. Since the flexibility of
1171 redefining functions is an important feature of SXEmacs, you should not
1172 make a function inline unless its speed is really crucial.
1174 Another disadvantage is that making a large function inline can increase
1175 the size of compiled code both in files and in memory. Since the speed
1176 advantage of inline functions is greatest for small functions, you
1177 generally should not make large functions inline.
1179 It's possible to define a macro to expand into the same code that an
1180 inline function would execute. But the macro would have a limitation:
1181 you can use it only explicitly---a macro cannot be called with
1182 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1183 convert an ordinary function into a macro. (@xref{Macros}.) To convert
1184 it into an inline function is very easy; simply replace @code{defun}
1185 with @code{defsubst}. Since each argument of an inline function is
1186 evaluated exactly once, you needn't worry about how many times the
1187 body uses the arguments, as you do for macros. (@xref{Argument
1190 Inline functions can be used and open-coded later on in the same file,
1191 following the definition, just like macros.
1193 @c Emacs versions prior to 19 did not have inline functions.
1196 @node Related Topics
1197 @section Other Topics Related to Functions
1199 Here is a table of several functions that do things related to
1200 function calling and function definitions. They are documented
1201 elsewhere, but we provide cross references here.
1205 See @ref{Calling Functions}.
1210 @item call-interactively
1211 See @ref{Interactive Call}.
1214 See @ref{Interactive Call}.
1217 See @ref{Accessing Documentation}.
1223 See @ref{Calling Functions}.
1226 See @ref{Calling Functions}.
1228 @item indirect-function
1229 See @ref{Function Indirection}.
1232 See @ref{Using Interactive}.
1235 See @ref{Interactive Call}.
1238 See @ref{Creating Symbols}.
1241 See @ref{Mapping Functions}.
1244 See @ref{Mapping Functions}.
1247 See @ref{Key Lookup}.