[elpa] externals/dash 081e10a 192/316: Improve take/drop definitions

[ELPA Syncer]

branch: externals/dash
commit 081e10a731fc8368141df4fa4dfaaaaeb2ffc0d6
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Improve take/drop definitions
    
    * dash.el (--take-while): Use push.
    (-take-while, -drop-while, -take-last): Improve docstring.
    (--drop-while, -drop, -drop-last): Return a copy.
    (-take): Optimize in terms of --take-while.
    
    * dev/examples.el (-take, -take-last, -drop, -drop-last)
    (-take-while, -drop-while): Add more tests.
    
    * README.md:
    * dash.info:
    * dash.texi: Regenerate docs.
---
 README.md       |  40 ++++--
 dash.el         |  89 ++++++------
 dash.info       | 414 +++++++++++++++++++++++++++++---------------------------
 dash.texi       |  49 +++++--
 dev/examples.el |  55 ++++++--
 5 files changed, 378 insertions(+), 269 deletions(-)

diff --git a/README.md b/README.md
index 3432319..12d5a73 100644
--- a/README.md
+++ b/README.md
@@ -581,18 +581,23 @@ section is returned.  Defaults to 1.
 
 #### -take `(n list)`
 
-Return a new list of the first `n` items in `list`, or all items if there are 
fewer than `n`.
+Return a copy of the first `n` items in `list`.
+Return a copy of `list` if it contains `n` items or fewer.
+Return nil if `n` is zero or less.
 
 See also: [`-take-last`](#-take-last-n-list)
 
 ```el
 (-take 3 '(1 2 3 4 5)) ;; => '(1 2 3)
 (-take 17 '(1 2 3 4 5)) ;; => '(1 2 3 4 5)
+(-take 0 '(1 2 3 4 5)) ;; => nil
 ```
 
 #### -take-last `(n list)`
 
-Return the last `n` items of `list` in order.
+Return a copy of the last `n` items of `list` in order.
+Return a copy of `list` if it contains `n` items or fewer.
+Return nil if `n` is zero or less.
 
 See also: [`-take`](#-take-n-list)
 
@@ -604,41 +609,54 @@ See also: [`-take`](#-take-n-list)
 
 #### -drop `(n list)`
 
-Return the tail of `list` without the first `n` items.
+Return a copy of the tail of `list` without the first `n` items.
+Return a copy of `list` if `n` is zero or less.
+Return nil if `list` contains `n` items or fewer.
 
 See also: [`-drop-last`](#-drop-last-n-list)
 
-(fn `n` `list`)
-
 ```el
 (-drop 3 '(1 2 3 4 5)) ;; => '(4 5)
-(-drop 17 '(1 2 3 4 5)) ;; => '()
+(-drop 17 '(1 2 3 4 5)) ;; => nil
+(-drop 0 '(1 2 3 4 5)) ;; => '(1 2 3 4 5)
 ```
 
 #### -drop-last `(n list)`
 
-Remove the last `n` items of `list` and return a copy.
+Return a copy of `list` without its last `n` items.
+Return a copy of `list` if `n` is zero or less.
+Return nil if `list` contains `n` items or fewer.
 
 See also: [`-drop`](#-drop-n-list)
 
 ```el
 (-drop-last 3 '(1 2 3 4 5)) ;; => '(1 2)
-(-drop-last 17 '(1 2 3 4 5)) ;; => '()
+(-drop-last 17 '(1 2 3 4 5)) ;; => nil
+(-drop-last 0 '(1 2 3 4 5)) ;; => '(1 2 3 4 5)
 ```
 
 #### -take-while `(pred list)`
 
-Return a new list of successive items from `list` while (`pred` item) returns 
a non-nil value.
+Take successive items from `list` for which `pred` returns non-nil.
+`pred` is a function of one argument.  Return a new list of the
+successive elements from the start of `list` for which `pred` returns
+non-nil.
+
+See also: [`-drop-while`](#-drop-while-pred-list)
 
 ```el
-(-take-while 'even? '(1 2 3 4)) ;; => '()
+(-take-while 'even? '(1 2 3 4)) ;; => nil
 (-take-while 'even? '(2 4 5 6)) ;; => '(2 4)
 (--take-while (< it 4) '(1 2 3 4 3 2 1)) ;; => '(1 2 3)
 ```
 
 #### -drop-while `(pred list)`
 
-Return the tail of `list` starting from the first item for which (`pred` item) 
returns nil.
+Drop successive items from `list` for which `pred` returns non-nil.
+`pred` is a function of one argument.  Return a copy of the tail of
+`list` starting from its first element for which `pred` returns nil.
+
+See also: [`-take-while`](#-take-while-pred-list)
 
 ```el
 (-drop-while 'even? '(1 2 3 4)) ;; => '(1 2 3 4)
diff --git a/dash.el b/dash.el
index 162680c..445208c 100644
--- a/dash.el
+++ b/dash.el
@@ -833,50 +833,21 @@ section is returned.  Defaults to 1."
         (push it new-list)))
     (nreverse new-list)))
 
-(defun -take (n list)
-  "Return a new list of the first N items in LIST, or all items if there are 
fewer than N.
-
-See also: `-take-last'"
-  (declare (pure t) (side-effect-free t))
-  (let (result)
-    (--dotimes n
-      (when list
-        (!cons (car list) result)
-        (!cdr list)))
-    (nreverse result)))
-
-(defun -take-last (n list)
-  "Return the last N items of LIST in order.
-
-See also: `-take'"
-  (declare (pure t) (side-effect-free t))
-  (copy-sequence (last list n)))
-
-(defalias '-drop 'nthcdr
-  "Return the tail of LIST without the first N items.
-
-See also: `-drop-last'
-
-\(fn N LIST)")
-
-(defun -drop-last (n list)
-  "Remove the last N items of LIST and return a copy.
-
-See also: `-drop'"
-  ;; No alias because we don't want magic optional argument
-  (declare (pure t) (side-effect-free t))
-  (butlast list n))
-
 (defmacro --take-while (form list)
   "Anaphoric form of `-take-while'."
   (declare (debug (form form)))
   (let ((r (make-symbol "result")))
     `(let (,r)
-       (--each-while ,list ,form (!cons it ,r))
+       (--each-while ,list ,form (push it ,r))
        (nreverse ,r))))
 
 (defun -take-while (pred list)
-  "Return a new list of successive items from LIST while (PRED item) returns a 
non-nil value."
+  "Take successive items from LIST for which PRED returns non-nil.
+PRED is a function of one argument.  Return a new list of the
+successive elements from the start of LIST for which PRED returns
+non-nil.
+
+See also: `-drop-while'"
   (--take-while (funcall pred it) list))
 
 (defmacro --drop-while (form list)
@@ -884,14 +855,52 @@ See also: `-drop'"
   (declare (debug (form form)))
   (let ((l (make-symbol "list")))
     `(let ((,l ,list))
-       (while (and ,l (let ((it (car ,l))) ,form))
-         (!cdr ,l))
-       ,l)))
+       (--each-while ,l ,form (pop ,l))
+       (copy-sequence ,l))))
 
 (defun -drop-while (pred list)
-  "Return the tail of LIST starting from the first item for which (PRED item) 
returns nil."
+  "Drop successive items from LIST for which PRED returns non-nil.
+PRED is a function of one argument.  Return a copy of the tail of
+LIST starting from its first element for which PRED returns nil.
+
+See also: `-take-while'"
   (--drop-while (funcall pred it) list))
 
+(defun -take (n list)
+  "Return a copy of the first N items in LIST.
+Return a copy of LIST if it contains N items or fewer.
+Return nil if N is zero or less.
+
+See also: `-take-last'"
+  (declare (pure t) (side-effect-free t))
+  (--take-while (< it-index n) list))
+
+(defun -take-last (n list)
+  "Return a copy of the last N items of LIST in order.
+Return a copy of LIST if it contains N items or fewer.
+Return nil if N is zero or less.
+
+See also: `-take'"
+  (declare (pure t) (side-effect-free t))
+  (copy-sequence (last list n)))
+
+(defun -drop (n list)
+  "Return a copy of the tail of LIST without the first N items.
+Return a copy of LIST if N is zero or less.
+Return nil if LIST contains N items or fewer.
+
+See also: `-drop-last'"
+  (copy-sequence (nthcdr n list)))
+
+(defun -drop-last (n list)
+  "Return a copy of LIST without its last N items.
+Return a copy of LIST if N is zero or less.
+Return nil if LIST contains N items or fewer.
+
+See also: `-drop'"
+  (declare (pure t) (side-effect-free t))
+  (nbutlast (copy-sequence list) n))
+
 (defun -split-at (n list)
   "Return a list of ((-take N LIST) (-drop N LIST)), in no more than one pass 
through the list."
   (declare (pure t) (side-effect-free t))
diff --git a/dash.info b/dash.info
index 1e6a14b..4bda4b3 100644
--- a/dash.info
+++ b/dash.info
@@ -437,8 +437,9 @@ Functions returning a sublist of the original list.
               ⇒ '(2 4 6 8)
 
  -- Function: -take (n list)
-     Return a new list of the first N items in LIST, or all items if
-     there are fewer than N.
+     Return a copy of the first N items in LIST.  Return a copy of
+     LIST if it contains N items or fewer.  Return nil if N is zero or
+     less.
 
      See also: ‘-take-last’ (*note -take-last::)
 
@@ -446,9 +447,13 @@ Functions returning a sublist of the original list.
               ⇒ '(1 2 3)
           (-take 17 '(1 2 3 4 5))
               ⇒ '(1 2 3 4 5)
+          (-take 0 '(1 2 3 4 5))
+              ⇒ nil
 
  -- Function: -take-last (n list)
-     Return the last N items of LIST in order.
+     Return a copy of the last N items of LIST in order.  Return a
+     copy of LIST if it contains N items or fewer.  Return nil if N is
+     zero or less.
 
      See also: ‘-take’ (*note -take::)
 
@@ -460,41 +465,54 @@ Functions returning a sublist of the original list.
               ⇒ '(5)
 
  -- Function: -drop (n list)
-     Return the tail of LIST without the first N items.
+     Return a copy of the tail of LIST without the first N items.
+     Return a copy of LIST if N is zero or less.  Return nil if LIST
+     contains N items or fewer.
 
      See also: ‘-drop-last’ (*note -drop-last::)
 
-     (fn N LIST)
-
           (-drop 3 '(1 2 3 4 5))
               ⇒ '(4 5)
           (-drop 17 '(1 2 3 4 5))
-              ⇒ '()
+              ⇒ nil
+          (-drop 0 '(1 2 3 4 5))
+              ⇒ '(1 2 3 4 5)
 
  -- Function: -drop-last (n list)
-     Remove the last N items of LIST and return a copy.
+     Return a copy of LIST without its last N items.  Return a copy of
+     LIST if N is zero or less.  Return nil if LIST contains N items
+     or fewer.
 
      See also: ‘-drop’ (*note -drop::)
 
           (-drop-last 3 '(1 2 3 4 5))
               ⇒ '(1 2)
           (-drop-last 17 '(1 2 3 4 5))
-              ⇒ '()
+              ⇒ nil
+          (-drop-last 0 '(1 2 3 4 5))
+              ⇒ '(1 2 3 4 5)
 
  -- Function: -take-while (pred list)
-     Return a new list of successive items from LIST while (PRED item)
-     returns a non-nil value.
+     Take successive items from LIST for which PRED returns non-nil.
+     PRED is a function of one argument.  Return a new list of the
+     successive elements from the start of LIST for which PRED returns
+     non-nil.
+
+     See also: ‘-drop-while’ (*note -drop-while::)
 
           (-take-while 'even? '(1 2 3 4))
-              ⇒ '()
+              ⇒ nil
           (-take-while 'even? '(2 4 5 6))
               ⇒ '(2 4)
           (--take-while (< it 4) '(1 2 3 4 3 2 1))
               ⇒ '(1 2 3)
 
  -- Function: -drop-while (pred list)
-     Return the tail of LIST starting from the first item for which
-     (PRED item) returns nil.
+     Drop successive items from LIST for which PRED returns non-nil.
+     PRED is a function of one argument.  Return a copy of the tail of
+     LIST starting from its first element for which PRED returns nil.
+
+     See also: ‘-take-while’ (*note -take-while::)
 
           (-drop-while 'even? '(1 2 3 4))
               ⇒ '(1 2 3 4)
@@ -3039,9 +3057,9 @@ Index
 * -distinct:                             Set operations.    (line  62)
 * -dotimes:                              Side-effects.      (line  63)
 * -doto:                                 Side-effects.      (line  72)
-* -drop:                                 Sublist selection. (line 125)
-* -drop-last:                            Sublist selection. (line 137)
-* -drop-while:                           Sublist selection. (line 158)
+* -drop:                                 Sublist selection. (line 130)
+* -drop-last:                            Sublist selection. (line 144)
+* -drop-while:                           Sublist selection. (line 173)
 * -each:                                 Side-effects.      (line   8)
 * -each-indexed:                         Side-effects.      (line  30)
 * -each-r:                               Side-effects.      (line  43)
@@ -3166,9 +3184,9 @@ Index
 * -same-items?:                          Predicates.        (line  72)
 * -second-item:                          Other list operations.
                                                             (line 287)
-* -select-by-indices:                    Sublist selection. (line 169)
-* -select-column:                        Sublist selection. (line 199)
-* -select-columns:                       Sublist selection. (line 180)
+* -select-by-indices:                    Sublist selection. (line 187)
+* -select-column:                        Sublist selection. (line 217)
+* -select-columns:                       Sublist selection. (line 198)
 * -separate:                             Partitioning.      (line  63)
 * -setq:                                 Binding.           (line 276)
 * -slice:                                Sublist selection. (line  86)
@@ -3194,8 +3212,8 @@ Index
                                                             (line 210)
 * -tails:                                Reductions.        (line 214)
 * -take:                                 Sublist selection. (line 102)
-* -take-last:                            Sublist selection. (line 113)
-* -take-while:                           Sublist selection. (line 147)
+* -take-last:                            Sublist selection. (line 116)
+* -take-while:                           Sublist selection. (line 158)
 * -third-item:                           Other list operations.
                                                             (line 299)
 * -tree-map:                             Tree operations.   (line  28)
@@ -3249,182 +3267,182 @@ Ref: -remove-item12332
 Ref: -non-nil12727
 Ref: -slice12886
 Ref: -take13418
-Ref: -take-last13726
-Ref: -drop14049
-Ref: -drop-last14322
-Ref: -take-while14582
-Ref: -drop-while14932
-Ref: -select-by-indices15288
-Ref: -select-columns15802
-Ref: -select-column16507
-Node: List to list16970
-Ref: -keep17162
-Ref: -concat17665
-Ref: -flatten17962
-Ref: -flatten-n18721
-Ref: -replace19108
-Ref: -replace-first19571
-Ref: -replace-last20068
-Ref: -insert-at20558
-Ref: -replace-at20885
-Ref: -update-at21280
-Ref: -remove-at21771
-Ref: -remove-at-indices22259
-Node: Reductions22841
-Ref: -reduce-from23010
-Ref: -reduce-r-from23776
-Ref: -reduce24543
-Ref: -reduce-r25277
-Ref: -reductions-from26147
-Ref: -reductions-r-from26862
-Ref: -reductions27587
-Ref: -reductions-r28212
-Ref: -count28847
-Ref: -sum29071
-Ref: -running-sum29260
-Ref: -product29553
-Ref: -running-product29762
-Ref: -inits30075
-Ref: -tails30323
-Ref: -common-prefix30570
-Ref: -common-suffix30867
-Ref: -min31164
-Ref: -min-by31390
-Ref: -max31913
-Ref: -max-by32138
-Node: Unfolding32666
-Ref: -iterate32905
-Ref: -unfold33350
-Node: Predicates34158
-Ref: -any?34282
-Ref: -all?34602
-Ref: -none?34932
-Ref: -only-some?35234
-Ref: -contains?35719
-Ref: -same-items?36108
-Ref: -is-prefix?36493
-Ref: -is-suffix?36816
-Ref: -is-infix?37139
-Node: Partitioning37493
-Ref: -split-at37681
-Ref: -split-with37966
-Ref: -split-on38369
-Ref: -split-when39045
-Ref: -separate39685
-Ref: -partition40127
-Ref: -partition-all40579
-Ref: -partition-in-steps41007
-Ref: -partition-all-in-steps41504
-Ref: -partition-by41989
-Ref: -partition-by-header42371
-Ref: -partition-after-pred42975
-Ref: -partition-before-pred43319
-Ref: -partition-before-item43670
-Ref: -partition-after-item43981
-Ref: -group-by44287
-Node: Indexing44724
-Ref: -elem-index44926
-Ref: -elem-indices45321
-Ref: -find-index45704
-Ref: -find-last-index46193
-Ref: -find-indices46697
-Ref: -grade-up47105
-Ref: -grade-down47508
-Node: Set operations47918
-Ref: -union48101
-Ref: -difference48543
-Ref: -intersection48960
-Ref: -powerset49397
-Ref: -permutations49610
-Ref: -distinct49910
-Node: Other list operations50288
-Ref: -rotate50513
-Ref: -repeat50883
-Ref: -cons*51146
-Ref: -snoc51533
-Ref: -interpose51946
-Ref: -interleave52244
-Ref: -zip-with52613
-Ref: -zip53330
-Ref: -zip-lists54162
-Ref: -zip-fill54863
-Ref: -unzip55186
-Ref: -cycle55931
-Ref: -pad56338
-Ref: -table56661
-Ref: -table-flat57451
-Ref: -first58460
-Ref: -some58832
-Ref: -last59141
-Ref: -first-item59475
-Ref: -second-item59891
-Ref: -third-item60171
-Ref: -fourth-item60449
-Ref: -fifth-item60715
-Ref: -last-item60977
-Ref: -butlast61269
-Ref: -sort61516
-Ref: -list62004
-Ref: -fix62335
-Node: Tree operations62875
-Ref: -tree-seq63071
-Ref: -tree-map63929
-Ref: -tree-map-nodes64372
-Ref: -tree-reduce65227
-Ref: -tree-reduce-from66109
-Ref: -tree-mapreduce66710
-Ref: -tree-mapreduce-from67570
-Ref: -clone68856
-Node: Threading macros69184
-Ref: ->69329
-Ref: ->>69821
-Ref: -->70326
-Ref: -as->70887
-Ref: -some->71342
-Ref: -some->>71716
-Ref: -some-->72152
-Node: Binding72623
-Ref: -when-let72835
-Ref: -when-let*73320
-Ref: -if-let73848
-Ref: -if-let*74243
-Ref: -let74860
-Ref: -let*80948
-Ref: -lambda81889
-Ref: -setq82691
-Node: Side-effects83507
-Ref: -each83701
-Ref: -each-while84108
-Ref: -each-indexed84566
-Ref: -each-r85084
-Ref: -each-r-while85517
-Ref: -dotimes85892
-Ref: -doto86195
-Ref: --doto86622
-Node: Destructive operations86897
-Ref: !cons87070
-Ref: !cdr87276
-Node: Function combinators87471
-Ref: -partial87745
-Ref: -rpartial88138
-Ref: -juxt88540
-Ref: -compose88972
-Ref: -applify89530
-Ref: -on89961
-Ref: -flip90487
-Ref: -const90799
-Ref: -cut91143
-Ref: -not91629
-Ref: -orfn91939
-Ref: -andfn92373
-Ref: -iteratefn92868
-Ref: -fixfn93571
-Ref: -prodfn95140
-Node: Development96209
-Node: Contribute96558
-Node: Changes97306
-Node: Contributors100305
-Node: Index101929
+Ref: -take-last13832
+Ref: -drop14265
+Ref: -drop-last14695
+Ref: -take-while15123
+Ref: -drop-while15649
+Ref: -select-by-indices16173
+Ref: -select-columns16687
+Ref: -select-column17392
+Node: List to list17855
+Ref: -keep18047
+Ref: -concat18550
+Ref: -flatten18847
+Ref: -flatten-n19606
+Ref: -replace19993
+Ref: -replace-first20456
+Ref: -replace-last20953
+Ref: -insert-at21443
+Ref: -replace-at21770
+Ref: -update-at22165
+Ref: -remove-at22656
+Ref: -remove-at-indices23144
+Node: Reductions23726
+Ref: -reduce-from23895
+Ref: -reduce-r-from24661
+Ref: -reduce25428
+Ref: -reduce-r26162
+Ref: -reductions-from27032
+Ref: -reductions-r-from27747
+Ref: -reductions28472
+Ref: -reductions-r29097
+Ref: -count29732
+Ref: -sum29956
+Ref: -running-sum30145
+Ref: -product30438
+Ref: -running-product30647
+Ref: -inits30960
+Ref: -tails31208
+Ref: -common-prefix31455
+Ref: -common-suffix31752
+Ref: -min32049
+Ref: -min-by32275
+Ref: -max32798
+Ref: -max-by33023
+Node: Unfolding33551
+Ref: -iterate33790
+Ref: -unfold34235
+Node: Predicates35043
+Ref: -any?35167
+Ref: -all?35487
+Ref: -none?35817
+Ref: -only-some?36119
+Ref: -contains?36604
+Ref: -same-items?36993
+Ref: -is-prefix?37378
+Ref: -is-suffix?37701
+Ref: -is-infix?38024
+Node: Partitioning38378
+Ref: -split-at38566
+Ref: -split-with38851
+Ref: -split-on39254
+Ref: -split-when39930
+Ref: -separate40570
+Ref: -partition41012
+Ref: -partition-all41464
+Ref: -partition-in-steps41892
+Ref: -partition-all-in-steps42389
+Ref: -partition-by42874
+Ref: -partition-by-header43256
+Ref: -partition-after-pred43860
+Ref: -partition-before-pred44204
+Ref: -partition-before-item44555
+Ref: -partition-after-item44866
+Ref: -group-by45172
+Node: Indexing45609
+Ref: -elem-index45811
+Ref: -elem-indices46206
+Ref: -find-index46589
+Ref: -find-last-index47078
+Ref: -find-indices47582
+Ref: -grade-up47990
+Ref: -grade-down48393
+Node: Set operations48803
+Ref: -union48986
+Ref: -difference49428
+Ref: -intersection49845
+Ref: -powerset50282
+Ref: -permutations50495
+Ref: -distinct50795
+Node: Other list operations51173
+Ref: -rotate51398
+Ref: -repeat51768
+Ref: -cons*52031
+Ref: -snoc52418
+Ref: -interpose52831
+Ref: -interleave53129
+Ref: -zip-with53498
+Ref: -zip54215
+Ref: -zip-lists55047
+Ref: -zip-fill55748
+Ref: -unzip56071
+Ref: -cycle56816
+Ref: -pad57223
+Ref: -table57546
+Ref: -table-flat58336
+Ref: -first59345
+Ref: -some59717
+Ref: -last60026
+Ref: -first-item60360
+Ref: -second-item60776
+Ref: -third-item61056
+Ref: -fourth-item61334
+Ref: -fifth-item61600
+Ref: -last-item61862
+Ref: -butlast62154
+Ref: -sort62401
+Ref: -list62889
+Ref: -fix63220
+Node: Tree operations63760
+Ref: -tree-seq63956
+Ref: -tree-map64814
+Ref: -tree-map-nodes65257
+Ref: -tree-reduce66112
+Ref: -tree-reduce-from66994
+Ref: -tree-mapreduce67595
+Ref: -tree-mapreduce-from68455
+Ref: -clone69741
+Node: Threading macros70069
+Ref: ->70214
+Ref: ->>70706
+Ref: -->71211
+Ref: -as->71772
+Ref: -some->72227
+Ref: -some->>72601
+Ref: -some-->73037
+Node: Binding73508
+Ref: -when-let73720
+Ref: -when-let*74205
+Ref: -if-let74733
+Ref: -if-let*75128
+Ref: -let75745
+Ref: -let*81833
+Ref: -lambda82774
+Ref: -setq83576
+Node: Side-effects84392
+Ref: -each84586
+Ref: -each-while84993
+Ref: -each-indexed85451
+Ref: -each-r85969
+Ref: -each-r-while86402
+Ref: -dotimes86777
+Ref: -doto87080
+Ref: --doto87507
+Node: Destructive operations87782
+Ref: !cons87955
+Ref: !cdr88161
+Node: Function combinators88356
+Ref: -partial88630
+Ref: -rpartial89023
+Ref: -juxt89425
+Ref: -compose89857
+Ref: -applify90415
+Ref: -on90846
+Ref: -flip91372
+Ref: -const91684
+Ref: -cut92028
+Ref: -not92514
+Ref: -orfn92824
+Ref: -andfn93258
+Ref: -iteratefn93753
+Ref: -fixfn94456
+Ref: -prodfn96025
+Node: Development97094
+Node: Contribute97443
+Node: Changes98191
+Node: Contributors101190
+Node: Index102814
 
 End Tag Table
 
diff --git a/dash.texi b/dash.texi
index 8a3b73b..7def1d4 100644
--- a/dash.texi
+++ b/dash.texi
@@ -597,7 +597,9 @@ section is returned.  Defaults to 1.
 
 @anchor{-take}
 @defun -take (n list)
-Return a new list of the first @var{n} items in @var{list}, or all items if 
there are fewer than @var{n}.
+Return a copy of the first @var{n} items in @var{list}.
+Return a copy of @var{list} if it contains @var{n} items or fewer.
+Return nil if @var{n} is zero or less.
 
 See also: @code{-take-last} (@pxref{-take-last})
 
@@ -610,12 +612,18 @@ See also: @code{-take-last} (@pxref{-take-last})
 (-take 17 '(1 2 3 4 5))
     @result{} '(1 2 3 4 5)
 @end group
+@group
+(-take 0 '(1 2 3 4 5))
+    @result{} nil
+@end group
 @end example
 @end defun
 
 @anchor{-take-last}
 @defun -take-last (n list)
-Return the last @var{n} items of @var{list} in order.
+Return a copy of the last @var{n} items of @var{list} in order.
+Return a copy of @var{list} if it contains @var{n} items or fewer.
+Return nil if @var{n} is zero or less.
 
 See also: @code{-take} (@pxref{-take})
 
@@ -637,12 +645,12 @@ See also: @code{-take} (@pxref{-take})
 
 @anchor{-drop}
 @defun -drop (n list)
-Return the tail of @var{list} without the first @var{n} items.
+Return a copy of the tail of @var{list} without the first @var{n} items.
+Return a copy of @var{list} if @var{n} is zero or less.
+Return nil if @var{list} contains @var{n} items or fewer.
 
 See also: @code{-drop-last} (@pxref{-drop-last})
 
-(fn @var{n} @var{list})
-
 @example
 @group
 (-drop 3 '(1 2 3 4 5))
@@ -650,14 +658,20 @@ See also: @code{-drop-last} (@pxref{-drop-last})
 @end group
 @group
 (-drop 17 '(1 2 3 4 5))
-    @result{} '()
+    @result{} nil
+@end group
+@group
+(-drop 0 '(1 2 3 4 5))
+    @result{} '(1 2 3 4 5)
 @end group
 @end example
 @end defun
 
 @anchor{-drop-last}
 @defun -drop-last (n list)
-Remove the last @var{n} items of @var{list} and return a copy.
+Return a copy of @var{list} without its last @var{n} items.
+Return a copy of @var{list} if @var{n} is zero or less.
+Return nil if @var{list} contains @var{n} items or fewer.
 
 See also: @code{-drop} (@pxref{-drop})
 
@@ -668,19 +682,28 @@ See also: @code{-drop} (@pxref{-drop})
 @end group
 @group
 (-drop-last 17 '(1 2 3 4 5))
-    @result{} '()
+    @result{} nil
+@end group
+@group
+(-drop-last 0 '(1 2 3 4 5))
+    @result{} '(1 2 3 4 5)
 @end group
 @end example
 @end defun
 
 @anchor{-take-while}
 @defun -take-while (pred list)
-Return a new list of successive items from @var{list} while (@var{pred} item) 
returns a non-nil value.
+Take successive items from @var{list} for which @var{pred} returns non-nil.
+@var{pred} is a function of one argument.  Return a new list of the
+successive elements from the start of @var{list} for which @var{pred} returns
+non-nil.
+
+See also: @code{-drop-while} (@pxref{-drop-while})
 
 @example
 @group
 (-take-while 'even? '(1 2 3 4))
-    @result{} '()
+    @result{} nil
 @end group
 @group
 (-take-while 'even? '(2 4 5 6))
@@ -695,7 +718,11 @@ Return a new list of successive items from @var{list} 
while (@var{pred} item) re
 
 @anchor{-drop-while}
 @defun -drop-while (pred list)
-Return the tail of @var{list} starting from the first item for which 
(@var{pred} item) returns nil.
+Drop successive items from @var{list} for which @var{pred} returns non-nil.
+@var{pred} is a function of one argument.  Return a copy of the tail of
+@var{list} starting from its first element for which @var{pred} returns nil.
+
+See also: @code{-take-while} (@pxref{-take-while})
 
 @example
 @group
diff --git a/dev/examples.el b/dev/examples.el
index 04e766f..11b0842 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -174,33 +174,70 @@ new list."
 
   (defexamples -take
     (-take 3 '(1 2 3 4 5)) => '(1 2 3)
-    (-take 17 '(1 2 3 4 5)) => '(1 2 3 4 5))
+    (-take 17 '(1 2 3 4 5)) => '(1 2 3 4 5)
+    (-take 0 '(1 2 3 4 5)) => ()
+    (-take 0 ()) => ()
+    (-take -1 ()) => ()
+    (-take -1 '(1)) => ()
+    (-take 1 ()) => ()
+    (let ((l (list 1 2))) (eq (-take 3 l) l)) => nil)
 
   (defexamples -take-last
     (-take-last 3 '(1 2 3 4 5)) => '(3 4 5)
     (-take-last 17 '(1 2 3 4 5)) => '(1 2 3 4 5)
     (-take-last 1 '(1 2 3 4 5)) => '(5)
-    (let ((l '(1 2 3 4 5)))
-      (setcar (-take-last 2 l) 1)
-      l) => '(1 2 3 4 5))
+    (-take-last 0 '(1)) => ()
+    (-take-last 0 ()) => ()
+    (-take-last -1 ()) => ()
+    (-take-last -1 '(1)) => ()
+    (let ((l (list 1 2))) (setcar (-take-last 1 l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (eq (-take-last 3 l) l)) => nil)
 
   (defexamples -drop
     (-drop 3 '(1 2 3 4 5)) => '(4 5)
-    (-drop 17 '(1 2 3 4 5)) => '())
+    (-drop 17 '(1 2 3 4 5)) => ()
+    (-drop 0 '(1 2 3 4 5)) => '(1 2 3 4 5)
+    (-drop 0 ()) => ()
+    (-drop -1 ()) => ()
+    (-drop -1 '(1)) => '(1)
+    (-drop 1 ()) => ()
+    (let ((l (list 1 2))) (setcar (-drop 1 l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (eq (-drop 0 l) l)) => nil)
 
   (defexamples -drop-last
     (-drop-last 3 '(1 2 3 4 5)) => '(1 2)
-    (-drop-last 17 '(1 2 3 4 5)) => '())
+    (-drop-last 17 '(1 2 3 4 5)) => ()
+    (-drop-last 0 '(1 2 3 4 5)) => '(1 2 3 4 5)
+    (-drop-last 0 ()) => ()
+    (-drop-last -1 ()) => ()
+    (-drop-last -1 '(1)) => '(1)
+    (-drop-last 1 ()) => ()
+    (let ((l (list 1 2))) (setcar (-drop-last 1 l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (eq (-drop-last 0 l) l)) => nil)
 
   (defexamples -take-while
-    (-take-while 'even? '(1 2 3 4)) => '()
+    (-take-while 'even? '(1 2 3 4)) => ()
     (-take-while 'even? '(2 4 5 6)) => '(2 4)
-    (--take-while (< it 4) '(1 2 3 4 3 2 1)) => '(1 2 3))
+    (--take-while (< it 4) '(1 2 3 4 3 2 1)) => '(1 2 3)
+    (--take-while t ()) => ()
+    (--take-while nil ()) => ()
+    (--take-while nil '(1)) => ()
+    (--take-while t '(1)) => '(1)
+    (--take-while t '(1 2)) => '(1 2)
+    (let ((l (list 1 2))) (eq (--take-while t l) l)) => nil)
 
   (defexamples -drop-while
     (-drop-while 'even? '(1 2 3 4)) => '(1 2 3 4)
     (-drop-while 'even? '(2 4 5 6)) => '(5 6)
-    (--drop-while (< it 4) '(1 2 3 4 3 2 1)) => '(4 3 2 1))
+    (--drop-while (< it 4) '(1 2 3 4 3 2 1)) => '(4 3 2 1)
+    (--drop-while t ()) => ()
+    (--drop-while nil ()) => ()
+    (--drop-while nil '(1)) => '(1)
+    (--drop-while nil '(1 2)) => '(1 2)
+    (--drop-while t '(1)) => ()
+    (--drop-while t '(1 2)) => ()
+    (let ((l (list 1 2))) (setcar (-drop-while 'odd? l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (eq (--drop-while nil l) l)) => nil)
 
   (defexamples -select-by-indices
     (-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" 
"t" "o" "r")) => '("c" "o" "l" "o" "r")