Commit fd8128f0 authored by Richard Stallman's avatar Richard Stallman Committed by Eli Zaretskii

; Move the description of define-inline to a different node in functions.texi

parent 524441d6
Pipeline #4532 passed with stage
in 57 minutes and 6 seconds
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment