From a92ee96bb90cd829a53b997d02c85f0c7b006d94 Mon Sep 17 00:00:00 2001 From: Daniel Mendler Date: Tue, 7 Apr 2026 19:50:45 +0200 Subject: compat-31: New function ensure-proper-list --- NEWS.org | 1 + compat-31.el | 12 ++++++++++++ compat-tests.el | 16 ++++++++++++---- compat.texi | 21 +++++++++++++++++++++ 4 files changed, 46 insertions(+), 4 deletions(-) diff --git a/NEWS.org b/NEWS.org index b1974a2..a97fe63 100644 --- a/NEWS.org +++ b/NEWS.org @@ -18,6 +18,7 @@ - compat-31: New function =remove-display-text-property=. - compat-31: New functions =drop-while=, =take-while=, =member-if=, =any=, =all=. - compat-31: New function =set-local=. +- compat-31: New function =ensure-proper-list=. - Drop support for Emacs 24.x. Emacs 25.1 is required now. In case Emacs 24.x support is still needed, Compat 30 can be used. diff --git a/compat-31.el b/compat-31.el index 4133bdb..0c1a228 100644 --- a/compat-31.el +++ b/compat-31.el @@ -29,6 +29,18 @@ ;;;; Defined in subr.el +(compat-defun ensure-proper-list (object) ;; + "Return OBJECT as a list. +If OBJECT is already a proper list, return OBJECT itself. If it's not a +proper list, return a one-element list containing OBJECT. + +`ensure-list' is usually preferable because that function runs in +constant time, but this one has to traverse the whole of OBJECT." + (declare (side-effect-free error-free)) + (if (proper-list-p object) + object + (list object))) + (compat-defun set-local (variable value) ;; "Make VARIABLE buffer local and set it to VALUE." (set (make-local-variable variable) value)) diff --git a/compat-tests.el b/compat-tests.el index 0ad9b42..e471efb 100644 --- a/compat-tests.el +++ b/compat-tests.el @@ -1410,10 +1410,18 @@ (should-error (length< 3 nil) :type 'wrong-type-argument)) (ert-deftest compat-ensure-list () - (should-not (ensure-list nil)) ;; empty list - (should-equal '(1) (ensure-list '(1))) ;; single element list - (should-equal '(1 2 3) (ensure-list '(1 2 3))) ;; multiple element list - (should-equal '(1) (ensure-list 1))) ;; atom + (should-not (ensure-list nil)) ;; empty list + (should-equal '(1) (ensure-list '(1))) ;; single element list + (should-equal '(1 2 3) (ensure-list '(1 2 3))) ;; multiple element list + (should-equal '(1) (ensure-list 1)) ;; atom + (should-equal '(1 . 2) (ensure-list '(1 . 2)))) ;; cons + +(ert-deftest compat-ensure-proper-list () + (should-not (ensure-list nil)) ;; empty list + (should-equal '(1) (ensure-proper-list '(1))) ;; single element list + (should-equal '(1 2 3) (ensure-proper-list '(1 2 3))) ;; multiple element list + (should-equal '(1) (ensure-proper-list 1)) ;; atom + (should-equal '((1 . 2)) (ensure-proper-list '(1 . 2)))) ;; cons (ert-deftest compat-proper-list-p () (should-equal 0 (proper-list-p ())) ;; empty list diff --git a/compat.texi b/compat.texi index 6b2862a..a56d511 100644 --- a/compat.texi +++ b/compat.texi @@ -3459,6 +3459,27 @@ older than 31.1. Note that due to upstream changes, it might happen that there will be the need for changes, so use these functions with care. +@c copied from lispref/lists.texi +@defun ensure-proper-list object +This function returns @var{object} as a proper list (@pxref{(elisp) Cons +Cells}). If @var{object} is already a proper list, the function returns +it; otherwise, the function returns a one-element list containing +@var{object}. + +If @var{object} might be a long list, prefer @code{ensure-list}, because +the latter function runs in constant time, whereas +@code{ensure-proper-list} runs in linear time. For short lists this +function is a convenient way to treat cons-cells as non-lists: + +@lisp +(ensure-list '(1 . 2)) + @result{}(1 . 2) + +(ensure-proper-list '(1 . 2)) + @result{}((1 . 2)) +@end lisp +@end defun + @c based on lisp/subr.el @defun set-local variable value Make @var{variable} buffer local and set it to @var{value}. -- cgit v1.0