master 434ab2e0889 1/4: Improve delete-consecutive-dups doc precision and add test

[Mattias Engdegård]

branch: master
commit 434ab2e08895bdf952de78aea285da33be63c954
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Improve delete-consecutive-dups doc precision and add test
    
    * lisp/subr.el (delete-consecutive-dups): Document which element of
    each run is retained (the earliest in the list).  This matters because
    it makes it safe to ignore the return value.
    * test/lisp/subr-tests.el (subr--delete-dups)
    (subr--delete-consecutive-dups): Add tests.
---
 lisp/subr.el            |  4 +++-
 test/lisp/subr-tests.el | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/lisp/subr.el b/lisp/subr.el
index 916b6de494b..ef2f63f7c37 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -768,7 +768,9 @@ one is kept.  See `seq-uniq' for non-destructive operation."
 (defun delete-consecutive-dups (list &optional circular)
   "Destructively remove `equal' consecutive duplicates from LIST.
 First and last elements are considered consecutive if CIRCULAR is
-non-nil."
+non-nil.
+Of several consecutive `equal' occurrences, the one earliest in
+the list is kept."
   (let ((tail list) last)
     (while (cdr tail)
       (if (equal (car tail) (cadr tail))
diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el
index d5efabc1370..050ee22ac18 100644
--- a/test/lisp/subr-tests.el
+++ b/test/lisp/subr-tests.el
@@ -1171,5 +1171,39 @@ final or penultimate step during initialization."))
   (should-not (list-of-strings-p '("a" nil "b")))
   (should-not (list-of-strings-p '("a" "b" . "c"))))
 
+(ert-deftest subr--delete-dups ()
+  (should (equal (delete-dups nil) nil))
+  (let* ((a (list "a" "b" "c"))
+         (a-dedup (delete-dups a)))
+    (should (equal a-dedup '("a" "b" "c")))
+    (should (eq a a-dedup)))
+  (let* ((a (list "a" "a" "b" "b" "a" "c" "b" "c" "a"))
+         (a-b (cddr a))   ; link of first "b"
+         (a-dedup (delete-dups a)))
+    (should (equal a-dedup '("a" "b" "c")))
+    (should (eq a a-dedup))
+    (should (eq (cdr a-dedup) a-b))))
+
+(ert-deftest subr--delete-consecutive-dups ()
+  (should (equal (delete-consecutive-dups nil) nil))
+  (let* ((a (list "a" "b" "c"))
+         (a-dedup (delete-consecutive-dups a)))
+    (should (equal a-dedup '("a" "b" "c")))
+    (should (eq a a-dedup)))
+  (let* ((a (list "a" "a" "b" "a" "a" "b" "b" "b" "c" "c" "a" "a"))
+         (a-b (nthcdr 3 a))   ; link of third "a"
+         (a-dedup (delete-consecutive-dups a)))
+    (should (equal a-dedup '("a" "b" "a" "b" "c" "a")))
+    (should (eq a a-dedup))
+    (should (equal (nthcdr 2 a-dedup) a-b)))
+  (let* ((a (list "a" "b" "a"))
+         (a-dedup (delete-consecutive-dups a t)))
+    (should (equal a-dedup '("a" "b")))
+    (should (eq a a-dedup)))
+  (let* ((a (list "a" "a" "b" "a" "a" "b" "b" "b" "c" "c" "a" "a"))
+         (a-dedup (delete-consecutive-dups a t)))
+    (should (equal a-dedup '("a" "b" "a" "b" "c")))
+    (should (eq a a-dedup))))
+
 (provide 'subr-tests)
 ;;; subr-tests.el ends here