Better documentation for cl-reduce (bug#24014)

[gnu-emacs] / lisp / emacs-lisp / cl-seq.el

diff --git a/lisp/emacs-lisp/cl-seq.el b/lisp/emacs-lisp/cl-seq.el
index 6b5b329e33f524e8755501f512a10e74e6e77628..443a147b3d223badf4ef406670df77cb3eda70d9 100644 (file)
--- a/lisp/emacs-lisp/cl-seq.el
+++ b/lisp/emacs-lisp/cl-seq.el
@@ -1,6 +1,6 @@
 ;;; cl-seq.el --- Common Lisp features, part 3  -*- lexical-binding: t -*-
 
-;; Copyright (C) 1993, 2001-2013 Free Software Foundation, Inc.
+;; Copyright (C) 1993, 2001-2016 Free Software Foundation, Inc.
 
 ;; Author: Dave Gillespie <daveg@synaptics.com>
 ;; Old-Version: 2.02
@@ -116,6 +116,16 @@
 (defun cl-reduce (cl-func cl-seq &rest cl-keys)
   "Reduce two-argument FUNCTION across SEQ.
 \nKeywords supported:  :start :end :from-end :initial-value :key
+
+Return the result of calling FUNCTION with the first and the
+second element of SEQ, then calling FUNCTION with that result and
+the third element of SEQ, then with that result and the fourth
+element of SEQ, etc.
+
+If :INITIAL-VALUE is specified, it is added to the front of SEQ.
+If SEQ is empty, return :INITIAL-VALUE and FUNCTION is not
+called.
+
 \n(fn FUNCTION SEQ [KEYWORD VALUE]...)"
   (cl--parsing-keywords (:from-end (:start 0) :end :initial-value :key) ()
     (or (listp cl-seq) (setq cl-seq (append cl-seq nil)))
@@ -166,7 +176,7 @@ SEQ1 is destructively modified, then returned.
                   (cl-n (min (- (or cl-end1 cl-len) cl-start1)
                              (- (or cl-end2 cl-len) cl-start2))))
              (while (>= (setq cl-n (1- cl-n)) 0)
-               (cl--set-elt cl-seq1 (+ cl-start1 cl-n)
+               (setf (elt cl-seq1 (+ cl-start1 cl-n))
                            (elt cl-seq2 (+ cl-start2 cl-n))))))
       (if (listp cl-seq1)
          (let ((cl-p1 (nthcdr cl-start1 cl-seq1))
@@ -392,7 +402,7 @@ to avoid corrupting the original SEQ.
            cl-seq
          (setq cl-seq (copy-sequence cl-seq))
          (or cl-from-end
-             (progn (cl--set-elt cl-seq cl-i cl-new)
+             (progn (setf (elt cl-seq cl-i) cl-new)
                     (setq cl-i (1+ cl-i) cl-count (1- cl-count))))
          (apply 'cl-nsubstitute cl-new cl-old cl-seq :count cl-count
                 :start cl-i cl-keys))))))
@@ -439,7 +449,7 @@ This is a destructive function; it reuses the storage of SEQ whenever possible.
                (setq cl-end (1- cl-end))
                (if (cl--check-test cl-old (elt cl-seq cl-end))
                    (progn
-                     (cl--set-elt cl-seq cl-end cl-new)
+                     (setf (elt cl-seq cl-end) cl-new)
                      (setq cl-count (1- cl-count)))))
            (while (and (< cl-start cl-end) (> cl-count 0))
              (if (cl--check-test cl-old (aref cl-seq cl-start))
@@ -774,7 +784,7 @@ to avoid corrupting the original LIST1 and LIST2.
 \nKeywords supported:  :test :test-not :key
 \n(fn LIST1 LIST2 [KEYWORD VALUE]...)"
   (cond ((null cl-list1) cl-list2) ((null cl-list2) cl-list1)
-       ((equal cl-list1 cl-list2) cl-list1)
+       ((and (not cl-keys) (equal cl-list1 cl-list2)) cl-list1)
        (t
         (or (>= (length cl-list1) (length cl-list2))
             (setq cl-list1 (prog1 cl-list2 (setq cl-list2 cl-list1))))
@@ -849,7 +859,7 @@ to avoid corrupting the original LIST1 and LIST2.
                (memq (car cl-list1) cl-list2))
              (push (car cl-list1) cl-res))
          (pop cl-list1))
-       cl-res))))
+        (nreverse cl-res)))))
 
 ;;;###autoload
 (defun cl-nset-difference (cl-list1 cl-list2 &rest cl-keys)
@@ -1018,4 +1028,6 @@ Atoms are compared by `eql'; cons cells are compared recursively.
 ;; generated-autoload-file: "cl-loaddefs.el"
 ;; End:
 
+(provide 'cl-seq)
+
 ;;; cl-seq.el ends here