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.
5 years ago · 081e10a731
parent 78fee36e7e
commit 081e10a731
5 changed files with 378 additions and 269 deletions
--- 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)
--- 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))
--- 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

--- 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
--- 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")