branch: externals/dash
commit 081e10a731fc8368141df4fa4dfaaaaeb2ffc0d6
Author: Basil L. Contovounesios <conto...@tcd.ie>
Commit: Basil L. Contovounesios <conto...@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")
