[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master be4f858: Add new function `ensure-list'
From: |
Lars Ingebrigtsen |
Subject: |
master be4f858: Add new function `ensure-list' |
Date: |
Tue, 21 Sep 2021 14:31:13 -0400 (EDT) |
branch: master
commit be4f8584983e63905aa409efad11fb7d8d418ccb
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>
Add new function `ensure-list'
* doc/lispref/lists.texi (Building Lists): Document it.
* lisp/subr.el (ensure-list): New function.
* lisp/emacs-lisp/shortdoc.el (list): Mention it.
---
doc/lispref/lists.texi | 14 ++++++++++++++
etc/NEWS | 5 +++++
lisp/emacs-lisp/shortdoc.el | 3 +++
lisp/subr.el | 8 ++++++++
test/lisp/subr-tests.el | 5 +++++
5 files changed, 35 insertions(+)
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index bbe1dce..6bb1146 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -679,6 +679,20 @@ list are in the same order as in @var{tree}.
@result{}(1 2 3 4 5 6 7)
@end example
+@defun ensure-list object
+Ensure that we have a list. If @var{object} is already a list, it is
+returned. If @var{object} isn't a list, a one-element list containing
+@var{object} is returned.
+
+This is usually useful if you have a variable that may or may not be a
+list, and you can then say, for instance:
+
+@lisp
+(dolist (elem (ensure-list foo))
+ (princ elem))
+@end lisp
+@end defun
+
@defun number-sequence from &optional to separation
This function returns a list of numbers starting with @var{from} and
incrementing by @var{separation}, and ending at or just before
diff --git a/etc/NEWS b/etc/NEWS
index d5b6919..eeb753a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3826,6 +3826,11 @@ it matches on fixed strings instead of regexps, and does
not change
the global match state.
+++
+** New function 'ensure-list'.
+This function makes a list of its object if it's not a list already.
+If it's already a list, the list is returned as is.
+
++++
** New function 'split-string-shell-command'.
This splits a shell command string into separate components,
respecting quoting with single ('like this') and double ("like this")
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 3e0d5ae..d4838ff 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -495,6 +495,9 @@ There can be any number of :example/:result elements."
:eval (list 1 2 3))
(number-sequence
:eval (number-sequence 5 8))
+ (ensure-list
+ :eval (ensure-list "foo")
+ :eval (ensure-list '(1 2 3)))
"Operations on Lists"
(append
:eval (append '("foo" "bar") '("zot")))
diff --git a/lisp/subr.el b/lisp/subr.el
index 6bd9a01..232e684 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -6426,4 +6426,12 @@ This is intended for internal use only."
(:success t)
(json-unavailable nil))))
+(defun ensure-list (object)
+ "Ensure that we have a list.
+If OBJECT is already a list, OBJECT is returned. If it's
+not a list, a one-element list containing OBJECT is returned."
+ (if (listp object)
+ object
+ (list object)))
+
;;; subr.el ends here
diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el
index 54bee7b..0c3661a 100644
--- a/test/lisp/subr-tests.el
+++ b/test/lisp/subr-tests.el
@@ -767,5 +767,10 @@ See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=19350."
(should-not (equal dir default-directory))
(should (file-exists-p default-directory)))))
+(ert-deftest test-ensure-list ()
+ (should (equal (ensure-list nil) nil))
+ (should (equal (ensure-list :foo) '(:foo)))
+ (should (equal (ensure-list '(1 2 3)) '(1 2 3))))
+
(provide 'subr-tests)
;;; subr-tests.el ends here
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master be4f858: Add new function `ensure-list',
Lars Ingebrigtsen <=