[elpa] externals/dash c8c6ea4 05/14: [Fix #154] Clarify that -flatten destroys all nils.

[Phillip Lord]

branch: externals/dash
commit c8c6ea4aa1b12abd15e8f943125edf4cec08b663
Author: Matus Goljer <address@hidden>
Commit: Matus Goljer <address@hidden>

    [Fix #154] Clarify that -flatten destroys all nils.
---
 dash.el         |    8 ++++++++
 dev/examples.el |    5 ++++-
 2 files changed, 12 insertions(+), 1 deletions(-)

diff --git a/dash.el b/dash.el
index ac143bc..9a82064 100644
--- a/dash.el
+++ b/dash.el
@@ -396,6 +396,14 @@ Thus function FN should return a list."
 (defun -flatten (l)
   "Take a nested list L and return its contents as a single, flat list.
 
+Note that because `nil' represents a list of zero elements (an
+empty list), any mention of nil in L will disappear after
+flattening.  If you need to preserve nils, consider `-flatten-n'
+or map them to some unique symbol and then map them back.
+
+Conses of two atoms are considered \"terminals\", that is, they
+aren't flattened further.
+
 See also: `-flatten-n'"
   (if (and (listp l) (listp (cdr l)))
       (-mapcat '-flatten l)
diff --git a/dev/examples.el b/dev/examples.el
index 2410eda..8491ccb 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -179,7 +179,10 @@ new list."
   (defexamples -flatten
     (-flatten '((1))) => '(1)
     (-flatten '((1 (2 3) (((4 (5))))))) => '(1 2 3 4 5)
-    (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4)))
+    (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4))
+    (-flatten '(nil nil nil)) => nil
+    (-flatten '(nil (1) nil)) => '(1)
+    (-flatten '(nil (nil) nil)) => nil)
 
   (defexamples -flatten-n
     (-flatten-n 1 '((1 2) ((3 4) ((5 6))))) => '(1 2 (3 4) ((5 6)))