; Move the description of define-inline to a different node in functions.texi
This commit is contained in:
Richard Stallman
Eli Zaretskii
parent
524441d6b3
commit
fd8128f0c1
1 changed files with 100 additions and 96 deletions
|
|
@ -576,8 +576,9 @@ naming conventions, which are being phased out.
|
|||
@cindex defining a function
|
||||
|
||||
We usually give a name to a function when it is first created. This
|
||||
is called @dfn{defining a function}, and it is done with the
|
||||
@code{defun} macro.
|
||||
is called @dfn{defining a function}, and we usually do it with the
|
||||
@code{defun} macro. This section also describes other ways to define
|
||||
a function.
|
||||
|
||||
@defmac defun name args [doc] [declare] [interactive] body@dots{}
|
||||
@code{defun} is the usual way to define new Lisp functions. It
|
||||
|
|
@ -682,95 +683,8 @@ definition will have no effect on them.
|
|||
and tells the Lisp compiler to perform inline expansion on it.
|
||||
@xref{Inline Functions}.
|
||||
|
||||
Alternatively, you can define a function by providing the code which
|
||||
will inline it as a compiler macro. The following macros make this
|
||||
possible.
|
||||
|
||||
@c FIXME: Can define-inline use the interactive spec?
|
||||
@defmac define-inline name args [doc] [declare] body@dots{}
|
||||
Define a function @var{name} by providing code that does its inlining,
|
||||
as a compiler macro. The function will accept the argument list
|
||||
@var{args} and will have the specified @var{body}.
|
||||
|
||||
If present, @var{doc} should be the function's documentation string
|
||||
(@pxref{Function Documentation}); @var{declare}, if present, should be
|
||||
a @code{declare} form (@pxref{Declare Form}) specifying the function's
|
||||
metadata.
|
||||
@end defmac
|
||||
|
||||
Functions defined via @code{define-inline} have several advantages
|
||||
with respect to macros defined by @code{defsubst} or @code{defmacro}:
|
||||
|
||||
@itemize @minus
|
||||
@item
|
||||
They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
|
||||
|
||||
@item
|
||||
They are more efficient.
|
||||
|
||||
@item
|
||||
They can be used as @dfn{place forms} to store values
|
||||
(@pxref{Generalized Variables}).
|
||||
|
||||
@item
|
||||
They behave in a more predictable way than @code{cl-defsubst}
|
||||
(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
|
||||
Lisp}).
|
||||
@end itemize
|
||||
|
||||
Like @code{defmacro}, a function inlined with @code{define-inline}
|
||||
inherits the scoping rules, either dynamic or lexical, from the call
|
||||
site. @xref{Variable Scoping}.
|
||||
|
||||
The following macros should be used in the body of a function defined
|
||||
by @code{define-inline}.
|
||||
|
||||
@defmac inline-quote expression
|
||||
Quote @var{expression} for @code{define-inline}. This is similar to
|
||||
the backquote (@pxref{Backquote}), but quotes code and accepts only
|
||||
@code{,}, not @code{,@@}.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-letevals (bindings@dots{}) body@dots{}
|
||||
This is similar to @code{let} (@pxref{Local Variables}): it sets up
|
||||
local variables as specified by @var{bindings}, and then evaluates
|
||||
@var{body} with those bindings in effect. Each element of
|
||||
@var{bindings} should be either a symbol or a list of the form
|
||||
@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
|
||||
@var{expr} and bind @var{var} to the result. The tail of
|
||||
@var{bindings} can be either @code{nil} or a symbol which should hold
|
||||
a list of arguments, in which case each argument is evaluated, and the
|
||||
symbol is bound to the resulting list.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-const-p expression
|
||||
Return non-@code{nil} if the value of @var{expression} is already
|
||||
known.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-const-val expression
|
||||
Return the value of @var{expression}.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-error format &rest args
|
||||
Signal an error, formatting @var{args} according to @var{format}.
|
||||
@end defmac
|
||||
|
||||
Here's an example of using @code{define-inline}:
|
||||
|
||||
@lisp
|
||||
(define-inline myaccessor (obj)
|
||||
(inline-letevals (obj)
|
||||
(inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
|
||||
@end lisp
|
||||
|
||||
@noindent
|
||||
This is equivalent to
|
||||
|
||||
@lisp
|
||||
(defsubst myaccessor (obj)
|
||||
(if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
|
||||
@end lisp
|
||||
To undefine a function name, use @code{fmakunbound}.
|
||||
@xref{Function Cells}.
|
||||
|
||||
@node Calling Functions
|
||||
@section Calling Functions
|
||||
|
|
@ -2155,8 +2069,12 @@ this:
|
|||
An @dfn{inline function} is a function that works just like an
|
||||
ordinary function, except for one thing: when you byte-compile a call
|
||||
to the function (@pxref{Byte Compilation}), the function's definition
|
||||
is expanded into the caller. To define an inline function, use
|
||||
@code{defsubst} instead of @code{defun}.
|
||||
is expanded into the caller.
|
||||
|
||||
The simple way to define an inline function, is to write
|
||||
@code{defsubst} instead of @code{defun}. The rest of the definition
|
||||
looks just the same, but using @code{defsubst} says to make it inline
|
||||
for byte compilation.
|
||||
|
||||
@defmac defsubst name args [doc] [declare] [interactive] body@dots{}
|
||||
This macro defines an inline function. Its syntax is exactly the same
|
||||
|
|
@ -2194,9 +2112,95 @@ 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.
|
||||
|
||||
As an alternative to @code{defsubst}, you can use
|
||||
@code{define-inline} to define functions via their exhaustive compiler
|
||||
macro. @xref{Defining Functions, define-inline}.
|
||||
Alternatively, you can define a function by providing the code which
|
||||
will inline it as a compiler macro. The following macros make this
|
||||
possible.
|
||||
|
||||
@c FIXME: Can define-inline use the interactive spec?
|
||||
@defmac define-inline name args [doc] [declare] body@dots{}
|
||||
Define a function @var{name} by providing code that does its inlining,
|
||||
as a compiler macro. The function will accept the argument list
|
||||
@var{args} and will have the specified @var{body}.
|
||||
|
||||
If present, @var{doc} should be the function's documentation string
|
||||
(@pxref{Function Documentation}); @var{declare}, if present, should be
|
||||
a @code{declare} form (@pxref{Declare Form}) specifying the function's
|
||||
metadata.
|
||||
@end defmac
|
||||
|
||||
Functions defined via @code{define-inline} have several advantages
|
||||
with respect to macros defined by @code{defsubst} or @code{defmacro}:
|
||||
|
||||
@itemize @minus
|
||||
@item
|
||||
They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
|
||||
|
||||
@item
|
||||
They are more efficient.
|
||||
|
||||
@item
|
||||
They can be used as @dfn{place forms} to store values
|
||||
(@pxref{Generalized Variables}).
|
||||
|
||||
@item
|
||||
They behave in a more predictable way than @code{cl-defsubst}
|
||||
(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
|
||||
Lisp}).
|
||||
@end itemize
|
||||
|
||||
Like @code{defmacro}, a function inlined with @code{define-inline}
|
||||
inherits the scoping rules, either dynamic or lexical, from the call
|
||||
site. @xref{Variable Scoping}.
|
||||
|
||||
The following macros should be used in the body of a function defined
|
||||
by @code{define-inline}.
|
||||
|
||||
@defmac inline-quote expression
|
||||
Quote @var{expression} for @code{define-inline}. This is similar to
|
||||
the backquote (@pxref{Backquote}), but quotes code and accepts only
|
||||
@code{,}, not @code{,@@}.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-letevals (bindings@dots{}) body@dots{}
|
||||
This is similar to @code{let} (@pxref{Local Variables}): it sets up
|
||||
local variables as specified by @var{bindings}, and then evaluates
|
||||
@var{body} with those bindings in effect. Each element of
|
||||
@var{bindings} should be either a symbol or a list of the form
|
||||
@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
|
||||
@var{expr} and bind @var{var} to the result. The tail of
|
||||
@var{bindings} can be either @code{nil} or a symbol which should hold
|
||||
a list of arguments, in which case each argument is evaluated, and the
|
||||
symbol is bound to the resulting list.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-const-p expression
|
||||
Return non-@code{nil} if the value of @var{expression} is already
|
||||
known.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-const-val expression
|
||||
Return the value of @var{expression}.
|
||||
@end defmac
|
||||
|
||||
@defmac inline-error format &rest args
|
||||
Signal an error, formatting @var{args} according to @var{format}.
|
||||
@end defmac
|
||||
|
||||
Here's an example of using @code{define-inline}:
|
||||
|
||||
@lisp
|
||||
(define-inline myaccessor (obj)
|
||||
(inline-letevals (obj)
|
||||
(inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
|
||||
@end lisp
|
||||
|
||||
@noindent
|
||||
This is equivalent to
|
||||
|
||||
@lisp
|
||||
(defsubst myaccessor (obj)
|
||||
(if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
|
||||
@end lisp
|
||||
|
||||
@node Declare Form
|
||||
@section The @code{declare} Form
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue