@item cl-extra.el
This file contains the larger, more complex or unusual functions.
-It is kept separate so that packages which only want to use Common
-Lisp fundamentals like the @code{cl-incf} function won't need to pay
-the overhead of loading the more advanced functions.
@item cl-seq.el
This file contains most of the advanced functions for operating
but use different function names (in fact, @file{cl.el} mainly just
defines aliases to the @file{cl-lib.el} definitions). Where
@file{cl-lib.el} defines a function called, for example,
-@code{cl-incf}, @file{cl.el} uses the same name but without the
-@samp{cl-} prefix, e.g., @code{incf} in this example. There are a few
+@code{cl-first}, @file{cl.el} uses the same name but without the
+@samp{cl-} prefix, e.g., @code{first} in this example. There are a few
exceptions to this. First, functions such as @code{cl-defun} where
the unprefixed version was already used for a standard Emacs Lisp
function. In such cases, the @file{cl.el} version adds a @samp{*}
@menu
* Setf Extensions:: Additional @code{setf} places.
-* Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
+* Modify Macros:: @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
@end menu
@node Setf Extensions
all the assignments are done (in an undefined order).
@end defmac
-@defmac cl-incf place &optional x
-This macro increments the number stored in @var{place} by one, or
-by @var{x} if specified. The incremented value is returned. For
-example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
-@code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
-
-As with @code{setf}, care is taken to preserve the ``apparent'' order
-of evaluation. For example,
-
-@example
-(cl-incf (aref vec (cl-incf i)))
-@end example
-
-@noindent
-appears to increment @code{i} once, then increment the element of
-@code{vec} addressed by @code{i}; this is indeed exactly what it
-does, which means the above form is @emph{not} equivalent to the
-``obvious'' expansion,
-
-@example
-(setf (aref vec (cl-incf i))
- (1+ (aref vec (cl-incf i)))) ; wrong!
-@end example
-
-@noindent
-but rather to something more like
-
-@example
-(let ((temp (cl-incf i)))
- (setf (aref vec temp) (1+ (aref vec temp))))
-@end example
-
-@noindent
-Again, all of this is taken care of automatically by @code{cl-incf} and
-the other generalized-variable macros.
-
-As a more Emacs-specific example of @code{cl-incf}, the expression
-@code{(cl-incf (point) @var{n})} is essentially equivalent to
-@code{(forward-char @var{n})}.
-@end defmac
-
-@defmac cl-decf place &optional x
-This macro decrements the number stored in @var{place} by one, or
-by @var{x} if specified.
-@end defmac
-
@defmac cl-pushnew x place @t{&key :test :test-not :key}
This macro inserts @var{x} at the front of the list stored in
@var{place}, but only if @var{x} isn't present in the list already.
This is the ``generic'' modify macro. It calls @var{function},
which should be an unquoted function name, macro name, or lambda.
It passes @var{place} and @var{args} as arguments, and assigns the
-result back to @var{place}. For example, @code{(cl-incf @var{place}
-@var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
+result back to @var{place}. For example, @code{(incf @var{place}
+@var{n})} could be implemented as @code{(cl-callf + @var{place} @var{n})}.
Some more examples:
@example
@end defmac
The @code{cl-callf} and @code{cl-callf2} macros serve as building
-blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
+blocks for other macros like @code{cl-pushnew}.
The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
of symbol macros; @pxref{Macro Bindings}.
@example
(setq bar '(5 . 9))
(cl-symbol-macrolet ((foo (car bar)))
- (cl-incf foo))
+ (incf foo))
bar
@result{} (6 . 9)
@end example
body))))
(setq mylist '(1 2 3 4))
-(my-dolist (x mylist) (cl-incf x))
+(my-dolist (x mylist) (incf x))
mylist
@result{} (2 3 4 5)
@end example
@example
(cl-loop for G1234 on mylist do
(cl-symbol-macrolet ((x (car G1234)))
- (cl-incf x)))
+ (incf x)))
@end example
@noindent
which in turn expands to
@example
-(cl-loop for G1234 on mylist do (cl-incf (car G1234)))
+(cl-loop for G1234 on mylist do (incf (car G1234)))
@end example
@xref{Loop Facility}, for a description of the @code{cl-loop} macro.
rather than just a temporary variable. For example,
@example
-(cl-loop for x in-ref my-list do (cl-incf x))
+(cl-loop for x in-ref my-list do (incf x))
@end example
@noindent
The fact that @code{default} is ignored can sometimes be useful:
@example
-(cl-incf (cl-get 'foo 'usage-count 0))
+(incf (cl-get 'foo 'usage-count 0))
@end example
Here, symbol @code{foo}'s @code{usage-count} property is incremented
slots by using @code{setf} on any of these place forms, for example:
@example
-(cl-incf (person-age birthday-boy))
+(incf (person-age birthday-boy))
@end example
You can create a new @code{person} by calling @code{make-person},
Many of the advanced features of this package, such as @code{cl-defun},
@code{cl-loop}, etc., are implemented as Lisp macros. In
byte-compiled code, these complex notations will be expanded into
-equivalent Lisp code which is simple and efficient. For example,
-the form
-
-@example
-(cl-incf i n)
-@end example
-
-@noindent
-is expanded at compile-time to the Lisp form
-
-@example
-(setq i (+ i n))
-@end example
-
-@noindent
-which is the most efficient way of doing this operation
-in Lisp. Thus, there is no performance penalty for using the more
-readable @code{cl-incf} form in your compiled code.
+equivalent Lisp code which is simple and efficient. Thus, there is no
+performance penalty for using the more readable form in your compiled
+code.
@emph{Interpreted} code, on the other hand, must expand these macros
every time they are executed. For this reason it is strongly
recommended that code making heavy use of macros be compiled.
-A loop using @code{cl-incf} a hundred times will execute considerably
+A loop using @code{cl-first} a hundred times will execute considerably
faster if compiled, and will also garbage-collect less because the
macro expansion will not have to be generated, used, and thrown away a
hundred times.
@example
(defun make-counter ()
(lexical-let ((n 0))
- (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
+ (cl-function (lambda (&optional (m 1)) (incf n m)))))
(setq count-1 (make-counter))
(funcall count-1 3)
@result{} 3
@defmac define-modify-macro name arglist function [doc-string]
This macro defines a ``read-modify-write'' macro similar to
-@code{cl-incf} and @code{cl-decf}. You can replace this macro
+@code{incf} and @code{decf}. You can replace this macro
with @code{gv-letplace}.
The macro @var{name} is defined to take a @var{place} argument
The Lisp form that is returned can access the arguments from
@var{arglist} and @var{store-var} in an unrestricted fashion;
-macros like @code{cl-incf} that invoke this
-setf-method will insert temporary variables as needed to make
+macros that invoke this
+setf-method should insert temporary variables as needed to make
sure the apparent order of evaluation is preserved.
Another standard example:
@code{defsetf}, the second return value is simply the list of
arguments in the place form, and the first return value is a
list of a corresponding number of temporary variables generated
-@c FIXME I don't think this is true anymore.
-by @code{cl-gensym}. Macros like @code{cl-incf} that
-use this setf-method will optimize away most temporaries that
-turn out to be unnecessary, so there is little reason for the
-setf-method itself to optimize.
+by @code{cl-gensym}.
@end defmac
@node GNU Free Documentation License
;; `(if (member ,v ,getter) nil
;; ,(funcall setter `(cons ,v ,getter))))))
-;; (defmacro gv-inc! (place &optional val)
-;; "Increment PLACE by VAL (default to 1)."
-;; (declare (debug (gv-place &optional form)))
-;; (gv-letplace (getter setter) place
-;; (funcall setter `(+ ,getter ,(or val 1)))))
+;;;###autoload
+(defmacro incf (place &optional delta)
+ "Increment PLACE by DELTA (default to 1).
-;; (defmacro gv-dec! (place &optional val)
-;; "Decrement PLACE by VAL (default to 1)."
-;; (declare (debug (gv-place &optional form)))
-;; (gv-letplace (getter setter) place
-;; (funcall setter `(- ,getter ,(or val 1)))))
+The DELTA is first added to PLACE, and then stored in PLACE.
+Return the incremented value of PLACE.
+
+See also `decf'."
+ (declare (debug (gv-place &optional form)))
+ (gv-letplace (getter setter) place
+ (funcall setter `(+ ,getter ,(or delta 1)))))
+
+;;;###autoload
+(defmacro decf (place &optional delta)
+ "Decrement PLACE by DELTA (default to 1).
+
+The DELTA is first subtracted from PLACE, and then stored in PLACE.
+Return the decremented value of PLACE.
+
+See also `incf'."
+ (declare (debug (gv-place &optional form)))
+ (gv-letplace (getter setter) place
+ (funcall setter `(- ,getter ,(or delta 1)))))
;; For Edebug, the idea is to let Edebug instrument gv-places just like it does
;; for normal expressions, and then give it a gv-expander to DTRT.
(should (equal (cl-multiple-value-list nil) nil))
(should (equal (cl-multiple-value-list (list 1 2 3)) '(1 2 3))))
-(defvar cl-lib-test--special 0)
-
-(ert-deftest cl-lib-test-incf ()
- (setq cl-lib-test--special 0)
- (should (= (cl-incf cl-lib-test--special) 1))
- (should (= cl-lib-test--special 1))
- (should (= (cl-incf cl-lib-test--special 9) 10))
- (should (= cl-lib-test--special 10))
- (let ((var 0))
- (should (= (cl-incf var) 1))
- (should (= var 1))
- (should (= (cl-incf var 9) 10))
- (should (= var 10)))
- (let ((alist))
- (should (= (cl-incf (alist-get 'a alist 0)) 1))
- (should (= (alist-get 'a alist 0) 1))
- (should (= (cl-incf (alist-get 'a alist 0) 9) 10))
- (should (= (alist-get 'a alist 0) 10))))
-
-(ert-deftest cl-lib-test-decf ()
- (setq cl-lib-test--special 0)
- (should (= (cl-decf cl-lib-test--special) -1))
- (should (= cl-lib-test--special -1))
- (should (= (cl-decf cl-lib-test--special 9) -10))
- (should (= cl-lib-test--special -10))
- (let ((var 1))
- (should (= (cl-decf var) 0))
- (should (= var 0))
- (should (= (cl-decf var 10) -10))
- (should (= var -10)))
- (let ((alist))
- (should (= (cl-decf (alist-get 'a alist 0)) -1))
- (should (= (alist-get 'a alist 0) -1))
- (should (= (cl-decf (alist-get 'a alist 0) 9) -10))
- (should (= (alist-get 'a alist 0) -10))))
-
(ert-deftest cl-digit-char-p ()
(should (eql 3 (cl-digit-char-p ?3)))
(should (eql 10 (cl-digit-char-p ?a 11)))
projects / emacs.git / commitdiff