[elpa] externals/dash c61fc34 417/426: Add -remove-first/last, -map-first/last, -replace-first/last

[Phillip Lord]

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

    Add -remove-first/last, -map-first/last, -replace-first/last
---
 README.md       |   86 ++++++++++++++++++++++++++++++++++
 dash.el         |   94 +++++++++++++++++++++++++++++++++++++
 dash.texi       |  140 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 dev/examples.el |   40 ++++++++++++++++
 4 files changed, 360 insertions(+), 0 deletions(-)

diff --git a/README.md b/README.md
index 78ac7d5..164b7c1 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,8 @@ new list.
 
 * [-map](#-map-fn-list) `(fn list)`
 * [-map-when](#-map-when-pred-rep-list) `(pred rep list)`
+* [-map-first](#-map-first-pred-rep-list) `(pred rep list)`
+* [-map-last](#-map-last-pred-rep-list) `(pred rep list)`
 * [-map-indexed](#-map-indexed-fn-list) `(fn list)`
 * [-annotate](#-annotate-fn-list) `(fn list)`
 * [-splice](#-splice-pred-fun-list) `(pred fun list)`
@@ -59,6 +61,8 @@ Functions returning a sublist of the original list.
 
 * [-filter](#-filter-pred-list) `(pred list)`
 * [-remove](#-remove-pred-list) `(pred list)`
+* [-remove-first](#-remove-first-pred-list) `(pred list)`
+* [-remove-last](#-remove-last-pred-list) `(pred list)`
 * [-remove-item](#-remove-item-item-list) `(item list)`
 * [-non-nil](#-non-nil-list) `(list)`
 * [-slice](#-slice-list-from-optional-to-step) `(list from &optional to step)`
@@ -78,6 +82,8 @@ Bag of various functions which modify input list.
 * [-flatten](#-flatten-l) `(l)`
 * [-flatten-n](#-flatten-n-num-list) `(num list)`
 * [-replace](#-replace-old-new-list) `(old new list)`
+* [-replace-first](#-replace-first-old-new-list) `(old new list)`
+* [-replace-last](#-replace-last-old-new-list) `(old new list)`
 * [-insert-at](#-insert-at-n-x-list) `(n x list)`
 * [-replace-at](#-replace-at-n-x-list) `(n x list)`
 * [-update-at](#-update-at-n-func-list) `(n func list)`
@@ -318,6 +324,30 @@ See also: [`-update-at`](#-update-at-n-func-list)
 (--map-when (= it 2) 17 '(1 2 3 4)) ;; => '(1 17 3 4)
 ```
 
+#### -map-first `(pred rep list)`
+
+Replace first item in `list` satisfying `pred` with result of `rep` called on 
this item.
+
+See also: [`-map-when`](#-map-when-pred-rep-list), 
[`-replace-first`](#-replace-first-old-new-list)
+
+```el
+(-map-first 'even? 'square '(1 2 3 4)) ;; => '(1 4 3 4)
+(--map-first (> it 2) (* it it) '(1 2 3 4)) ;; => '(1 2 9 4)
+(--map-first (= it 2) 17 '(1 2 3 2)) ;; => '(1 17 3 2)
+```
+
+#### -map-last `(pred rep list)`
+
+Replace first item in `list` satisfying `pred` with result of `rep` called on 
this item.
+
+See also: [`-map-when`](#-map-when-pred-rep-list), 
[`-replace-last`](#-replace-last-old-new-list)
+
+```el
+(-map-last 'even? 'square '(1 2 3 4)) ;; => '(1 2 3 16)
+(--map-last (> it 2) (* it it) '(1 2 3 4)) ;; => '(1 2 3 16)
+(--map-last (= it 2) 17 '(1 2 3 2)) ;; => '(1 2 3 17)
+```
+
 #### -map-indexed `(fn list)`
 
 Return a new list consisting of the result of (`fn` index item) for each item 
in `list`.
@@ -419,6 +449,34 @@ Alias: `-reject`
 (--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
 ```
 
+#### -remove-first `(pred list)`
+
+Return a new list with the first item matching `pred` removed.
+
+Alias: `-reject-first`
+
+See also: [`-remove`](#-remove-pred-list), 
[`-map-first`](#-map-first-pred-rep-list)
+
+```el
+(-remove-first 'even? '(1 3 5 4 7 8 10)) ;; => '(1 3 5 7 8 10)
+(-remove-first 'stringp '(1 2 "first" "second" "third")) ;; => '(1 2 "second" 
"third")
+(--remove-first (> it 3) '(1 2 3 4 5 6 7 8 9 10)) ;; => '(1 2 3 5 6 7 8 9 10)
+```
+
+#### -remove-last `(pred list)`
+
+Return a new list with the last item matching `pred` removed.
+
+Alias: `-reject-last`
+
+See also: [`-remove`](#-remove-pred-list), 
[`-map-last`](#-map-last-pred-rep-list)
+
+```el
+(-remove-last 'even? '(1 3 5 4 7 8 10 11)) ;; => '(1 3 5 4 7 8 11)
+(-remove-last 'stringp '(1 2 "last" "second" "third")) ;; => '(1 2 "last" 
"second")
+(--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10)) ;; => '(1 2 3 4 5 6 7 8 9)
+```
+
 #### -remove-item `(item list)`
 
 Remove all occurences of `item` from `list`.
@@ -570,6 +628,34 @@ See also: [`-replace-at`](#-replace-at-n-x-list)
 (-replace 1 2 nil) ;; => nil
 ```
 
+#### -replace-first `(old new list)`
+
+Replace the first occurence of `old` with `new` in `list`.
+
+Elements are compared using `equal`.
+
+See also: [`-map-first`](#-map-first-pred-rep-list)
+
+```el
+(-replace-first 1 "1" '(1 2 3 4 3 2 1)) ;; => '("1" 2 3 4 3 2 1)
+(-replace-first "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; 
=> '("a" "nice" "bar" "sentence" "about" "foo")
+(-replace-first 1 2 nil) ;; => nil
+```
+
+#### -replace-last `(old new list)`
+
+Replace the last occurence of `old` with `new` in `list`.
+
+Elements are compared using `equal`.
+
+See also: [`-map-last`](#-map-last-pred-rep-list)
+
+```el
+(-replace-last 1 "1" '(1 2 3 4 3 2 1)) ;; => '(1 2 3 4 3 2 "1")
+(-replace-last "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; => 
'("a" "nice" "foo" "sentence" "about" "bar")
+(-replace-last 1 2 nil) ;; => nil
+```
+
 #### -insert-at `(n x list)`
 
 Return a list with `x` inserted into `list` at position `n`.
diff --git a/dash.el b/dash.el
index 000d575..6cfea03 100644
--- a/dash.el
+++ b/dash.el
@@ -226,6 +226,44 @@ Alias: `-reject'"
 (defalias '-reject '-remove)
 (defalias '--reject '--remove)
 
+(defun -remove-first (pred list)
+  "Return a new list with the first item matching PRED removed.
+
+Alias: `-reject-first'
+
+See also: `-remove', `-map-first'"
+  (let (front)
+    (while (and list (not (funcall pred (car list))))
+      (push (car list) front)
+      (!cdr list))
+    (if list
+        (-concat (nreverse front) (cdr list))
+      (nreverse front))))
+
+(defmacro --remove-first (form list)
+  "Anaphoric form of `-remove-first'."
+  (declare (debug (form form)))
+  `(-remove-first (lambda (it) ,form) ,list))
+
+(defalias '-reject-first '-remove-first)
+(defalias '--reject-first '--remove-first)
+
+(defun -remove-last (pred list)
+  "Return a new list with the last item matching PRED removed.
+
+Alias: `-reject-last'
+
+See also: `-remove', `-map-last'"
+  (nreverse (-remove-first pred (nreverse list))))
+
+(defmacro --remove-last (form list)
+  "Anaphoric form of `-remove-last'."
+  (declare (debug (form form)))
+  `(-remove-last (lambda (it) ,form) ,list))
+
+(defalias '-reject-last '-remove-last)
+(defalias '--reject-last '--remove-last)
+
 (defun -remove-item (item list)
   "Remove all occurences of ITEM from LIST.
 
@@ -287,6 +325,32 @@ See also: `-update-at'"
 (defalias '-replace-where '-map-when)
 (defalias '--replace-where '--map-when)
 
+(defun -map-first (pred rep list)
+  "Replace first item in LIST satisfying PRED with result of REP called on 
this item.
+
+See also: `-map-when', `-replace-first'"
+  (let (front)
+    (while (and list (not (funcall pred (car list))))
+      (push (car list) front)
+      (!cdr list))
+    (if list
+        (-concat (nreverse front) (cons (funcall rep (car list)) (cdr list)))
+      (nreverse front))))
+
+(defmacro --map-first (pred rep list)
+  "Anaphoric form of `-map-first'."
+  `(-map-first (lambda (it) ,pred) (lambda (it) ,rep) ,list))
+
+(defun -map-last (pred rep list)
+  "Replace first item in LIST satisfying PRED with result of REP called on 
this item.
+
+See also: `-map-when', `-replace-last'"
+  (nreverse (-map-first pred rep (nreverse list))))
+
+(defmacro --map-last (pred rep list)
+  "Anaphoric form of `-map-last'."
+  `(-map-last (lambda (it) ,pred) (lambda (it) ,rep) ,list))
+
 (defun -replace (old new list)
   "Replace all OLD items in LIST with NEW.
 
@@ -295,6 +359,22 @@ Elements are compared using `equal'.
 See also: `-replace-at'"
   (--map-when (equal it old) new list))
 
+(defun -replace-first (old new list)
+  "Replace the first occurence of OLD with NEW in LIST.
+
+Elements are compared using `equal'.
+
+See also: `-map-first'"
+  (--map-first (equal old it) new list))
+
+(defun -replace-last (old new list)
+  "Replace the last occurence of OLD with NEW in LIST.
+
+Elements are compared using `equal'.
+
+See also: `-map-last'"
+  (--map-last (equal old it) new list))
+
 (defmacro --mapcat (form list)
   "Anaphoric form of `-mapcat'."
   (declare (debug (form form)))
@@ -1991,6 +2071,14 @@ structure such as plist or alist."
                              "--remove"
                              "-reject"
                              "--reject"
+                             "-remove-first"
+                             "--remove-first"
+                             "-reject-first"
+                             "--reject-first"
+                             "-remove-last"
+                             "--remove-last"
+                             "-reject-last"
+                             "--reject-last"
                              "-remove-item"
                              "-non-nil"
                              "-keep"
@@ -2005,7 +2093,13 @@ structure such as plist or alist."
                              "--map-when"
                              "-replace-where"
                              "--replace-where"
+                             "-map-first"
+                             "--map-first"
+                             "-map-last"
+                             "--map-last"
                              "-replace"
+                             "-replace-first"
+                             "-replace-last"
                              "-flatten"
                              "-flatten-n"
                              "-concat"
diff --git a/dash.texi b/dash.texi
index 08f5b22..a6f5a1d 100644
--- a/dash.texi
+++ b/dash.texi
@@ -250,6 +250,50 @@ See also: @code{-update-at} (@pxref{-update-at})
 @end example
 @end defun
 
address@hidden
address@hidden -map-first (pred rep list)
+Replace first item in @var{list} satisfying @var{pred} with result of 
@var{rep} called on this item.
+
+See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} 
(@pxref{-replace-first})
+
address@hidden
address@hidden
+(-map-first 'even? 'square '(1 2 3 4))
+    @result{} '(1 4 3 4)
address@hidden group
address@hidden
+(--map-first (> it 2) (* it it) '(1 2 3 4))
+    @result{} '(1 2 9 4)
address@hidden group
address@hidden
+(--map-first (= it 2) 17 '(1 2 3 2))
+    @result{} '(1 17 3 2)
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden
address@hidden -map-last (pred rep list)
+Replace first item in @var{list} satisfying @var{pred} with result of 
@var{rep} called on this item.
+
+See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} 
(@pxref{-replace-last})
+
address@hidden
address@hidden
+(-map-last 'even? 'square '(1 2 3 4))
+    @result{} '(1 2 3 16)
address@hidden group
address@hidden
+(--map-last (> it 2) (* it it) '(1 2 3 4))
+    @result{} '(1 2 3 16)
address@hidden group
address@hidden
+(--map-last (= it 2) 17 '(1 2 3 2))
+    @result{} '(1 2 3 17)
address@hidden group
address@hidden example
address@hidden defun
+
 @anchor{-map-indexed}
 @defun -map-indexed (fn list)
 Return a new list consisting of the result of (@var{fn} index item) for each 
item in @var{list}.
@@ -424,6 +468,54 @@ Alias: @code{-reject}
 @end example
 @end defun
 
address@hidden
address@hidden -remove-first (pred list)
+Return a new list with the first item matching @var{pred} removed.
+
+Alias: @code{-reject-first}
+
+See also: @code{-remove} (@pxref{-remove}), @code{-map-first} 
(@pxref{-map-first})
+
address@hidden
address@hidden
+(-remove-first 'even? '(1 3 5 4 7 8 10))
+    @result{} '(1 3 5 7 8 10)
address@hidden group
address@hidden
+(-remove-first 'stringp '(1 2 "first" "second" "third"))
+    @result{} '(1 2 "second" "third")
address@hidden group
address@hidden
+(--remove-first (> it 3) '(1 2 3 4 5 6 7 8 9 10))
+    @result{} '(1 2 3 5 6 7 8 9 10)
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden
address@hidden -remove-last (pred list)
+Return a new list with the last item matching @var{pred} removed.
+
+Alias: @code{-reject-last}
+
+See also: @code{-remove} (@pxref{-remove}), @code{-map-last} 
(@pxref{-map-last})
+
address@hidden
address@hidden
+(-remove-last 'even? '(1 3 5 4 7 8 10 11))
+    @result{} '(1 3 5 4 7 8 11)
address@hidden group
address@hidden
+(-remove-last 'stringp '(1 2 "last" "second" "third"))
+    @result{} '(1 2 "last" "second")
address@hidden group
address@hidden
+(--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10))
+    @result{} '(1 2 3 4 5 6 7 8 9)
address@hidden group
address@hidden example
address@hidden defun
+
 @anchor{-remove-item}
 @defun -remove-item (item list)
 Remove all occurences of @var{item} from @var{list}.
@@ -695,6 +787,54 @@ See also: @code{-replace-at} (@pxref{-replace-at})
 @end example
 @end defun
 
address@hidden
address@hidden -replace-first (old new list)
+Replace the first occurence of @var{old} with @var{new} in @var{list}.
+
+Elements are compared using @code{equal}.
+
+See also: @code{-map-first} (@pxref{-map-first})
+
address@hidden
address@hidden
+(-replace-first 1 "1" '(1 2 3 4 3 2 1))
+    @result{} '("1" 2 3 4 3 2 1)
address@hidden group
address@hidden
+(-replace-first "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo"))
+    @result{} '("a" "nice" "bar" "sentence" "about" "foo")
address@hidden group
address@hidden
+(-replace-first 1 2 nil)
+    @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden
address@hidden -replace-last (old new list)
+Replace the last occurence of @var{old} with @var{new} in @var{list}.
+
+Elements are compared using @code{equal}.
+
+See also: @code{-map-last} (@pxref{-map-last})
+
address@hidden
address@hidden
+(-replace-last 1 "1" '(1 2 3 4 3 2 1))
+    @result{} '(1 2 3 4 3 2 "1")
address@hidden group
address@hidden
+(-replace-last "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo"))
+    @result{} '("a" "nice" "foo" "sentence" "about" "bar")
address@hidden group
address@hidden
+(-replace-last 1 2 nil)
+    @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
 @anchor{-insert-at}
 @defun -insert-at (n x list)
 Return a list with @var{x} inserted into @var{list} at position @var{n}.
diff --git a/dev/examples.el b/dev/examples.el
index eeab347..14835ee 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -38,6 +38,22 @@ new list."
     (--map-when (= it 2) 17 '(1 2 3 4)) => '(1 17 3 4)
     (-map-when (lambda (n) (= n 3)) (lambda (n) 0) '(1 2 3 4)) => '(1 2 0 4))
 
+  (defexamples -map-first
+    (-map-first 'even? 'square '(1 2 3 4)) => '(1 4 3 4)
+    (--map-first (> it 2) (* it it) '(1 2 3 4)) => '(1 2 9 4)
+    (--map-first (= it 2) 17 '(1 2 3 2)) => '(1 17 3 2)
+    (-map-first 'even? 'square '(1 3 5 7)) => '(1 3 5 7)
+    (-map-first 'even? 'square '(2)) => '(4)
+    (-map-first 'even? 'square nil) => nil)
+
+  (defexamples -map-last
+    (-map-last 'even? 'square '(1 2 3 4)) => '(1 2 3 16)
+    (--map-last (> it 2) (* it it) '(1 2 3 4)) => '(1 2 3 16)
+    (--map-last (= it 2) 17 '(1 2 3 2)) => '(1 2 3 17)
+    (-map-last 'even? 'square '(1 3 5 7)) => '(1 3 5 7)
+    (-map-last 'even? 'square '(2)) => '(4)
+    (-map-last 'even? 'square nil) => nil)
+
   (defexamples -map-indexed
     (-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) => '(1 1 1 
1)
     (--map-indexed (- it it-index) '(1 2 3 4)) => '(1 1 1 1))
@@ -80,6 +96,20 @@ new list."
     (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) => 
'(1 3)
     (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
 
+  (defexamples -remove-first
+    (-remove-first 'even? '(1 3 5 4 7 8 10)) => '(1 3 5 7 8 10)
+    (-remove-first 'stringp '(1 2 "first" "second" "third")) => '(1 2 "second" 
"third")
+    (--remove-first (> it 3) '(1 2 3 4 5 6 7 8 9 10)) => '(1 2 3 5 6 7 8 9 10)
+    (-remove-first 'even? '(2 3 4)) => '(3 4)
+    (-remove-first 'even? '(3 5 7 4)) => '(3 5 7)
+    (-remove-first 'even? '(2)) => nil
+    (-remove-first 'even? '(1 3 5 7)) => '(1 3 5 7))
+
+  (defexamples -remove-last
+    (-remove-last 'even? '(1 3 5 4 7 8 10 11)) => '(1 3 5 4 7 8 11)
+    (-remove-last 'stringp '(1 2 "last" "second" "third")) => '(1 2 "last" 
"second")
+    (--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10)) => '(1 2 3 4 5 6 7 8 9))
+
   (defexamples -remove-item
     (-remove-item 3 '(1 2 3 2 3 4 5 3)) => '(1 2 2 4 5)
     (-remove-item 'foo '(foo bar baz foo)) => '(bar baz)
@@ -163,6 +193,16 @@ new list."
     (-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) => 
'("a" "nice" "bar" "sentence" "about" "bar")
     (-replace 1 2 nil) => nil)
 
+  (defexamples -replace-first
+    (-replace-first 1 "1" '(1 2 3 4 3 2 1)) => '("1" 2 3 4 3 2 1)
+    (-replace-first "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) 
=> '("a" "nice" "bar" "sentence" "about" "foo")
+    (-replace-first 1 2 nil) => nil)
+
+  (defexamples -replace-last
+    (-replace-last 1 "1" '(1 2 3 4 3 2 1)) => '(1 2 3 4 3 2 "1")
+    (-replace-last "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) 
=> '("a" "nice" "foo" "sentence" "about" "bar")
+    (-replace-last 1 2 nil) => nil)
+
   (defexamples -insert-at
     (-insert-at 1 'x '(a b c)) => '(a x b c)
     (-insert-at 12 'x '(a b c)) => '(a b c x))