@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/functions@node Functions, Macros, Variables, Top@chapter Functions A Lisp program is composed mainly of Lisp functions. This chapterexplains what functions are, how they accept arguments, and how todefine them.@menu* What Is a Function:: Lisp functions vs. primitives; terminology.* Lambda Expressions:: How functions are expressed as Lisp objects.* Function Names:: A symbol can serve as the name of a function.* Defining Functions:: Lisp expressions for defining functions.* Calling Functions:: How to use an existing function.* Mapping Functions:: Applying a function to each element of a list, etc.* Anonymous Functions:: Lambda expressions are functions with no names.* Function Cells:: Accessing or setting the function definition of a symbol.* Obsolete Functions:: Declaring functions obsolete.* Inline Functions:: Defining functions that the compiler will open code.* Function Safety:: Determining whether a function is safe to call.* Related Topics:: Cross-references to specific Lisp primitives that have a special bearing on how functions work.@end menu@node What Is a Function@section What Is a Function? In a general sense, a function is a rule for carrying on a computationgiven several values called @dfn{arguments}. The result of thecomputation is called the value of the function. The computation canalso have side effects: lasting changes in the values of variables orthe contents of data structures. Here are important terms for functions in Emacs Lisp and for otherfunction-like objects.@table @dfn@item function@cindex functionIn Emacs Lisp, a @dfn{function} is anything that can be applied toarguments in a Lisp program. In some cases, we use it morespecifically to mean a function written in Lisp. Special forms andmacros are not functions.@item primitive@cindex primitive@cindex subr@cindex built-in functionA @dfn{primitive} is a function callable from Lisp that is written in C,such as @code{car} or @code{append}. These functions are also called@dfn{built-in functions}, or @dfn{subrs}. (Special forms are alsoconsidered primitives.)Usually the reason we implement a function as a primitive is eitherbecause it is fundamental, because it provides a low-level interfaceto operating system services, or because it needs to run fast.Primitives can be modified or added only by changing the C sources andrecompiling the editor. See @ref{Writing Emacs Primitives}.@item lambda expressionA @dfn{lambda expression} is a function written in Lisp.These are described in the following section.@ifnottex@xref{Lambda Expressions}.@end ifnottex@item special formA @dfn{special form} is a primitive that is like a function but does notevaluate all of its arguments in the usual way. It may evaluate onlysome of the arguments, or may evaluate them in an unusual order, orseveral times. Many special forms are described in @ref{ControlStructures}.@item macro@cindex macroA @dfn{macro} is a construct defined in Lisp by the programmer. Itdiffers from a function in that it translates a Lisp expression that youwrite into an equivalent expression to be evaluated instead of theoriginal expression. Macros enable Lisp programmers to do the sorts ofthings that special forms can do. @xref{Macros}, for how to define anduse macros.@item command@cindex commandA @dfn{command} is an object that @code{command-execute} can invoke; itis a possible definition for a key sequence. Some functions arecommands; a function written in Lisp is a command if it contains aninteractive declaration (@pxref{Defining Commands}). Such a functioncan be called from Lisp expressions like other functions; in this case,the fact that the function is a command makes no difference.Keyboard macros (strings and vectors) are commands also, even thoughthey are not functions. A symbol is a command if its functiondefinition is a command; such symbols can be invoked with @kbd{M-x}.The symbol is a function as well if the definition is a function.@xref{Interactive Call}.@item keystroke command@cindex keystroke commandA @dfn{keystroke command} is a command that is bound to a key sequence(typically one to three keystrokes). The distinction is made heremerely to avoid confusion with the meaning of ``command'' in non-Emacseditors; for Lisp programs, the distinction is normally unimportant.@item byte-code functionA @dfn{byte-code function} is a function that has been compiled by thebyte compiler. @xref{Byte-Code Type}.@end table@defun functionp objectThis function returns @code{t} if @var{object} is any kind offunction, or a special form, or, recursively, a symbol whose functiondefinition is a function or special form. (This does not includemacros.)@end defunUnlike @code{functionp}, the next three functions do @emph{not}treat a symbol as its function definition.@defun subrp objectThis function returns @code{t} if @var{object} is a built-in function(i.e., a Lisp primitive).@example@group(subrp 'message) ; @r{@code{message} is a symbol,} @result{} nil ; @r{not a subr object.}@end group@group(subrp (symbol-function 'message)) @result{} t@end group@end example@end defun@defun byte-code-function-p objectThis function returns @code{t} if @var{object} is a byte-codefunction. For example:@example@group(byte-code-function-p (symbol-function 'next-line)) @result{} t@end group@end example@end defun@defun subr-arity subrThis function provides information about the argument list of aprimitive, @var{subr}. The returned value is a pair@code{(@var{min} . @var{max})}. @var{min} is the minimum number ofargs. @var{max} is the maximum number or the symbol @code{many}, for afunction with @code{&rest} arguments, or the symbol @code{unevalled} if@var{subr} is a special form.@end defun@node Lambda Expressions@section Lambda Expressions@cindex lambda expression A function written in Lisp is a list that looks like this:@example(lambda (@var{arg-variables}@dots{}) @r{[}@var{documentation-string}@r{]} @r{[}@var{interactive-declaration}@r{]} @var{body-forms}@dots{})@end example@noindentSuch a list is called a @dfn{lambda expression}. In Emacs Lisp, itactually is valid as an expression---it evaluates to itself. In someother Lisp dialects, a lambda expression is not a valid expression atall. In either case, its main use is not to be evaluated as anexpression, but to be called as a function.@menu* Lambda Components:: The parts of a lambda expression.* Simple Lambda:: A simple example.* Argument List:: Details and special features of argument lists.* Function Documentation:: How to put documentation in a function.@end menu@node Lambda Components@subsection Components of a Lambda Expression@ifnottex A function written in Lisp (a ``lambda expression'') is a list thatlooks like this:@example(lambda (@var{arg-variables}@dots{}) [@var{documentation-string}] [@var{interactive-declaration}] @var{body-forms}@dots{})@end example@end ifnottex@cindex lambda list The first element of a lambda expression is always the symbol@code{lambda}. This indicates that the list represents a function. Thereason functions are defined to start with @code{lambda} is so thatother lists, intended for other uses, will not accidentally be valid asfunctions. The second element is a list of symbols---the argument variable names.This is called the @dfn{lambda list}. When a Lisp function is called,the argument values are matched up against the variables in the lambdalist, which are given local bindings with the values provided.@xref{Local Variables}. The documentation string is a Lisp string object placed within thefunction definition to describe the function for the Emacs helpfacilities. @xref{Function Documentation}. The interactive declaration is a list of the form @code{(interactive@var{code-string})}. This declares how to provide arguments if thefunction is used interactively. Functions with this declaration are called@dfn{commands}; they can be called using @kbd{M-x} or bound to a key.Functions not intended to be called in this way should not have interactivedeclarations. @xref{Defining Commands}, for how to write an interactivedeclaration.@cindex body of function The rest of the elements are the @dfn{body} of the function: the Lispcode to do the work of the function (or, as a Lisp programmer would say,``a list of Lisp forms to evaluate''). The value returned by thefunction is the value returned by the last element of the body.@node Simple Lambda@subsection A Simple Lambda-Expression Example Consider for example the following function:@example(lambda (a b c) (+ a b c))@end example@noindentWe can call this function by writing it as the @sc{car} of anexpression, like this:@example@group((lambda (a b c) (+ a b c)) 1 2 3)@end group@end example@noindentThis call evaluates the body of the lambda expression with the variable@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.Evaluation of the body adds these three numbers, producing the result 6;therefore, this call to the function returns the value 6. Note that the arguments can be the results of other function calls, as inthis example:@example@group((lambda (a b c) (+ a b c)) 1 (* 2 3) (- 5 4))@end group@end example@noindentThis evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 54)} from left to right. Then it applies the lambda expression to theargument values 1, 6 and 1 to produce the value 8. It is not often useful to write a lambda expression as the @sc{car} ofa form in this way. You can get the same result, of making localvariables and giving them values, using the special form @code{let}(@pxref{Local Variables}). And @code{let} is clearer and easier to use.In practice, lambda expressions are either stored as the functiondefinitions of symbols, to produce named functions, or passed asarguments to other functions (@pxref{Anonymous Functions}). However, calls to explicit lambda expressions were very useful in theold days of Lisp, before the special form @code{let} was invented. Atthat time, they were the only way to bind and initialize localvariables.@node Argument List@subsection Other Features of Argument Lists@kindex wrong-number-of-arguments@cindex argument binding@cindex binding arguments Our simple sample function, @code{(lambda (a b c) (+ a b c))},specifies three argument variables, so it must be called with threearguments: if you try to call it with only two arguments or fourarguments, you get a @code{wrong-number-of-arguments} error. It is often convenient to write a function that allows certainarguments to be omitted. For example, the function @code{substring}accepts three arguments---a string, the start index and the endindex---but the third argument defaults to the @var{length} of thestring if you omit it. It is also convenient for certain functions toaccept an indefinite number of arguments, as the functions @code{list}and @code{+} do.@cindex optional arguments@cindex rest arguments@kindex &optional@kindex &rest To specify optional arguments that may be omitted when a functionis called, simply include the keyword @code{&optional} before the optionalarguments. To specify a list of zero or more extra arguments, include thekeyword @code{&rest} before one final argument. Thus, the complete syntax for an argument list is as follows:@example@group(@var{required-vars}@dots{} @r{[}&optional @var{optional-vars}@dots{}@r{]} @r{[}&rest @var{rest-var}@r{]})@end group@end example@noindentThe square brackets indicate that the @code{&optional} and @code{&rest}clauses, and the variables that follow them, are optional. A call to the function requires one actual argument for each of the@var{required-vars}. There may be actual arguments for zero or more ofthe @var{optional-vars}, and there cannot be any actual arguments beyondthat unless the lambda list uses @code{&rest}. In that case, there maybe any number of extra actual arguments. If actual arguments for the optional and rest variables are omitted,then they always default to @code{nil}. There is no way for thefunction to distinguish between an explicit argument of @code{nil} andan omitted argument. However, the body of the function is free toconsider @code{nil} an abbreviation for some other meaningful value.This is what @code{substring} does; @code{nil} as the third argument to@code{substring} means to use the length of the string supplied.@cindex CL note---default optional arg@quotation@b{Common Lisp note:} Common Lisp allows the function to specify whatdefault value to use when an optional argument is omitted; Emacs Lispalways uses @code{nil}. Emacs Lisp does not support ``supplied-p''variables that tell you whether an argument was explicitly passed.@end quotation For example, an argument list that looks like this:@example(a b &optional c d &rest e)@end example@noindentbinds @code{a} and @code{b} to the first two actual arguments, which arerequired. If one or two more arguments are provided, @code{c} and@code{d} are bound to them respectively; any arguments after the firstfour are collected into a list and @code{e} is bound to that list. Ifthere are only two arguments, @code{c} is @code{nil}; if two or threearguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}is @code{nil}. There is no way to have required arguments following optionalones---it would not make sense. To see why this must be so, supposethat @code{c} in the example were optional and @code{d} were required.Suppose three actual arguments are given; which variable would thethird argument be for? Would it be used for the @var{c}, or for@var{d}? One can argue for both possibilities. Similarly, it makesno sense to have any more arguments (either required or optional)after a @code{&rest} argument. Here are some examples of argument lists and proper calls:@smallexample((lambda (n) (1+ n)) ; @r{One required:} 1) ; @r{requires exactly one argument.} @result{} 2((lambda (n &optional n1) ; @r{One required and one optional:} (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} 1 2) @result{} 3((lambda (n &rest ns) ; @r{One required and one rest:} (+ n (apply '+ ns))) ; @r{1 or more arguments.} 1 2 3 4 5) @result{} 15@end smallexample@node Function Documentation@subsection Documentation Strings of Functions@cindex documentation of function A lambda expression may optionally have a @dfn{documentation string} justafter the lambda list. This string does not affect execution of thefunction; it is a kind of comment, but a systematized comment whichactually appears inside the Lisp world and can be used by the Emacs helpfacilities. @xref{Documentation}, for how the @var{documentation-string} isaccessed. It is a good idea to provide documentation strings for all thefunctions in your program, even those that are called only from withinyour program. Documentation strings are like comments, except that theyare easier to access. The first line of the documentation string should stand on its own,because @code{apropos} displays just this first line. It should consistof one or two complete sentences that summarize the function's purpose. The start of the documentation string is usually indented in thesource file, but since these spaces come before the startingdouble-quote, they are not part of the string. Some people make apractice of indenting any additional lines of the string so that thetext lines up in the program source. @emph{That is a mistake.} Theindentation of the following lines is inside the string; what looksnice in the source code will look ugly when displayed by the helpcommands. You may wonder how the documentation string could be optional, sincethere are required components of the function that follow it (the body).Since evaluation of a string returns that string, without any side effects,it has no effect if it is not the last form in the body. Thus, inpractice, there is no confusion between the first form of the body and thedocumentation string; if the only body form is a string then it serves bothas the return value and as the documentation. The last line of the documentation string can specify callingconventions different from the actual function arguments. Writetext like this:@example\(fn @var{arglist})@end example@noindentfollowing a blank line, at the beginning of the line, with no newlinefollowing it inside the documentation string. (The @samp{\} is usedto avoid confusing the Emacs motion commands.) The calling conventionspecified in this way appears in help messages in place of the onederived from the actual arguments of the function. This feature is particularly useful for macro definitions, since thearguments written in a macro definition often do not correspond to theway users think of the parts of the macro call.@node Function Names@section Naming a Function@cindex function definition@cindex named function@cindex function name In most computer languages, every function has a name; the idea of afunction without a name is nonsensical. In Lisp, a function in thestrictest sense has no name. It is simply a list whose first element is@code{lambda}, a byte-code function object, or a primitive subr-object. However, a symbol can serve as the name of a function. This happenswhen you put the function in the symbol's @dfn{function cell}(@pxref{Symbol Components}). Then the symbol itself becomes a valid,callable function, equivalent to the list or subr-object that itsfunction cell refers to. The contents of the function cell are alsocalled the symbol's @dfn{function definition}. The procedure of using asymbol's function definition in place of the symbol is called@dfn{symbol function indirection}; see @ref{Function Indirection}. In practice, nearly all functions are given names in this way andreferred to through their names. For example, the symbol @code{car} worksas a function and does what it does because the primitive subr-object@code{#<subr car>} is stored in its function cell. We give functions names because it is convenient to refer to them bytheir names in Lisp expressions. For primitive subr-objects such as@code{#<subr car>}, names are the only way you can refer to them: thereis no read syntax for such objects. For functions written in Lisp, thename is more convenient to use in a call than an explicit lambdaexpression. Also, a function with a name can refer to itself---it canbe recursive. Writing the function's name in its own definition is muchmore convenient than making the function definition point to itself(something that is not impossible but that has various disadvantages inpractice). We often identify functions with the symbols used to name them. Forexample, we often speak of ``the function @code{car},'' notdistinguishing between the symbol @code{car} and the primitivesubr-object that is its function definition. For most purposes, thedistinction is not important. Even so, keep in mind that a function need not have a unique name. Whilea given function object @emph{usually} appears in the function cell of onlyone symbol, this is just a matter of convenience. It is easy to storeit in several symbols using @code{fset}; then each of the symbols isequally well a name for the same function. A symbol used as a function name may also be used as a variable; thesetwo uses of a symbol are independent and do not conflict. (Some Lispdialects, such as Scheme, do not distinguish between a symbol's valueand its function definition; a symbol's value as a variable is also itsfunction definition.) If you have not given a symbol a functiondefinition, you cannot use it as a function; whether the symbol has avalue as a variable makes no difference to this.@node Defining Functions@section Defining Functions@cindex defining a function We usually give a name to a function when it is first created. Thisis called @dfn{defining a function}, and it is done with the@code{defun} special form.@defspec defun name argument-list body-forms@code{defun} is the usual way to define new Lisp functions. Itdefines the symbol @var{name} as a function that looks like this:@example(lambda @var{argument-list} . @var{body-forms})@end example@code{defun} stores this lambda expression in the function cell of@var{name}. It returns the value @var{name}, but usually we ignore thisvalue.As described previously, @var{argument-list} is a list of argumentnames and may include the keywords @code{&optional} and @code{&rest}(@pxref{Lambda Expressions}). Also, the first two of the@var{body-forms} may be a documentation string and an interactivedeclaration.There is no conflict if the same symbol @var{name} is also used as avariable, since the symbol's value cell is independent of the functioncell. @xref{Symbol Components}.Here are some examples:@example@group(defun foo () 5) @result{} foo@end group@group(foo) @result{} 5@end group@group(defun bar (a &optional b &rest c) (list a b c)) @result{} bar@end group@group(bar 1 2 3 4 5) @result{} (1 2 (3 4 5))@end group@group(bar 1) @result{} (1 nil nil)@end group@group(bar)@error{} Wrong number of arguments.@end group@group(defun capitalize-backwards () "Upcase the last letter of a word." (interactive) (backward-word 1) (forward-word 1) (backward-char 1) (capitalize-word 1)) @result{} capitalize-backwards@end group@end exampleBe careful not to redefine existing functions unintentionally.@code{defun} redefines even primitive functions such as @code{car}without any hesitation or notification. Redefining a function alreadydefined is often done deliberately, and there is no way to distinguishdeliberate redefinition from unintentional redefinition.@end defspec@defun defalias name definition &optional docstring@anchor{Definition of defalias}This special form defines the symbol @var{name} as a function, withdefinition @var{definition} (which can be any valid Lisp function).It returns @var{definition}.If @var{docstring} is non-@code{nil}, it becomes the functiondocumentation of @var{name}. Otherwise, any documentation provided by@var{definition} is used.The proper place to use @code{defalias} is where a specific functionname is being defined---especially where that name appears explicitly inthe source file being loaded. This is because @code{defalias} recordswhich file defined the function, just like @code{defun}(@pxref{Unloading}).By contrast, in programs that manipulate function definitions for otherpurposes, it is better to use @code{fset}, which does not keep suchrecords. @xref{Function Cells}.@end defun You cannot create a new primitive function with @code{defun} or@code{defalias}, but you can use them to change the function definition ofany symbol, even one such as @code{car} or @code{x-popup-menu} whosenormal definition is a primitive. However, this is risky: forinstance, it is next to impossible to redefine @code{car} withoutbreaking Lisp completely. Redefining an obscure function such as@code{x-popup-menu} is less dangerous, but it still may not work asyou expect. If there are calls to the primitive from C code, theycall the primitive's C definition directly, so changing the symbol'sdefinition will have no effect on them. See also @code{defsubst}, which defines a function like @code{defun}and tells the Lisp compiler to open-code it. @xref{Inline Functions}.@node Calling Functions@section Calling Functions@cindex function invocation@cindex calling a function Defining functions is only half the battle. Functions don't doanything until you @dfn{call} them, i.e., tell them to run. Calling afunction is also known as @dfn{invocation}. The most common way of invoking a function is by evaluating a list.For example, evaluating the list @code{(concat "a" "b")} calls thefunction @code{concat} with arguments @code{"a"} and @code{"b"}.@xref{Evaluation}, for a description of evaluation. When you write a list as an expression in your program, you specifywhich function to call, and how many arguments to give it, in the textof the program. Usually that's just what you want. Occasionally youneed to compute at run time which function to call. To do that, usethe function @code{funcall}. When you also need to determine at runtime how many arguments to pass, use @code{apply}.@defun funcall function &rest arguments@code{funcall} calls @var{function} with @var{arguments}, and returnswhatever @var{function} returns.Since @code{funcall} is a function, all of its arguments, including@var{function}, are evaluated before @code{funcall} is called. Thismeans that you can use any expression to obtain the function to becalled. It also means that @code{funcall} does not see theexpressions you write for the @var{arguments}, only their values.These values are @emph{not} evaluated a second time in the act ofcalling @var{function}; the operation of @code{funcall} is like thenormal procedure for calling a function, once its arguments havealready been evaluated.The argument @var{function} must be either a Lisp function or aprimitive function. Special forms and macros are not allowed, becausethey make sense only when given the ``unevaluated'' argumentexpressions. @code{funcall} cannot provide these because, as we sawabove, it never knows them in the first place.@example@group(setq f 'list) @result{} list@end group@group(funcall f 'x 'y 'z) @result{} (x y z)@end group@group(funcall f 'x 'y '(z)) @result{} (x y (z))@end group@group(funcall 'and t nil)@error{} Invalid function: #<subr and>@end group@end exampleCompare these examples with the examples of @code{apply}.@end defun@defun apply function &rest arguments@code{apply} calls @var{function} with @var{arguments}, just like@code{funcall} but with one difference: the last of @var{arguments} is alist of objects, which are passed to @var{function} as separatearguments, rather than a single list. We say that @code{apply}@dfn{spreads} this list so that each individual element becomes anargument.@code{apply} returns the result of calling @var{function}. As with@code{funcall}, @var{function} must either be a Lisp function or aprimitive function; special forms and macros do not make sense in@code{apply}.@example@group(setq f 'list) @result{} list@end group@group(apply f 'x 'y 'z)@error{} Wrong type argument: listp, z@end group@group(apply '+ 1 2 '(3 4)) @result{} 10@end group@group(apply '+ '(1 2 3 4)) @result{} 10@end group@group(apply 'append '((a b c) nil (x y z) nil)) @result{} (a b c x y z)@end group@end exampleFor an interesting example of using @code{apply}, see @ref{Definitionof mapcar}.@end defun@cindex functionals It is common for Lisp functions to accept functions as arguments orfind them in data structures (especially in hook variables and propertylists) and call them using @code{funcall} or @code{apply}. Functionsthat accept function arguments are often called @dfn{functionals}. Sometimes, when you call a functional, it is useful to supply a no-opfunction as the argument. Here are two different kinds of no-opfunction:@defun identity argThis function returns @var{arg} and has no side effects.@end defun@defun ignore &rest argsThis function ignores any arguments and returns @code{nil}.@end defun@node Mapping Functions@section Mapping Functions@cindex mapping functions A @dfn{mapping function} applies a given function (@emph{not} aspecial form or macro) to each element of a list or other collection.Emacs Lisp has several such functions; @code{mapcar} and@code{mapconcat}, which scan a list, are described here.@xref{Definition of mapatoms}, for the function @code{mapatoms} whichmaps over the symbols in an obarray. @xref{Definition of maphash},for the function @code{maphash} which maps over key/value associationsin a hash table. These mapping functions do not allow char-tables because a char-tableis a sparse array whose nominal range of indices is very large. To mapover a char-table in a way that deals properly with its sparse nature,use the function @code{map-char-table} (@pxref{Char-Tables}).@defun mapcar function sequence@anchor{Definition of mapcar}@code{mapcar} applies @var{function} to each element of @var{sequence}in turn, and returns a list of the results.The argument @var{sequence} can be any kind of sequence except achar-table; that is, a list, a vector, a bool-vector, or a string. Theresult is always a list. The length of the result is the same as thelength of @var{sequence}. For example:@smallexample@group(mapcar 'car '((a b) (c d) (e f))) @result{} (a c e)(mapcar '1+ [1 2 3]) @result{} (2 3 4)(mapcar 'char-to-string "abc") @result{} ("a" "b" "c")@end group@group;; @r{Call each function in @code{my-hooks}.}(mapcar 'funcall my-hooks)@end group@group(defun mapcar* (function &rest args) "Apply FUNCTION to successive cars of all ARGS.Return the list of results." ;; @r{If no list is exhausted,} (if (not (memq nil args)) ;; @r{apply function to @sc{car}s.} (cons (apply function (mapcar 'car args)) (apply 'mapcar* function ;; @r{Recurse for rest of elements.} (mapcar 'cdr args)))))@end group@group(mapcar* 'cons '(a b c) '(1 2 3 4)) @result{} ((a . 1) (b . 2) (c . 3))@end group@end smallexample@end defun@defun mapc function sequence@code{mapc} is like @code{mapcar} except that @var{function} is used forside-effects only---the values it returns are ignored, not collectedinto a list. @code{mapc} always returns @var{sequence}.@end defun@defun mapconcat function sequence separator@code{mapconcat} applies @var{function} to each element of@var{sequence}: the results, which must be strings, are concatenated.Between each pair of result strings, @code{mapconcat} inserts the string@var{separator}. Usually @var{separator} contains a space or comma orother suitable punctuation.The argument @var{function} must be a function that can take oneargument and return a string. The argument @var{sequence} can be anykind of sequence except a char-table; that is, a list, a vector, abool-vector, or a string.@smallexample@group(mapconcat 'symbol-name '(The cat in the hat) " ") @result{} "The cat in the hat"@end group@group(mapconcat (function (lambda (x) (format "%c" (1+ x)))) "HAL-8000" "") @result{} "IBM.9111"@end group@end smallexample@end defun@node Anonymous Functions@section Anonymous Functions@cindex anonymous function In Lisp, a function is a list that starts with @code{lambda}, abyte-code function compiled from such a list, or alternatively aprimitive subr-object; names are ``extra.'' Although usually functionsare defined with @code{defun} and given names at the same time, it isoccasionally more concise to use an explicit lambda expression---ananonymous function. Such a list is valid wherever a function name is. Any method of creating such a list makes a valid function. Even this:@smallexample@group(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))@result{} (lambda (x) (+ 12 x))@end group@end smallexample@noindentThis computes a list that looks like @code{(lambda (x) (+ 12 x))} andmakes it the value (@emph{not} the function definition!) of@code{silly}. Here is how we might call this function:@example@group(funcall silly 1)@result{} 13@end group@end example@noindent(It does @emph{not} work to write @code{(silly 1)}, because this functionis not the @emph{function definition} of @code{silly}. We have not given@code{silly} any function definition, just a value as a variable.) Most of the time, anonymous functions are constants that appear inyour program. For example, you might want to pass one as an argument tothe function @code{mapcar}, which applies any given function to eachelement of a list. Here we define a function @code{change-property} whichuses a function as its third argument:@example@group(defun change-property (symbol prop function) (let ((value (get symbol prop))) (put symbol prop (funcall function value))))@end group@end example@noindentHere we define a function that uses @code{change-property},passing it a function to double a number:@example@group(defun double-property (symbol prop) (change-property symbol prop '(lambda (x) (* 2 x))))@end group@end example@noindentIn such cases, we usually use the special form @code{function} insteadof simple quotation to quote the anonymous function, like this:@example@group(defun double-property (symbol prop) (change-property symbol prop (function (lambda (x) (* 2 x)))))@end group@end exampleUsing @code{function} instead of @code{quote} makes a difference if youcompile the function @code{double-property}. For example, if youcompile the second definition of @code{double-property}, the anonymousfunction is compiled as well. By contrast, if you compile the firstdefinition which uses ordinary @code{quote}, the argument passed to@code{change-property} is the precise list shown:@example(lambda (x) (* x 2))@end example@noindentThe Lisp compiler cannot assume this list is a function, even though itlooks like one, since it does not know what @code{change-property} willdo with the list. Perhaps it will check whether the @sc{car} of the thirdelement is the symbol @code{*}! Using @code{function} tells thecompiler it is safe to go ahead and compile the constant function. Nowadays it is possible to omit @code{function} entirely, like this:@example@group(defun double-property (symbol prop) (change-property symbol prop (lambda (x) (* 2 x))))@end group@end example@noindentThis is because @code{lambda} itself implies @code{function}. We sometimes write @code{function} instead of @code{quote} whenquoting the name of a function, but this usage is just a sort ofcomment:@example(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}@end example@cindex @samp{#'} syntax The read syntax @code{#'} is a short-hand for using @code{function}.For example,@example#'(lambda (x) (* x x))@end example@noindentis equivalent to@example(function (lambda (x) (* x x)))@end example@defspec function function-object@cindex function quotingThis special form returns @var{function-object} without evaluating it.In this, it is equivalent to @code{quote}. However, it serves as anote to the Emacs Lisp compiler that @var{function-object} is intendedto be used only as a function, and therefore can safely be compiled.Contrast this with @code{quote}, in @ref{Quoting}.@end defspec @xref{describe-symbols example}, for a realistic example using@code{function} and an anonymous function.@node Function Cells@section Accessing Function Cell Contents The @dfn{function definition} of a symbol is the object stored in thefunction cell of the symbol. The functions described here access, test,and set the function cell of symbols. See also the function @code{indirect-function}. @xref{Definition ofindirect-function}.@defun symbol-function symbol@kindex void-functionThis returns the object in the function cell of @var{symbol}. If thesymbol's function cell is void, a @code{void-function} error issignaled.This function does not check that the returned object is a legitimatefunction.@example@group(defun bar (n) (+ n 2)) @result{} bar@end group@group(symbol-function 'bar) @result{} (lambda (n) (+ n 2))@end group@group(fset 'baz 'bar) @result{} bar@end group@group(symbol-function 'baz) @result{} bar@end group@end example@end defun@cindex void function cell If you have never given a symbol any function definition, we say thatthat symbol's function cell is @dfn{void}. In other words, the functioncell does not have any Lisp object in it. If you try to call such a symbolas a function, it signals a @code{void-function} error. Note that void is not the same as @code{nil} or the symbol@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,and can be stored into a function cell just as any other object can be(and they can be valid functions if you define them in turn with@code{defun}). A void function cell contains no object whatsoever. You can test the voidness of a symbol's function definition with@code{fboundp}. After you have given a symbol a function definition, youcan make it void once more using @code{fmakunbound}.@defun fboundp symbolThis function returns @code{t} if the symbol has an object in itsfunction cell, @code{nil} otherwise. It does not check that the objectis a legitimate function.@end defun@defun fmakunbound symbolThis function makes @var{symbol}'s function cell void, so that asubsequent attempt to access this cell will cause a@code{void-function} error. It returns @var{symbol}. (See also@code{makunbound}, in @ref{Void Variables}.)@example@group(defun foo (x) x) @result{} foo@end group@group(foo 1) @result{}1@end group@group(fmakunbound 'foo) @result{} foo@end group@group(foo 1)@error{} Symbol's function definition is void: foo@end group@end example@end defun@defun fset symbol definitionThis function stores @var{definition} in the function cell of@var{symbol}. The result is @var{definition}. Normally@var{definition} should be a function or the name of a function, butthis is not checked. The argument @var{symbol} is an ordinary evaluatedargument.There are three normal uses of this function:@itemize @bullet@itemCopying one symbol's function definition to another---in other words,making an alternate name for a function. (If you think of this as thedefinition of the new name, you should use @code{defalias} instead of@code{fset}; see @ref{Definition of defalias}.)@itemGiving a symbol a function definition that is not a list and thereforecannot be made with @code{defun}. For example, you can use @code{fset}to give a symbol @code{s1} a function definition which is another symbol@code{s2}; then @code{s1} serves as an alias for whatever definition@code{s2} presently has. (Once again use @code{defalias} instead of@code{fset} if you think of this as the definition of @code{s1}.)@itemIn constructs for defining or altering functions. If @code{defun}were not a primitive, it could be written in Lisp (as a macro) using@code{fset}.@end itemizeHere are examples of these uses:@example@group;; @r{Save @code{foo}'s definition in @code{old-foo}.}(fset 'old-foo (symbol-function 'foo))@end group@group;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.};; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}(fset 'xfirst 'car) @result{} car@end group@group(xfirst '(1 2 3)) @result{} 1@end group@group(symbol-function 'xfirst) @result{} car@end group@group(symbol-function (symbol-function 'xfirst)) @result{} #<subr car>@end group@group;; @r{Define a named keyboard macro.}(fset 'kill-two-lines "\^u2\^k") @result{} "\^u2\^k"@end group@group;; @r{Here is a function that alters other functions.}(defun copy-function-definition (new old) "Define NEW with the same function definition as OLD." (fset new (symbol-function old)))@end group@end example@end defun @code{fset} is sometimes used to save the old definition of afunction before redefining it. That permits the new definition toinvoke the old definition. But it is unmodular and unclean for a Lispfile to redefine a function defined elsewhere. If you want to modifya function defined by another package, it is cleaner to use@code{defadvice} (@pxref{Advising Functions}).@node Obsolete Functions@section Declaring Functions ObsoleteYou can use @code{make-obsolete} to declare a function obsolete. Thisindicates that the function may be removed at some stage in the future.@defun make-obsolete obsolete-name current-name &optional whenThis function makes the byte compiler warn that the function@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, thewarning message says to use @var{current-name} instead of@var{obsolete-name}. @var{current-name} does not need to be an alias for@var{obsolete-name}; it can be a different function with similarfunctionality. If @var{current-name} is a string, it is the warningmessage.If provided, @var{when} should be a string indicating when the functionwas first made obsolete---for example, a date or a release number.@end defunYou can define a function as an alias and declare it obsolete at thesame time using the macro @code{define-obsolete-function-alias}.@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstringThis macro marks the function @var{obsolete-name} obsolete and alsodefines it as an alias for the function @var{current-name}. It isequivalent to the following:@example(defalias @var{obsolete-name} @var{current-name} @var{docstring})(make-obsolete @var{obsolete-name} @var{current-name} @var{when})@end example@end defmac@node Inline Functions@section Inline Functions@cindex inline functions@findex defsubstYou can define an @dfn{inline function} by using @code{defsubst} insteadof @code{defun}. An inline function works just like an ordinaryfunction except for one thing: when you compile a call to the function,the function's definition is open-coded into the caller.Making a function inline makes explicit calls run faster. But it alsohas disadvantages. For one thing, it reduces flexibility; if you changethe definition of the function, calls already inlined still use the olddefinition until you recompile them. Since the flexibility ofredefining functions is an important feature of Emacs, you should notmake a function inline unless its speed is really crucial.Another disadvantage is that making a large function inline can increasethe size of compiled code both in files and in memory. Since the speedadvantage of inline functions is greatest for small functions, yougenerally should not make large functions inline.It's possible to define a macro to expand into the same code that aninline function would execute. (@xref{Macros}.) But the macro would belimited to direct use in expressions---a macro cannot be called with@code{apply}, @code{mapcar} and so on. Also, it takes some work toconvert an ordinary function into a macro. To convert it into an inlinefunction is very easy; simply replace @code{defun} with @code{defsubst}.Since each argument of an inline function is evaluated exactly once, youneedn't worry about how many times the body uses the arguments, as youdo for macros. (@xref{Argument Evaluation}.)Inline functions can be used and open-coded later on in the same file,following the definition, just like macros.@node Function Safety@section Determining whether a Function is Safe to Call@cindex function safety@cindex safety of functionsSome major modes such as SES call functions that are stored in userfiles. (@inforef{Top, ,ses}, for more information on SES.) Userfiles sometimes have poor pedigrees---you can get a spreadsheet fromsomeone you've just met, or you can get one through email from someoneyou've never met. So it is risky to call a function whose source codeis stored in a user file until you have determined that it is safe.@defun unsafep form &optional unsafep-varsReturns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, orreturns a list that describes why it might be unsafe. The argument@var{unsafep-vars} is a list of symbols known to have temporarybindings at this point; it is mainly used for internal recursivecalls. The current buffer is an implicit argument, which provides alist of buffer-local bindings.@end defunBeing quick and simple, @code{unsafep} does a very light analysis andrejects many Lisp expressions that are actually safe. There are noknown cases where @code{unsafep} returns @code{nil} for an unsafeexpression. However, a ``safe'' Lisp expression can return a stringwith a @code{display} property, containing an associated Lispexpression to be executed after the string is inserted into a buffer.This associated expression can be a virus. In order to be safe, youmust delete properties from all strings calculated by user code beforeinserting them into buffers.@ignoreWhat is a safe Lisp expression? Basically, it's an expression thatcalls only built-in functions with no side effects (or only innocuousones). Innocuous side effects include displaying messages andaltering non-risky buffer-local variables (but not global variables).@table @dfn@item Safe expression@itemize@itemAn atom or quoted thing.@itemA call to a safe function (see below), if all its arguments aresafe expressions.@itemOne of the special forms @code{and}, @code{catch}, @code{cond},@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},@code{while}, and @code{unwind-protect}], if all its arguments aresafe.@itemA form that creates temporary bindings (@code{condition-case},@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or@code{let*}), if all args are safe and the symbols to be bound are notexplicitly risky (see @pxref{File Local Variables}).@itemAn assignment using @code{add-to-list}, @code{setq}, @code{push}, or@code{pop}, if all args are safe and the symbols to be assigned arenot explicitly risky and they already have temporary or buffer-localbindings.@itemOne of [apply, mapc, mapcar, mapconcat] if the first argument is asafe explicit lambda and the other args are safe expressions.@end itemize@item Safe function@itemize@itemA lambda containing safe expressions.@itemA symbol on the list @code{safe-functions}, so the user says it's safe.@itemA symbol with a non-@code{nil} @code{side-effect-free} property.@itemA symbol with a non-@code{nil} @code{safe-function} property. Value tindicates a function that is safe but has innocuous side effects.Other values will someday indicate functions with classes of sideeffects that are not always safe.@end itemizeThe @code{side-effect-free} and @code{safe-function} properties areprovided for built-in functions and for low-level functions and macrosdefined in @file{subr.el}. You can assign these properties for thefunctions you write.@end table@end ignore@node Related Topics@section Other Topics Related to Functions Here is a table of several functions that do things related tofunction calling and function definitions. They are documentedelsewhere, but we provide cross references here.@table @code@item applySee @ref{Calling Functions}.@item autoloadSee @ref{Autoload}.@item call-interactivelySee @ref{Interactive Call}.@item commandpSee @ref{Interactive Call}.@item documentationSee @ref{Accessing Documentation}.@item evalSee @ref{Eval}.@item funcallSee @ref{Calling Functions}.@item functionSee @ref{Anonymous Functions}.@item ignoreSee @ref{Calling Functions}.@item indirect-functionSee @ref{Function Indirection}.@item interactiveSee @ref{Using Interactive}.@item interactive-pSee @ref{Interactive Call}.@item mapatomsSee @ref{Creating Symbols}.@item mapcarSee @ref{Mapping Functions}.@item map-char-tableSee @ref{Char-Tables}.@item mapconcatSee @ref{Mapping Functions}.@item undefinedSee @ref{Functions for Key Lookup}.@end table@ignore arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2@end ignore