@tindex functionp
@defun functionp object
-This function returns @code{t} if @var{object} is any kind of function;
-that is, anything that could be called as a function.
+This function returns @code{t} if @var{object} is any kind of function,
+or a special form or macro.
@end defun
@defun subrp object
accessed.
It is a good idea to provide documentation strings for all the
-functions in your program, even those that are only called from within
+functions in your program, even those that are called only from within
your program. Documentation strings are like comments, except that they
are easier to access.
In most computer languages, every function has a name; the idea of a
function without a name is nonsensical. In Lisp, a function in the
strictest sense has no name. It is simply a list whose first element is
-@code{lambda}, or a primitive subr-object.
+@code{lambda}, a byte-code function object, or a primitive subr-object.
However, a symbol can serve as the name of a function. This happens
when you put the function in the symbol's @dfn{function cell}
which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
-functions @code{funcall} and @code{apply}.
+function @code{funcall}. When you also need to determine at run time
+how may arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
list or other collection. Emacs Lisp has several such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
here. @xref{Creating Symbols}, for the function @code{mapatoms} which
-maps over the symbols in an obarray. @xref{Char-Tables}, for the
-function @code{map-char-table}, which maps over the elements in a
-char-table.
+maps over the symbols in an obarray.
+
+ These mapping functions do not allow char-tables because a char-table
+is a sparse array whose nominal range of indices is very large. To map
+over 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
@code{mapcar} applies @var{function} to each element of @var{sequence}
in turn, and returns a list of the results.
-The argument @var{sequence} may be a list, a vector, or a string. The
+The argument @var{sequence} can be any kind of sequence except a
+char-table; that is, a list, a vector, a bool-vector, or a string. The
result is always a list. The length of the result is the same as the
length of @var{sequence}.
@end group
@group
-(defun mapcar* (f &rest args)
+(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 f (mapcar 'car args))
- (apply 'mapcar* f
+ ;; @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
other suitable punctuation.
The argument @var{function} must be a function that can take one
-argument and return a string.
+argument and return a string. The argument @var{sequence} can be any
+kind of sequence except a char-table; that is, a list, a vector, a
+bool-vector, or a string.
@smallexample
@group
@noindent
Here we define a function that uses @code{change-property},
-passing a function that doubles its argument:
+passing it a function to double a number:
@example
@group
@itemize @bullet
@item
-Copying one symbol's function definition to another. (In other words,
-making an alternate name for a function.)
+Copying one symbol's function definition to another---in other words,
+making an alternate name for a function. (If you think of this as the
+definition of the new name, you should use @code{defalias} instead of
+@code{fset}; see @ref{Defining Functions}.)
@item
Giving a symbol a function definition that is not a list and therefore
cannot 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.
+@code{s2} presently has. (Once again use @code{defalias} instead of
+@code{fset} if you think of this as the definition of @code{s1}.)
@item
In constructs for defining or altering functions. If @code{defun}
@code{fset}.
@end itemize
-Here are examples of the first two uses:
+Here are examples of these uses:
@example
@group
-;; @r{Give @code{first} the same definition @code{car} has.}
-(fset 'first (symbol-function 'car))
- @result{} #<subr car>
-@end group
-@group
-(first '(1 2 3))
- @result{} 1
+;; @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
(fset 'kill-two-lines "\^u2\^k")
@result{} "\^u2\^k"
@end group
-@end example
-See also the related function @code{defalias}, in @ref{Defining
-Functions}.
+@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
When writing a function that extends a previously defined function,
file is loaded before moving aside the old definition of @code{foo}.
But it is unmodular and unclean, in any case, for a Lisp file to
-redefine a function defined elsewhere.
+redefine a function defined elsewhere. It is cleaner to use the advice
+facility (@pxref{Advising Functions}).
@node Inline Functions
@section Inline Functions
generally should not make large functions inline.
It's possible to define a macro to expand into the same code that an
-inline function would execute. But the macro would have a limitation:
-you can use it only explicitly---a macro cannot be called with
+inline function would execute. (@xref{Macros}.) But the macro would be
+limited to direct use in expressions---a macro cannot be called with
@code{apply}, @code{mapcar} and so on. Also, it takes some work to
-convert an ordinary function into a macro. (@xref{Macros}.) To convert
-it into an inline function is very easy; simply replace @code{defun}
-with @code{defsubst}. Since each argument of an inline function is
-evaluated exactly once, you needn't worry about how many times the
-body uses the arguments, as you do for macros. (@xref{Argument
-Evaluation}.)
+convert an ordinary function into a macro. To convert it into an inline
+function is very easy; simply replace @code{defun} with @code{defsubst}.
+Since each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do 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.
@item funcall
See @ref{Calling Functions}.
+@item function
+See @ref{Anonymous Functions}.
+
@item ignore
See @ref{Calling Functions}.
@item mapcar
See @ref{Mapping Functions}.
+@item map-char-table
+See @ref{Char-Tables}.
+
@item mapconcat
See @ref{Mapping Functions}.
HCoop / bpt / emacs.git / blobdiff