From e6013f950eb6f4494165789312a60dce50e8904b Mon Sep 17 00:00:00 2001 From: Daniel Oosthuizen Date: Sat, 12 Nov 2016 12:30:35 +0000 Subject: [PATCH] Add `-npartial' for arbitrary currying Currently, we have `-partial' and `-rpartial' for currying with arguments at either the left or the right, but we don't have anything for truly arbitrary application of curried arguments. Therefore I've included `-npartial' to plug that gap. It takes an offset N to determine where to put the curried arguments, a function FN, and the curried ARGS. E.g.: (funcall (-npartial 1 (lambda (a b c) (+ a (* b c))) 5) 2 3) ;; => 17 (funcall (-npartial 2 (lambda (a b c d) (+ a (* b c) d)) 3) 2 4 5) ;; => 19 (Note that I have a slightly different version of texinfo -- 6 instead of 4 -- so the way that the paragraphs have been filled is slightly different, but I'm afraid there's nothing much I can do, because Arch can't downgrade all the way to 4.) --- README.md | 16 + dash-functional.el | 10 + dash.info | 1046 +++++++++++++++++++++++--------------------- dash.texi | 28 ++ dev/examples.el | 4 + 5 files changed, 596 insertions(+), 508 deletions(-) diff --git a/README.md b/README.md index 2b69225f..16d86168 100644 --- a/README.md +++ b/README.md @@ -292,6 +292,7 @@ These combinators require Emacs 24 for its lexical scope. So they are offered in * [-partial](#-partial-fn-rest-args) `(fn &rest args)` * [-rpartial](#-rpartial-fn-rest-args) `(fn &rest args)` +* [-npartial](#-npartial-n-fn-rest-args) `(n fn &rest args)` * [-juxt](#-juxt-rest-fns) `(&rest fns)` * [-compose](#-compose-rest-fns) `(&rest fns)` * [-applify](#-applify-fn) `(fn)` @@ -1669,6 +1670,7 @@ Return the first item of `list`, or nil on an empty list. ```el (-first-item '(1 2 3)) ;; => 1 (-first-item nil) ;; => nil +(let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => '(5 2 3) ``` #### -last-item `(list)` @@ -1678,6 +1680,7 @@ Return the last item of `list`, or nil on an empty list. ```el (-last-item '(1 2 3)) ;; => 3 (-last-item nil) ;; => nil +(let ((list (list 1 2 3))) (setf (-last-item list) 5) list) ;; => '(1 2 5) ``` #### -butlast `(list)` @@ -2280,6 +2283,19 @@ args first and then `args`. (funcall (-rpartial '- 5 2) 10) ;; => 3 ``` +#### -npartial `(n fn &rest args)` + +Takes an offset `n`, a function `fn` and fewer than the normal +arguments to `fn`, and returns a function which takes a variable +number of additional `args`. When called, the returned function +calls `fn` with the first `n` additional args first, then `args`, then +the remaining additional args. + +```el +(funcall (-npartial 1 (lambda (a b c) (+ a (* b c))) 5) 2 3) ;; => 17 +(funcall (-npartial 2 (lambda (a b c d) (+ a (* b c) d)) 3) 2 4 5) ;; => 19 +``` + #### -juxt `(&rest fns)` Takes a list of functions and returns a fn that is the diff --git a/dash-functional.el b/dash-functional.el index 4bd2d6dd..f5303233 100644 --- a/dash-functional.el +++ b/dash-functional.el @@ -45,6 +45,16 @@ When called, the returned function calls FN with the additional args first and then ARGS." (lambda (&rest args-before) (apply fn (append args-before args)))) +(defun -npartial (n fn &rest args) + "Takes an offset N, a function FN and fewer than the normal +arguments to FN, and returns a function which takes a variable +number of additional ARGS. When called, the returned function +calls FN with the first N additional args first, then ARGS, then +the remaining additional args." + (lambda (&rest args-around) (apply fn (append (-take n args-around) + args + (-drop n args-around))))) + (defun -juxt (&rest fns) "Takes a list of functions and returns a fn that is the juxtaposition of those fns. The returned fn takes a variable diff --git a/dash.info b/dash.info index f94cd19f..7bedd4af 100644 --- a/dash.info +++ b/dash.info @@ -1,4 +1,4 @@ -This is dash.info, produced by makeinfo version 5.2 from dash.texi. +This is dash.info, produced by makeinfo version 6.3 from dash.texi. This manual is for ‘dash.el’ version 2.12.1. @@ -6,11 +6,11 @@ This manual is for ‘dash.el’ version 2.12.1. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as - published by the Free Software Foundation, either version 3 of the - License, or (at your option) any later version. + published by the Free Software Foundation, either version 3 of + the License, or (at your option) any later version. - This program is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. @@ -34,11 +34,11 @@ This manual is for ‘dash.el’ version 2.12.1. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as - published by the Free Software Foundation, either version 3 of the - License, or (at your option) any later version. + published by the Free Software Foundation, either version 3 of + the License, or (at your option) any later version. - This program is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. @@ -140,15 +140,16 @@ File: dash.info, Node: Functions, Next: Development, Prev: Installation, Up: *********** This chapter contains reference documentation for the dash application -programming interface (API). All functions and constructs in the library -are prefixed with a dash (-). +programming interface (API). All functions and constructs in the +library are prefixed with a dash (-). There are also anaphoric versions of functions where that makes sense, prefixed with two dashes instead of one. - For instance, while ‘-map’ takes a function to map over the list, one -can also use the anaphoric form with double dashes - which will then be -executed with ‘it’ exposed as the list item. Here’s an example: + For instance, while ‘-map’ takes a function to map over the list, +one can also use the anaphoric form with double dashes - which will +then be executed with ‘it’ exposed as the list item. Here’s an +example: (-map (lambda (n) (* n n)) '(1 2 3 4)) ;; normal version @@ -203,9 +204,10 @@ The results are collected in order and returned as new list. ⇒ '(1 4 9 16) -- Function: -map-when (pred rep list) - Return a new list where the elements in LIST that do not match the - PRED function are unchanged, and where the elements in LIST that do - match the PRED function are mapped through the REP function. + Return a new list where the elements in LIST that do not match + the PRED function are unchanged, and where the elements in LIST + that do match the PRED function are mapped through the REP + function. Alias: ‘-replace-where’ @@ -222,8 +224,8 @@ The results are collected in order and returned as new list. Replace first item in LIST satisfying PRED with result of REP called on this item. - See also: ‘-map-when’ (*note -map-when::), ‘-replace-first’ (*note - -replace-first::) + See also: ‘-map-when’ (*note -map-when::), ‘-replace-first’ + (*note -replace-first::) (-map-first 'even? 'square '(1 2 3 4)) ⇒ '(1 4 3 4) @@ -272,14 +274,14 @@ The results are collected in order and returned as new list. ⇒ '((nil . 0) (nil . 1) (t . 2) (t . 3)) -- Function: -splice (pred fun list) - Splice lists generated by FUN in place of elements matching PRED in - LIST. + Splice lists generated by FUN in place of elements matching PRED + in LIST. FUN takes the element matching PRED as input. - This function can be used as replacement for ‘,@’ in case you need - to splice several lists at marked positions (for example with - keywords). + This function can be used as replacement for ‘,@’ in case you + need to splice several lists at marked positions (for example + with keywords). See also: ‘-splice-list’ (*note -splice-list::), ‘-insert-at’ (*note -insert-at::) @@ -349,7 +351,8 @@ Functions returning a sublist of the original list. ⇒ '(2 4) -- Function: -remove (pred list) - Return a new list of the items in LIST for which PRED returns nil. + Return a new list of the items in LIST for which PRED returns + nil. Alias: ‘-reject’ @@ -414,8 +417,8 @@ Functions returning a sublist of the original list. FROM or TO may be negative. These values are then interpreted modulo the length of the list. - If STEP is a number, only each STEPth item in the resulting section - is returned. Defaults to 1. + If STEP is a number, only each STEPth item in the resulting + section is returned. Defaults to 1. (-slice '(1 2 3 4 5) 1) ⇒ '(2 3 4 5) @@ -505,8 +508,8 @@ Functions returning a sublist of the original list. -- Function: -select-columns (columns table) Select COLUMNS from TABLE. - TABLE is a list of lists where each element represents one row. It - is assumed each row has the same length. + TABLE is a list of lists where each element represents one row. + It is assumed each row has the same length. Each row is transformed such that only the specified COLUMNS are selected. @@ -524,8 +527,8 @@ Functions returning a sublist of the original list. -- Function: -select-column (column table) Select COLUMN from TABLE. - TABLE is a list of lists where each element represents one row. It - is assumed each row has the same length. + TABLE is a list of lists where each element represents one row. + It is assumed each row has the same length. The single selected column is returned as a list. @@ -547,8 +550,8 @@ Bag of various functions which modify input list. Return a new list of the non-nil results of applying FN to the items in LIST. - If you want to select the original items satisfying a predicate use - ‘-filter’ (*note -filter::). + If you want to select the original items satisfying a predicate + use ‘-filter’ (*note -filter::). (-keep 'cdr '((1 2 3) (4 5) (6))) ⇒ '((2 3) (5)) @@ -575,8 +578,8 @@ Bag of various functions which modify input list. Note that because ‘nil’ represents a list of zero elements (an empty list), any mention of nil in L will disappear after flattening. If you need to preserve nils, consider ‘-flatten-n’ - (*note -flatten-n::) or map them to some unique symbol and then map - them back. + (*note -flatten-n::) or map them to some unique symbol and then + map them back. Conses of two atoms are considered "terminals", that is, they aren’t flattened further. @@ -656,7 +659,8 @@ Bag of various functions which modify input list. ⇒ '(a b c x) -- Function: -replace-at (n x list) - Return a list with element at Nth position in LIST replaced with X. + Return a list with element at Nth position in LIST replaced with + X. See also: ‘-replace’ (*note -replace::) @@ -718,8 +722,8 @@ Functions reducing lists into single value. -- Function: -reduce-from (fn initial-value list) Return the result of applying FN to INITIAL-VALUE and the first item in LIST, then applying FN to that result and the 2nd item, - etc. If LIST contains no items, return INITIAL-VALUE and FN is not - called. + etc. If LIST contains no items, return INITIAL-VALUE and FN is + not called. In the anaphoric form ‘--reduce-from’, the accumulated value is exposed as ‘acc‘. @@ -736,12 +740,12 @@ Functions reducing lists into single value. -- Function: -reduce-r-from (fn initial-value list) Replace conses with FN, nil with INITIAL-VALUE and evaluate the - resulting expression. If LIST is empty, INITIAL-VALUE is returned - and FN is not called. + resulting expression. If LIST is empty, INITIAL-VALUE is + returned and FN is not called. Note: this function works the same as ‘-reduce-from’ (*note - -reduce-from::) but the operation associates from right instead of - from left. + -reduce-from::) but the operation associates from right instead + of from left. See also: ‘-reduce-r’ (*note -reduce-r::), ‘-reduce’ (*note -reduce::) @@ -754,17 +758,17 @@ Functions reducing lists into single value. ⇒ "a b c END" -- Function: -reduce (fn list) - Return the result of applying FN to the first 2 items in LIST, then - applying FN to that result and the 3rd item, etc. If LIST contains - no items, FN must accept no arguments as well, and reduce return - the result of calling FN with no arguments. If LIST has only 1 - item, it is returned and FN is not called. + Return the result of applying FN to the first 2 items in LIST, + then applying FN to that result and the 3rd item, etc. If LIST + contains no items, FN must accept no arguments as well, and + reduce return the result of calling FN with no arguments. If + LIST has only 1 item, it is returned and FN is not called. - In the anaphoric form ‘--reduce’, the accumulated value is exposed - as ‘acc‘. + In the anaphoric form ‘--reduce’, the accumulated value is + exposed as ‘acc‘. - See also: ‘-reduce-from’ (*note -reduce-from::), ‘-reduce-r’ (*note - -reduce-r::) + See also: ‘-reduce-from’ (*note -reduce-from::), ‘-reduce-r’ + (*note -reduce-r::) (-reduce '- '(1 2 3 4)) ⇒ -8 @@ -774,11 +778,11 @@ Functions reducing lists into single value. ⇒ "1-2-3" -- Function: -reduce-r (fn list) - Replace conses with FN and evaluate the resulting expression. The - final nil is ignored. If LIST contains no items, FN must accept no - arguments as well, and reduce return the result of calling FN with - no arguments. If LIST has only 1 item, it is returned and FN is - not called. + Replace conses with FN and evaluate the resulting expression. + The final nil is ignored. If LIST contains no items, FN must + accept no arguments as well, and reduce return the result of + calling FN with no arguments. If LIST has only 1 item, it is + returned and FN is not called. The first argument of FN is the new item, the second is the accumulated value. @@ -900,14 +904,14 @@ than consuming a list to produce a single value. -- Function: -unfold (fun seed) Build a list from SEED using FUN. - This is "dual" operation to ‘-reduce-r’ (*note -reduce-r::): while - -reduce-r consumes a list to produce a single value, ‘-unfold’ - (*note -unfold::) takes a seed value and builds a (potentially - infinite!) list. + This is "dual" operation to ‘-reduce-r’ (*note -reduce-r::): + while -reduce-r consumes a list to produce a single value, + ‘-unfold’ (*note -unfold::) takes a seed value and builds a + (potentially infinite!) list. FUN should return ‘nil’ to stop the generating process, or a cons - (A . B), where A will be prepended to the result and B is the new - seed. + (A . B), where A will be prepended to the result and B is the + new seed. (-unfold (lambda (x) (unless (= x 0) (cons x (1- x)))) 10) ⇒ '(10 9 8 7 6 5 4 3 2 1) @@ -1058,8 +1062,8 @@ Functions partitioning the input list into a list of lists. ⇒ '((1 2 3 4 5) nil) -- Function: -split-with (pred list) - Return a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), - in no more than one pass through the list. + Return a list of ((-take-while PRED LIST) (-drop-while PRED + LIST)), in no more than one pass through the list. (-split-with 'even? '(1 2 3 4)) ⇒ '(nil (1 2 3 4)) @@ -1072,8 +1076,8 @@ Functions partitioning the input list into a list of lists. Split the LIST each time ITEM is found. Unlike ‘-partition-by’ (*note -partition-by::), the ITEM is - discarded from the results. Empty lists are also removed from the - result. + discarded from the results. Empty lists are also removed from + the result. Comparison is done by ‘equal’. @@ -1104,8 +1108,8 @@ Functions partitioning the input list into a list of lists. ⇒ '((a b) (c d) (args)) -- Function: -separate (pred list) - Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in one - pass through the list. + Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in + one pass through the list. (-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ⇒ '((2 4 6) (1 3 5 7)) @@ -1162,8 +1166,8 @@ Functions partitioning the input list into a list of lists. ⇒ '((1 2 3) (3 4 5) (5)) -- Function: -partition-by (fn list) - Apply FN to each item in LIST, splitting it each time FN returns a - new value. + Apply FN to each item in LIST, splitting it each time FN returns + a new value. (-partition-by 'even? '()) ⇒ '() @@ -1202,8 +1206,8 @@ File: dash.info, Node: Indexing, Next: Set operations, Prev: Partitioning, U 2.8 Indexing ============ -Return indices of elements based on predicates, sort elements by indices -etc. +Return indices of elements based on predicates, sort elements by +indices etc. -- Function: -elem-index (elem list) Return the index of the first element in the given LIST which is @@ -1229,9 +1233,9 @@ etc. ⇒ '(1 3) -- Function: -find-index (pred list) - Take a predicate PRED and a LIST and return the index of the first - element in the list satisfying the predicate, or nil if there is no - such element. + Take a predicate PRED and a LIST and return the index of the + first element in the list satisfying the predicate, or nil if + there is no such element. See also ‘-first’ (*note -first::). @@ -1244,8 +1248,8 @@ etc. -- Function: -find-last-index (pred list) Take a predicate PRED and a LIST and return the index of the last - element in the list satisfying the predicate, or nil if there is no - such element. + element in the list satisfying the predicate, or nil if there is + no such element. See also ‘-last’ (*note -last::). @@ -1257,8 +1261,8 @@ etc. ⇒ 1 -- Function: -find-indices (pred list) - Return the indices of all elements in LIST satisfying the predicate - PRED, in ascending order. + Return the indices of all elements in LIST satisfying the + predicate PRED, in ascending order. (-find-indices 'even? '(2 4 1 6 3 3 5 8)) ⇒ '(0 1 3 7) @@ -1320,9 +1324,9 @@ Operations pretending lists are sets. ⇒ '(1 2) -- Function: -intersection (list list2) - Return a new list containing only the elements that are members of - both LIST and LIST2. The test for equality is done with ‘equal’, - or with ‘-compare-fn’ if that’s non-nil. + Return a new list containing only the elements that are members + of both LIST and LIST2. The test for equality is done with + ‘equal’, or with ‘-compare-fn’ if that’s non-nil. (-intersection '() '()) ⇒ '() @@ -1352,8 +1356,8 @@ File: dash.info, Node: Other list operations, Next: Tree operations, Prev: Se Other list functions not fit to be classified elsewhere. -- Function: -rotate (n list) - Rotate LIST N places to the right. With N negative, rotate to the - left. The time complexity is O(n). + Rotate LIST N places to the right. With N negative, rotate to + the left. The time complexity is O(n). (-rotate 3 '(1 2 3 4 5 6 7)) ⇒ '(5 6 7 1 2 3 4) @@ -1374,9 +1378,9 @@ Other list functions not fit to be classified elsewhere. -- Function: -cons* (&rest args) Make a new list from the elements of ARGS. - The last 2 members of ARGS are used as the final cons of the result - so if the final member of ARGS is not a list the result is a dotted - list. + The last 2 members of ARGS are used as the final cons of the + result so if the final member of ARGS is not a list the result is + a dotted list. (-cons* 1 2) ⇒ '(1 . 2) @@ -1446,8 +1450,8 @@ Other list functions not fit to be classified elsewhere. list of cons cells. Otherwise, return the groupings as a list of lists. - Please note! This distinction is being removed in an upcoming 3.0 - release of Dash. If you rely on this behavior, use -zip-pair + Please note! This distinction is being removed in an upcoming + 3.0 release of Dash. If you rely on this behavior, use -zip-pair instead. (-zip '(1 2 3) '(4 5 6)) @@ -1494,8 +1498,8 @@ Other list functions not fit to be classified elsewhere. ⇒ '((1 . 1) (2 . 2)) -- Function: -pad (fill-value &rest lists) - Appends FILL-VALUE to the end of each list in LISTS such that they - will all have the same length. + Appends FILL-VALUE to the end of each list in LISTS such that + they will all have the same length. (-pad 0 '()) ⇒ '(nil) @@ -1511,8 +1515,8 @@ Other list functions not fit to be classified elsewhere. supplied lists. The outer product is computed by applying fn to all possible - combinations created by taking one element from each list in order. - The dimension of the result is (length lists). + combinations created by taking one element from each list in + order. The dimension of the result is (length lists). See also: ‘-table-flat’ (*note -table-flat::) @@ -1530,9 +1534,9 @@ Other list functions not fit to be classified elsewhere. supplied lists. The outer product is computed by applying fn to all possible - combinations created by taking one element from each list in order. - The results are flattened, ignoring the tensor structure of the - result. This is equivalent to calling: + combinations created by taking one element from each list in + order. The results are flattened, ignoring the tensor structure + of the result. This is equivalent to calling: (-flatten-n (1- (length lists)) (apply ’-table fn lists)) @@ -1563,8 +1567,8 @@ Other list functions not fit to be classified elsewhere. ⇒ 3 -- Function: -some (pred list) - Return (PRED x) for the first LIST item where (PRED x) is non-nil, - else nil. + Return (PRED x) for the first LIST item where (PRED x) is + non-nil, else nil. Alias: ‘-any’ @@ -1594,6 +1598,8 @@ Other list functions not fit to be classified elsewhere. ⇒ 1 (-first-item nil) ⇒ nil + (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) + ⇒ '(5 2 3) -- Function: -last-item (list) Return the last item of LIST, or nil on an empty list. @@ -1602,6 +1608,8 @@ Other list functions not fit to be classified elsewhere. ⇒ 3 (-last-item nil) ⇒ nil + (let ((list (list 1 2 3))) (setf (-last-item list) 5) list) + ⇒ '(1 2 5) -- Function: -butlast (list) Return a list of all items in list except for the last. @@ -1614,10 +1622,10 @@ Other list functions not fit to be classified elsewhere. ⇒ nil -- Function: -sort (comparator list) - Sort LIST, stably, comparing elements using COMPARATOR. Return the - sorted list. LIST is NOT modified by side effects. COMPARATOR is - called with two elements of LIST, and should return non-nil if the - first element should sort before the second. + Sort LIST, stably, comparing elements using COMPARATOR. Return + the sorted list. LIST is NOT modified by side effects. + COMPARATOR is called with two elements of LIST, and should return + non-nil if the first element should sort before the second. (-sort '< '(3 1 2)) ⇒ '(1 2 3) @@ -1665,8 +1673,8 @@ Functions pretending lists are trees. passed argument is a branch, that is, a node that can have children. - CHILDREN is a function of one argument that returns the children of - the passed branch node. + CHILDREN is a function of one argument that returns the children + of the passed branch node. Non-branch nodes are simply copied. @@ -1692,7 +1700,8 @@ Functions pretending lists are trees. Call FUN on each node of TREE that satisfies PRED. If PRED returns nil, continue descending down this node. If PRED - returns non-nil, apply FUN to this node and do not descend further. + returns non-nil, apply FUN to this node and do not descend + further. (-tree-map-nodes 'vectorp (lambda (x) (-sum (append x nil))) '(1 [2 3] 4 (5 [6 7] 8))) ⇒ '(1 5 4 (5 13 8)) @@ -1772,9 +1781,9 @@ Functions pretending lists are trees. ⇒ "{elips-mode : {foo : {bar -> booze{, baz -> qux{, c-mode : {foo -> bla, bum -> bam}}" -- Function: -clone (list) - Create a deep copy of LIST. The new list has the same elements and - structure but all cons are replaced with new ones. This is useful - when you need to clone a structure such as plist or alist. + Create a deep copy of LIST. The new list has the same elements + and structure but all cons are replaced with new ones. This is + useful when you need to clone a structure such as plist or alist. (let* ((a '(1 2 3)) (b (-clone a))) (nreverse a) b) ⇒ '(1 2 3) @@ -1786,10 +1795,10 @@ File: dash.info, Node: Threading macros, Next: Binding, Prev: Tree operations ===================== -- Macro: -> (x &optional form &rest more) - Thread the expr through the forms. Insert X as the second item in - the first form, making a list of it if it is not a list already. - If there are more forms, insert the first form as the second item - in second form, etc. + Thread the expr through the forms. Insert X as the second item + in the first form, making a list of it if it is not a list + already. If there are more forms, insert the first form as the + second item in second form, etc. (-> '(2 3 5)) ⇒ '(2 3 5) @@ -1801,8 +1810,8 @@ File: dash.info, Node: Threading macros, Next: Binding, Prev: Tree operations -- Macro: ->> (x &optional form &rest more) Thread the expr through the forms. Insert X as the last item in the first form, making a list of it if it is not a list already. - If there are more forms, insert the first form as the last item in - second form, etc. + If there are more forms, insert the first form as the last item + in second form, etc. (->> '(1 2 3) (-map 'square)) ⇒ '(1 4 9) @@ -1883,8 +1892,9 @@ control. ⇒ nil -- Macro: -when-let* (vars-vals &rest body) - If all VALS evaluate to true, bind them to their corresponding VARS - and execute body. VARS-VALS should be a list of (VAR VAL) pairs. + If all VALS evaluate to true, bind them to their corresponding + VARS and execute body. VARS-VALS should be a list of (VAR VAL) + pairs. Note: binding is done according to ‘-let*’ (*note -let*::). VALS are evaluated sequentially, and evaluation stops after the first @@ -1896,8 +1906,8 @@ control. ⇒ nil -- Macro: -if-let (var-val then &rest else) - If VAL evaluates to non-nil, bind it to VAR and do THEN, otherwise - do ELSE. VAR-VAL should be a (VAR VAL) pair. + If VAL evaluates to non-nil, bind it to VAR and do THEN, + otherwise do ELSE. VAR-VAL should be a (VAR VAL) pair. Note: binding is done according to ‘-let’ (*note -let::). @@ -1907,9 +1917,9 @@ control. ⇒ t -- Macro: -if-let* (vars-vals then &rest else) - If all VALS evaluate to true, bind them to their corresponding VARS - and do THEN, otherwise do ELSE. VARS-VALS should be a list of (VAR - VAL) pairs. + If all VALS evaluate to true, bind them to their corresponding + VARS and do THEN, otherwise do ELSE. VARS-VALS should be a list + of (VAR VAL) pairs. Note: binding is done according to ‘-let*’ (*note -let*::). VALS are evaluated sequentially, and evaluation stops after the first @@ -1931,12 +1941,12 @@ control. recursively, and can therefore contain sub-patterns which are matched against corresponding sub-expressions of SOURCE. - All the SOURCEs are evalled before any symbols are bound (i.e. "in - parallel"). + All the SOURCEs are evalled before any symbols are bound (i.e. + "in parallel"). If VARLIST only contains one (PATTERN SOURCE) element, you can - optionally specify it using a vector and discarding the outer-most - parens. Thus + optionally specify it using a vector and discarding the + outer-most parens. Thus (-let ((PATTERN SOURCE)) ..) @@ -1945,10 +1955,10 @@ control. (-let [PATTERN SOURCE] ..). ‘-let’ (*note -let::) uses a convention of not binding places - (symbols) starting with _ whenever it’s possible. You can use this - to skip over entries you don’t care about. However, this is not - *always* possible (as a result of implementation) and these symbols - might get bound to undefined values. + (symbols) starting with _ whenever it’s possible. You can use + this to skip over entries you don’t care about. However, this is + not *always* possible (as a result of implementation) and these + symbols might get bound to undefined values. Following is the overview of supported patterns. Remember that patterns can be matched recursively, so every a, b, aK in the @@ -1967,8 +1977,8 @@ control. (a b) - bind car of list to A and ‘cadr’ to B - (a1 a2 a3 ...) - bind 0th car of list to A1, 1st to A2, 2nd to A3 - ... + (a1 a2 a3 ...) - bind 0th car of list to A1, 1st to A2, 2nd to + A3 ... (a1 a2 a3 ... aN . rest) - as above, but bind the Nth cdr to REST. @@ -1978,10 +1988,10 @@ control. [a] - bind 0th element of a non-list sequence to A (works with vectors, strings, bit arrays...) - [a1 a2 a3 ...] - bind 0th element of non-list sequence to A0, 1st - to A1, 2nd to A2, ... If the PATTERN is shorter than SOURCE, the - values at places not in PATTERN are ignored. If the PATTERN is - longer than SOURCE, an ‘error’ is thrown. + [a1 a2 a3 ...] - bind 0th element of non-list sequence to A0, + 1st to A1, 2nd to A2, ... If the PATTERN is shorter than SOURCE, + the values at places not in PATTERN are ignored. If the PATTERN + is longer than SOURCE, an ‘error’ is thrown. [a1 a2 a3 ... &rest rest] - as above, but bind the rest of the sequence to REST. This is conceptually the same as improper list @@ -2007,9 +2017,9 @@ control. This binds N values from the list to a1 ... aN, then interprets the cdr as a plist (see key/value matching above). - You can name the source using the syntax SYMBOL &as PATTERN. This - syntax works with lists (proper or improper), vectors and all types - of maps. + You can name the source using the syntax SYMBOL &as PATTERN. + This syntax works with lists (proper or improper), vectors and + all types of maps. (list &as a b c) (list 1 2 3) @@ -2038,10 +2048,10 @@ control. This is especially useful when we want to capture the result of a computation and destructure at the same time. Consider the form (function-returning-complex-structure) returning a list of two - vectors with two items each. We want to capture this entire result - and pass it to another computation, but at the same time we want to - get the second item from each vector. We can achieve it with - pattern + vectors with two items each. We want to capture this entire + result and pass it to another computation, but at the same time + we want to get the second item from each vector. We can achieve + it with pattern (result &as [_ a] [_ b]) (function-returning-complex-structure) @@ -2060,12 +2070,12 @@ control. Bind variables according to VARLIST then eval BODY. VARLIST is a list of lists of the form (PATTERN SOURCE). Each - PATTERN is matched against the SOURCE structurally. SOURCE is only - evaluated once for each PATTERN. + PATTERN is matched against the SOURCE structurally. SOURCE is + only evaluated once for each PATTERN. - Each SOURCE can refer to the symbols already bound by this VARLIST. - This is useful if you want to destructure SOURCE recursively but - also want to name the intermediate structures. + Each SOURCE can refer to the symbols already bound by this + VARLIST. This is useful if you want to destructure SOURCE + recursively but also want to name the intermediate structures. See ‘-let’ (*note -let::) for the list of all possible patterns. @@ -2086,7 +2096,8 @@ control. (-lambda (x) body) (-lambda (x y ...) body) has the usual semantics of ‘lambda’. Furthermore, these get - translated into normal lambda, so there is no performance penalty. + translated into normal lambda, so there is no performance + penalty. See ‘-let’ (*note -let::) for the description of destructuring mechanism. @@ -2107,8 +2118,8 @@ File: dash.info, Node: Side-effects, Next: Destructive operations, Prev: Bind Functions iterating over lists for side-effect only. -- Function: -each (list fn) - Call FN with every item in LIST. Return nil, used for side-effects - only. + Call FN with every item in LIST. Return nil, used for + side-effects only. (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) ⇒ nil @@ -2150,9 +2161,9 @@ Functions iterating over lists for side-effect only. -- Macro: -doto (eval-initial-value &rest forms) Eval a form, then insert that form as the 2nd argument to other - forms. The EVAL-INITIAL-VALUE form is evaluated once. Its result - is passed to FORMS, which are then evaluated sequentially. Returns - the target form. + forms. The EVAL-INITIAL-VALUE form is evaluated once. Its + result is passed to FORMS, which are then evaluated sequentially. + Returns the target form. (-doto '(1 2 3) (!cdr) (!cdr)) ⇒ '(3) @@ -2191,10 +2202,10 @@ These combinators require Emacs 24 for its lexical scope. So they are offered in a separate package: ‘dash-functional‘. -- Function: -partial (fn &rest args) - Takes a function FN and fewer than the normal arguments to FN, and - returns a fn that takes a variable number of additional ARGS. When - called, the returned function calls FN with ARGS first and then - additional args. + Takes a function FN and fewer than the normal arguments to FN, + and returns a fn that takes a variable number of additional ARGS. + When called, the returned function calls FN with ARGS first and + then additional args. (funcall (-partial '- 5) 3) ⇒ 2 @@ -2202,16 +2213,28 @@ offered in a separate package: ‘dash-functional‘. ⇒ 10 -- Function: -rpartial (fn &rest args) - Takes a function FN and fewer than the normal arguments to FN, and - returns a fn that takes a variable number of additional ARGS. When - called, the returned function calls FN with the additional args - first and then ARGS. + Takes a function FN and fewer than the normal arguments to FN, + and returns a fn that takes a variable number of additional ARGS. + When called, the returned function calls FN with the additional + args first and then ARGS. (funcall (-rpartial '- 5) 8) ⇒ 3 (funcall (-rpartial '- 5 2) 10) ⇒ 3 + -- Function: -npartial (n fn &rest args) + Takes an offset N, a function FN and fewer than the normal + arguments to FN, and returns a function which takes a variable + number of additional ARGS. When called, the returned function + calls FN with the first N additional args first, then ARGS, then + the remaining additional args. + + (funcall (-npartial 1 (lambda (a b c) (+ a (* b c))) 5) 2 3) + ⇒ 17 + (funcall (-npartial 2 (lambda (a b c d) (+ a (* b c) d)) 3) 2 4 5) + ⇒ 19 + -- Function: -juxt (&rest fns) Takes a list of functions and returns a fn that is the juxtaposition of those fns. The returned fn takes a variable @@ -2224,10 +2247,11 @@ offered in a separate package: ‘dash-functional‘. ⇒ '((1 1) (2 4) (3 9)) -- Function: -compose (&rest fns) - Takes a list of functions and returns a fn that is the composition - of those fns. The returned fn takes a variable number of - arguments, and returns the result of applying each fn to the result - of applying the previous fn to the arguments (right-to-left). + Takes a list of functions and returns a fn that is the + composition of those fns. The returned fn takes a variable + number of arguments, and returns the result of applying each fn + to the result of applying the previous fn to the arguments + (right-to-left). (funcall (-compose 'square '+) 2 3) ⇒ (square (+ 2 3)) @@ -2237,8 +2261,8 @@ offered in a separate package: ‘dash-functional‘. ⇒ (square 3) -- Function: -applify (fn) - Changes an n-arity function FN to a 1-arity function that expects a - list with n items as arguments + Changes an n-arity function FN to a 1-arity function that expects + a list with n items as arguments (-map (-applify '+) '((1 1 1) (1 2 3) (5 5 5))) ⇒ '(3 6 15) @@ -2274,7 +2298,8 @@ offered in a separate package: ‘dash-functional‘. ⇒ '(6 4 3 1) -- Function: -const (c) - Return a function that returns C ignoring any additional arguments. + Return a function that returns C ignoring any additional + arguments. In types: a -> b -> a @@ -2364,18 +2389,19 @@ offered in a separate package: ‘dash-functional‘. iteration halts when either of the following conditions is satisified: - 1. Iteration converges to the fixpoint, with equality being tested - using EQUAL-TEST. If EQUAL-TEST is not specified, ‘equal’ is used. - For functions over the floating point numbers, it may be necessary - to provide an appropriate appoximate comparsion test. + 1. Iteration converges to the fixpoint, with equality being + tested using EQUAL-TEST. If EQUAL-TEST is not specified, ‘equal’ + is used. For functions over the floating point numbers, it may + be necessary to provide an appropriate appoximate comparsion + test. 2. HALT-TEST returns a non-nil value. HALT-TEST defaults to a simple counter that returns t after ‘-fixfn-max-iterations’, to guard against infinite iteration. Otherwise, HALT-TEST must be a function that accepts a single argument, the current value of X, - and returns non-nil as long as iteration should continue. In this - way, a more sophisticated convergence test may be supplied by the - caller. + and returns non-nil as long as iteration should continue. In + this way, a more sophisticated convergence test may be supplied + by the caller. The return value of the lambda is either the fixpoint or, if iteration halted before converging, a cons with car ‘halted’ and @@ -2391,9 +2417,9 @@ offered in a separate package: ‘dash-functional‘. ⇒ '(halted . t) -- Function: -prodfn (&rest fns) - Take a list of n functions and return a function that takes a list - of length n, applying i-th function to i-th element of the input - list. Returns a list of length n. + Take a list of n functions and return a function that takes a + list of length n, applying i-th function to i-th element of the + input list. Returns a list of length n. In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) @@ -2401,10 +2427,10 @@ offered in a separate package: ‘dash-functional‘. (-compose (-prodfn f g ...) (-prodfn f’ g’ ...)) = (-prodfn (-compose f f’) (-compose g g’) ...) (-prodfn f g ...) = (-juxt - (-compose f (-partial ’nth 0)) (-compose g (-partial ’nth 1)) ...) - (-compose (-prodfn f g ...) (-juxt f’ g’ ...)) = (-juxt (-compose - f f’) (-compose g g’) ...) (-compose (-partial ’nth n) (-prod f1 - f2 ...)) = (-compose fn (-partial ’nth n)) + (-compose f (-partial ’nth 0)) (-compose g (-partial ’nth 1)) + ...) (-compose (-prodfn f g ...) (-juxt f’ g’ ...)) = (-juxt + (-compose f f’) (-compose g g’) ...) (-compose (-partial ’nth n) + (-prod f1 f2 ...)) = (-compose fn (-partial ’nth n)) (funcall (-prodfn '1+ '1- 'int-to-string) '(1 2 3)) ⇒ '(2 1 "3") @@ -2435,8 +2461,8 @@ File: dash.info, Node: Contribute, Next: Changes, Up: Development ============== Yes, please do. Pure functions in the list manipulation realm only, -please. There’s a suite of tests in dev/examples.el, so remember to add -tests for your function, or it might get broken later. +please. There’s a suite of tests in dev/examples.el, so remember to +add tests for your function, or it might get broken later. Run the tests with ‘./run-tests.sh’. Create the docs with ‘./create-docs.sh’. I highly recommend that you install these as a @@ -2446,8 +2472,8 @@ always in sync: cp pre-commit.sh .git/hooks/pre-commit Oh, and don’t edit ‘README.md’ directly, it is auto-generated. -Change ‘readme-template.md’ or ‘examples-to-docs.el’ instead. The same -goes for the info manual. +Change ‘readme-template.md’ or ‘examples-to-docs.el’ instead. The +same goes for the info manual.  File: dash.info, Node: Changes, Next: Contributors, Prev: Contribute, Up: Development @@ -2520,8 +2546,8 @@ Changes in 2.1: Changes in 2.0: • Split out ‘dash-functional.el’ (Matus Goljer) - • Add ‘-andfn’, ‘-orfn’, ‘-not’, ‘-cut’, ‘-const’, ‘-flip’ and ‘-on’. - (Matus Goljer) + • Add ‘-andfn’, ‘-orfn’, ‘-not’, ‘-cut’, ‘-const’, ‘-flip’ and + ‘-on’. (Matus Goljer) • Fix ‘-min’, ‘-max’, ‘-min-by’ and ‘-max-by’ (Matus Goljer) Changes in 1.8: @@ -2567,7 +2593,8 @@ File: dash.info, Node: Contributors, Prev: Changes, Up: Development • Matus Goljer (https://github.com/Fuco1) contributed lots of features and functions. - • Takafumi Arakaki (https://github.com/tkf) contributed ‘-group-by’. + • Takafumi Arakaki (https://github.com/tkf) contributed + ‘-group-by’. • tali713 (https://github.com/tali713) is the author of ‘-applify’. • Víctor M. Valenzuela (https://github.com/vemv) contributed ‘-repeat’. @@ -2582,9 +2609,9 @@ File: dash.info, Node: Contributors, Prev: Changes, Up: Development ‘-compose’ • Steve Lamb (https://github.com/steventlamb) contributed ‘-cycle’, ‘-pad’, ‘-annotate’, ‘-zip-fill’ and an n-ary version of ‘-zip’. - • Fredrik Bergroth (https://github.com/fbergroth) made the ‘-if-let’ - family use ‘-let’ destructuring and improved script for generating - documentation. + • Fredrik Bergroth (https://github.com/fbergroth) made the + ‘-if-let’ family use ‘-let’ destructuring and improved script for + generating documentation. • Mark Oteiza (https://github.com/holomorph) contributed the script to create an info manual. • Vasilij Schneidermann (https://github.com/wasamasa) contributed @@ -2604,194 +2631,196 @@ Index * Menu: * !cdr: Destructive operations. - (line 14) + (line 14) * !cons: Destructive operations. - (line 6) -* -->: Threading macros. (line 32) -* ->: Threading macros. (line 6) -* ->>: Threading macros. (line 19) -* -all?: Predicates. (line 18) + (line 6) +* -->: Threading macros. (line 32) +* ->: Threading macros. (line 6) +* ->>: Threading macros. (line 19) +* -all?: Predicates. (line 18) * -andfn: Function combinators. - (line 138) -* -annotate: Maps. (line 79) -* -any?: Predicates. (line 6) + (line 152) +* -annotate: Maps. (line 80) +* -any?: Predicates. (line 6) * -applify: Function combinators. - (line 55) + (line 68) * -butlast: Other list operations. - (line 260) -* -clone: Tree operations. (line 122) + (line 264) +* -clone: Tree operations. (line 123) * -compose: Function combinators. - (line 42) -* -concat: List to list. (line 22) + (line 54) +* -concat: List to list. (line 22) * -cons*: Other list operations. - (line 28) + (line 28) * -const: Function combinators. - (line 92) -* -contains?: Predicates. (line 57) -* -copy: Maps. (line 134) -* -count: Reductions. (line 89) + (line 105) +* -contains?: Predicates. (line 57) +* -copy: Maps. (line 135) +* -count: Reductions. (line 89) * -cut: Function combinators. - (line 104) + (line 118) * -cycle: Other list operations. - (line 139) -* -difference: Set operations. (line 20) -* -distinct: Set operations. (line 44) -* -dotimes: Side-effects. (line 41) -* -doto: Side-effects. (line 50) -* -drop: Sublist selection. (line 122) -* -drop-last: Sublist selection. (line 134) -* -drop-while: Sublist selection. (line 155) -* -each: Side-effects. (line 8) -* -each-indexed: Side-effects. (line 28) -* -each-while: Side-effects. (line 19) -* -elem-index: Indexing. (line 9) -* -elem-indices: Indexing. (line 21) -* -filter: Sublist selection. (line 8) -* -find-index: Indexing. (line 32) -* -find-indices: Indexing. (line 60) -* -find-last-index: Indexing. (line 46) + (line 139) +* -difference: Set operations. (line 20) +* -distinct: Set operations. (line 44) +* -dotimes: Side-effects. (line 41) +* -doto: Side-effects. (line 50) +* -drop: Sublist selection. (line 123) +* -drop-last: Sublist selection. (line 135) +* -drop-while: Sublist selection. (line 156) +* -each: Side-effects. (line 8) +* -each-indexed: Side-effects. (line 28) +* -each-while: Side-effects. (line 19) +* -elem-index: Indexing. (line 9) +* -elem-indices: Indexing. (line 21) +* -filter: Sublist selection. (line 8) +* -find-index: Indexing. (line 32) +* -find-indices: Indexing. (line 60) +* -find-last-index: Indexing. (line 46) * -first: Other list operations. - (line 205) + (line 205) * -first-item: Other list operations. - (line 242) + (line 242) * -fix: Other list operations. - (line 296) + (line 300) * -fixfn: Function combinators. - (line 175) -* -flatten: List to list. (line 33) -* -flatten-n: List to list. (line 55) + (line 189) +* -flatten: List to list. (line 33) +* -flatten-n: List to list. (line 55) * -flip: Function combinators. - (line 80) -* -grade-down: Indexing. (line 81) -* -grade-up: Indexing. (line 71) -* -group-by: Partitioning. (line 145) -* -if-let: Binding. (line 35) -* -if-let*: Binding. (line 46) -* -insert-at: List to list. (line 109) + (line 93) +* -grade-down: Indexing. (line 81) +* -grade-up: Indexing. (line 71) +* -group-by: Partitioning. (line 145) +* -if-let: Binding. (line 36) +* -if-let*: Binding. (line 47) +* -insert-at: List to list. (line 109) * -interleave: Other list operations. - (line 66) + (line 66) * -interpose: Other list operations. - (line 56) -* -intersection: Set operations. (line 32) -* -is-infix?: Predicates. (line 110) -* -is-prefix?: Predicates. (line 86) -* -is-suffix?: Predicates. (line 98) -* -iterate: Unfolding. (line 9) + (line 56) +* -intersection: Set operations. (line 32) +* -is-infix?: Predicates. (line 110) +* -is-prefix?: Predicates. (line 86) +* -is-suffix?: Predicates. (line 98) +* -iterate: Unfolding. (line 9) * -iteratefn: Function combinators. - (line 152) + (line 166) * -juxt: Function combinators. - (line 31) -* -keep: List to list. (line 8) -* -lambda: Binding. (line 216) + (line 43) +* -keep: List to list. (line 8) +* -lambda: Binding. (line 217) * -last: Other list operations. - (line 232) + (line 232) * -last-item: Other list operations. - (line 252) -* -let: Binding. (line 62) -* -let*: Binding. (line 196) + (line 254) +* -let: Binding. (line 63) +* -let*: Binding. (line 197) * -list: Other list operations. - (line 283) -* -map: Maps. (line 10) -* -map-first: Maps. (line 37) -* -map-indexed: Maps. (line 65) -* -map-last: Maps. (line 51) -* -map-when: Maps. (line 21) -* -mapcat: Maps. (line 123) -* -max: Reductions. (line 141) -* -max-by: Reductions. (line 151) -* -min: Reductions. (line 117) -* -min-by: Reductions. (line 127) -* -non-nil: Sublist selection. (line 77) -* -none?: Predicates. (line 30) + (line 287) +* -map: Maps. (line 10) +* -map-first: Maps. (line 38) +* -map-indexed: Maps. (line 66) +* -map-last: Maps. (line 52) +* -map-when: Maps. (line 21) +* -mapcat: Maps. (line 124) +* -max: Reductions. (line 141) +* -max-by: Reductions. (line 151) +* -min: Reductions. (line 117) +* -min-by: Reductions. (line 127) +* -non-nil: Sublist selection. (line 78) +* -none?: Predicates. (line 30) * -not: Function combinators. - (line 117) + (line 131) +* -npartial: Function combinators. + (line 31) * -on: Function combinators. - (line 66) -* -only-some?: Predicates. (line 42) + (line 79) +* -only-some?: Predicates. (line 42) * -orfn: Function combinators. - (line 126) + (line 140) * -pad: Other list operations. - (line 150) + (line 150) * -partial: Function combinators. - (line 9) -* -partition: Partitioning. (line 74) -* -partition-all: Partitioning. (line 86) -* -partition-all-in-steps: Partitioning. (line 109) -* -partition-by: Partitioning. (line 121) -* -partition-by-header: Partitioning. (line 132) -* -partition-in-steps: Partitioning. (line 97) + (line 9) +* -partition: Partitioning. (line 74) +* -partition-all: Partitioning. (line 86) +* -partition-all-in-steps: Partitioning. (line 109) +* -partition-by: Partitioning. (line 121) +* -partition-by-header: Partitioning. (line 132) +* -partition-in-steps: Partitioning. (line 97) * -prodfn: Function combinators. - (line 209) -* -product: Reductions. (line 107) -* -reduce: Reductions. (line 46) -* -reduce-from: Reductions. (line 8) -* -reduce-r: Reductions. (line 66) -* -reduce-r-from: Reductions. (line 27) -* -remove: Sublist selection. (line 23) -* -remove-at: List to list. (line 145) -* -remove-at-indices: List to list. (line 158) -* -remove-first: Sublist selection. (line 35) -* -remove-item: Sublist selection. (line 65) -* -remove-last: Sublist selection. (line 50) + (line 224) +* -product: Reductions. (line 107) +* -reduce: Reductions. (line 46) +* -reduce-from: Reductions. (line 8) +* -reduce-r: Reductions. (line 66) +* -reduce-r-from: Reductions. (line 27) +* -remove: Sublist selection. (line 23) +* -remove-at: List to list. (line 146) +* -remove-at-indices: List to list. (line 159) +* -remove-first: Sublist selection. (line 36) +* -remove-item: Sublist selection. (line 66) +* -remove-last: Sublist selection. (line 51) * -repeat: Other list operations. - (line 17) -* -replace: List to list. (line 67) -* -replace-at: List to list. (line 120) -* -replace-first: List to list. (line 81) -* -replace-last: List to list. (line 95) + (line 17) +* -replace: List to list. (line 67) +* -replace-at: List to list. (line 120) +* -replace-first: List to list. (line 81) +* -replace-last: List to list. (line 95) * -rotate: Other list operations. - (line 8) + (line 8) * -rpartial: Function combinators. - (line 20) -* -same-items?: Predicates. (line 72) -* -select-by-indices: Sublist selection. (line 166) -* -select-column: Sublist selection. (line 196) -* -select-columns: Sublist selection. (line 177) -* -separate: Partitioning. (line 63) -* -slice: Sublist selection. (line 83) + (line 20) +* -same-items?: Predicates. (line 72) +* -select-by-indices: Sublist selection. (line 167) +* -select-column: Sublist selection. (line 197) +* -select-columns: Sublist selection. (line 178) +* -separate: Partitioning. (line 63) +* -slice: Sublist selection. (line 84) * -snoc: Other list operations. - (line 42) + (line 42) * -some: Other list operations. - (line 219) -* -some-->: Threading macros. (line 69) -* -some->: Threading macros. (line 45) -* -some->>: Threading macros. (line 57) + (line 219) +* -some-->: Threading macros. (line 69) +* -some->: Threading macros. (line 45) +* -some->>: Threading macros. (line 57) * -sort: Other list operations. - (line 270) -* -splice: Maps. (line 90) -* -splice-list: Maps. (line 110) -* -split-at: Partitioning. (line 8) -* -split-on: Partitioning. (line 28) -* -split-when: Partitioning. (line 46) -* -split-with: Partitioning. (line 17) -* -sum: Reductions. (line 97) + (line 274) +* -splice: Maps. (line 91) +* -splice-list: Maps. (line 111) +* -split-at: Partitioning. (line 8) +* -split-on: Partitioning. (line 28) +* -split-when: Partitioning. (line 46) +* -split-with: Partitioning. (line 17) +* -sum: Reductions. (line 97) * -table: Other list operations. - (line 161) + (line 161) * -table-flat: Other list operations. - (line 180) -* -take: Sublist selection. (line 99) -* -take-last: Sublist selection. (line 110) -* -take-while: Sublist selection. (line 144) -* -tree-map: Tree operations. (line 28) -* -tree-map-nodes: Tree operations. (line 39) -* -tree-mapreduce: Tree operations. (line 84) -* -tree-mapreduce-from: Tree operations. (line 103) -* -tree-reduce: Tree operations. (line 52) -* -tree-reduce-from: Tree operations. (line 69) -* -tree-seq: Tree operations. (line 8) -* -unfold: Unfolding. (line 25) -* -union: Set operations. (line 8) + (line 180) +* -take: Sublist selection. (line 100) +* -take-last: Sublist selection. (line 111) +* -take-while: Sublist selection. (line 145) +* -tree-map: Tree operations. (line 28) +* -tree-map-nodes: Tree operations. (line 39) +* -tree-mapreduce: Tree operations. (line 85) +* -tree-mapreduce-from: Tree operations. (line 104) +* -tree-reduce: Tree operations. (line 53) +* -tree-reduce-from: Tree operations. (line 70) +* -tree-seq: Tree operations. (line 8) +* -unfold: Unfolding. (line 25) +* -union: Set operations. (line 8) * -unzip: Other list operations. - (line 122) -* -update-at: List to list. (line 132) -* -when-let: Binding. (line 9) -* -when-let*: Binding. (line 22) + (line 122) +* -update-at: List to list. (line 133) +* -when-let: Binding. (line 9) +* -when-let*: Binding. (line 22) * -zip: Other list operations. - (line 93) + (line 93) * -zip-fill: Other list operations. - (line 114) + (line 114) * -zip-with: Other list operations. - (line 77) + (line 77)  @@ -2804,173 +2833,174 @@ Node: Functions3749 Node: Maps4960 Ref: -map5255 Ref: -map-when5596 -Ref: -map-first6174 -Ref: -map-last6652 -Ref: -map-indexed7126 -Ref: -annotate7599 -Ref: -splice8089 -Ref: -splice-list8870 -Ref: -mapcat9332 -Ref: -copy9708 -Node: Sublist selection9912 -Ref: -filter10105 -Ref: -remove10523 -Ref: -remove-first10880 -Ref: -remove-last11407 -Ref: -remove-item11928 -Ref: -non-nil12322 -Ref: -slice12481 -Ref: -take13013 -Ref: -take-last13321 -Ref: -drop13644 -Ref: -drop-last13917 -Ref: -take-while14177 -Ref: -drop-while14527 -Ref: -select-by-indices14883 -Ref: -select-columns15397 -Ref: -select-column16103 -Node: List to list16567 -Ref: -keep16754 -Ref: -concat17257 -Ref: -flatten17554 -Ref: -flatten-n18313 -Ref: -replace18700 -Ref: -replace-first19163 -Ref: -replace-last19659 -Ref: -insert-at20148 -Ref: -replace-at20475 -Ref: -update-at20865 -Ref: -remove-at21356 -Ref: -remove-at-indices21844 -Node: Reductions22426 -Ref: -reduce-from22595 -Ref: -reduce-r-from23374 -Ref: -reduce24159 -Ref: -reduce-r24960 -Ref: -count25877 -Ref: -sum26101 -Ref: -product26290 -Ref: -min26499 -Ref: -min-by26725 -Ref: -max27248 -Ref: -max-by27473 -Node: Unfolding28001 -Ref: -iterate28240 -Ref: -unfold28685 -Node: Predicates29493 -Ref: -any?29617 -Ref: -all?29945 -Ref: -none?30275 -Ref: -only-some?30577 -Ref: -contains?31062 -Ref: -same-items?31451 -Ref: -is-prefix?31836 -Ref: -is-suffix?32159 -Ref: -is-infix?32482 -Node: Partitioning32836 -Ref: -split-at33024 -Ref: -split-with33309 -Ref: -split-on33712 -Ref: -split-when34388 -Ref: -separate35028 -Ref: -partition35470 -Ref: -partition-all35922 -Ref: -partition-in-steps36350 -Ref: -partition-all-in-steps36847 -Ref: -partition-by37332 -Ref: -partition-by-header37714 -Ref: -group-by38318 -Node: Indexing38755 -Ref: -elem-index38957 -Ref: -elem-indices39352 -Ref: -find-index39735 -Ref: -find-last-index40224 -Ref: -find-indices40728 -Ref: -grade-up41136 -Ref: -grade-down41539 -Node: Set operations41949 -Ref: -union42132 -Ref: -difference42574 -Ref: -intersection42991 -Ref: -distinct43428 -Node: Other list operations43752 -Ref: -rotate43977 -Ref: -repeat44272 -Ref: -cons*44535 -Ref: -snoc44922 -Ref: -interpose45335 -Ref: -interleave45633 -Ref: -zip-with46002 -Ref: -zip46705 -Ref: -zip-fill47511 -Ref: -unzip47834 -Ref: -cycle48368 -Ref: -pad48741 -Ref: -table49064 -Ref: -table-flat49853 -Ref: -first50861 -Ref: -some51235 -Ref: -last51605 -Ref: -first-item51939 -Ref: -last-item52154 -Ref: -butlast52349 -Ref: -sort52596 -Ref: -list53085 -Ref: -fix53416 -Node: Tree operations53956 -Ref: -tree-seq54152 -Ref: -tree-map55010 -Ref: -tree-map-nodes55453 -Ref: -tree-reduce56303 -Ref: -tree-reduce-from57185 -Ref: -tree-mapreduce57786 -Ref: -tree-mapreduce-from58646 -Ref: -clone59932 -Node: Threading macros60260 -Ref: ->60405 -Ref: ->>60896 -Ref: -->61401 -Ref: -some->61927 -Ref: -some->>62301 -Ref: -some-->62737 -Node: Binding63208 -Ref: -when-let63420 -Ref: -when-let*63914 -Ref: -if-let64437 -Ref: -if-let*64832 -Ref: -let65449 -Ref: -let*70244 -Ref: -lambda71184 -Node: Side-effects71981 -Ref: -each72175 -Ref: -each-while72582 -Ref: -each-indexed72942 -Ref: -dotimes73453 -Ref: -doto73756 -Node: Destructive operations74184 -Ref: !cons74357 -Ref: !cdr74563 -Node: Function combinators74758 -Ref: -partial75032 -Ref: -rpartial75428 -Ref: -juxt75831 -Ref: -compose76263 -Ref: -applify76816 -Ref: -on77263 -Ref: -flip77786 -Ref: -const78098 -Ref: -cut78437 -Ref: -not78923 -Ref: -orfn79233 -Ref: -andfn79667 -Ref: -iteratefn80162 -Ref: -fixfn80865 -Ref: -prodfn82428 -Node: Development83490 -Node: Contribute83839 -Node: Changes84587 -Node: Contributors87585 -Node: Index89204 +Ref: -map-first6179 +Ref: -map-last6657 +Ref: -map-indexed7131 +Ref: -annotate7604 +Ref: -splice8094 +Ref: -splice-list8875 +Ref: -mapcat9337 +Ref: -copy9713 +Node: Sublist selection9917 +Ref: -filter10110 +Ref: -remove10528 +Ref: -remove-first10890 +Ref: -remove-last11417 +Ref: -remove-item11938 +Ref: -non-nil12332 +Ref: -slice12491 +Ref: -take13023 +Ref: -take-last13331 +Ref: -drop13654 +Ref: -drop-last13927 +Ref: -take-while14187 +Ref: -drop-while14537 +Ref: -select-by-indices14893 +Ref: -select-columns15407 +Ref: -select-column16112 +Node: List to list16575 +Ref: -keep16762 +Ref: -concat17265 +Ref: -flatten17562 +Ref: -flatten-n18321 +Ref: -replace18708 +Ref: -replace-first19171 +Ref: -replace-last19667 +Ref: -insert-at20156 +Ref: -replace-at20483 +Ref: -update-at20878 +Ref: -remove-at21369 +Ref: -remove-at-indices21857 +Node: Reductions22439 +Ref: -reduce-from22608 +Ref: -reduce-r-from23387 +Ref: -reduce24172 +Ref: -reduce-r24973 +Ref: -count25889 +Ref: -sum26113 +Ref: -product26302 +Ref: -min26511 +Ref: -min-by26737 +Ref: -max27260 +Ref: -max-by27485 +Node: Unfolding28013 +Ref: -iterate28252 +Ref: -unfold28697 +Node: Predicates29505 +Ref: -any?29629 +Ref: -all?29957 +Ref: -none?30287 +Ref: -only-some?30589 +Ref: -contains?31074 +Ref: -same-items?31463 +Ref: -is-prefix?31848 +Ref: -is-suffix?32171 +Ref: -is-infix?32494 +Node: Partitioning32848 +Ref: -split-at33036 +Ref: -split-with33321 +Ref: -split-on33724 +Ref: -split-when34400 +Ref: -separate35040 +Ref: -partition35482 +Ref: -partition-all35934 +Ref: -partition-in-steps36362 +Ref: -partition-all-in-steps36859 +Ref: -partition-by37344 +Ref: -partition-by-header37726 +Ref: -group-by38330 +Node: Indexing38767 +Ref: -elem-index38969 +Ref: -elem-indices39364 +Ref: -find-index39747 +Ref: -find-last-index40236 +Ref: -find-indices40740 +Ref: -grade-up41148 +Ref: -grade-down41551 +Node: Set operations41961 +Ref: -union42144 +Ref: -difference42586 +Ref: -intersection43003 +Ref: -distinct43440 +Node: Other list operations43764 +Ref: -rotate43989 +Ref: -repeat44284 +Ref: -cons*44547 +Ref: -snoc44934 +Ref: -interpose45347 +Ref: -interleave45645 +Ref: -zip-with46014 +Ref: -zip46717 +Ref: -zip-fill47523 +Ref: -unzip47846 +Ref: -cycle48380 +Ref: -pad48753 +Ref: -table49076 +Ref: -table-flat49866 +Ref: -first50875 +Ref: -some51249 +Ref: -last51619 +Ref: -first-item51953 +Ref: -last-item52266 +Ref: -butlast52558 +Ref: -sort52805 +Ref: -list53293 +Ref: -fix53624 +Node: Tree operations54164 +Ref: -tree-seq54360 +Ref: -tree-map55218 +Ref: -tree-map-nodes55661 +Ref: -tree-reduce56516 +Ref: -tree-reduce-from57398 +Ref: -tree-mapreduce57999 +Ref: -tree-mapreduce-from58859 +Ref: -clone60145 +Node: Threading macros60473 +Ref: ->60618 +Ref: ->>61110 +Ref: -->61615 +Ref: -some->62141 +Ref: -some->>62515 +Ref: -some-->62951 +Node: Binding63422 +Ref: -when-let63634 +Ref: -when-let*64128 +Ref: -if-let64656 +Ref: -if-let*65051 +Ref: -let65668 +Ref: -let*70461 +Ref: -lambda71402 +Node: Side-effects72204 +Ref: -each72398 +Ref: -each-while72805 +Ref: -each-indexed73165 +Ref: -dotimes73676 +Ref: -doto73979 +Node: Destructive operations74406 +Ref: !cons74579 +Ref: !cdr74785 +Node: Function combinators74980 +Ref: -partial75254 +Ref: -rpartial75649 +Ref: -npartial76051 +Ref: -juxt76591 +Ref: -compose77023 +Ref: -applify77581 +Ref: -on78028 +Ref: -flip78551 +Ref: -const78863 +Ref: -cut79207 +Ref: -not79693 +Ref: -orfn80003 +Ref: -andfn80437 +Ref: -iteratefn80932 +Ref: -fixfn81635 +Ref: -prodfn83204 +Node: Development84267 +Node: Contribute84616 +Node: Changes85364 +Node: Contributors88363 +Node: Index89987  End Tag Table diff --git a/dash.texi b/dash.texi index 94d8ec92..8c9a5a93 100644 --- a/dash.texi +++ b/dash.texi @@ -2524,6 +2524,10 @@ Return the first item of @var{list}, or nil on an empty list. (-first-item nil) @result{} nil @end group +@group +(let ((list (list 1 2 3))) (setf (-first-item list) 5) list) + @result{} '(5 2 3) +@end group @end example @end defun @@ -2540,6 +2544,10 @@ Return the last item of @var{list}, or nil on an empty list. (-last-item nil) @result{} nil @end group +@group +(let ((list (list 1 2 3))) (setf (-last-item list) 5) list) + @result{} '(1 2 5) +@end group @end example @end defun @@ -3451,6 +3459,26 @@ args first and then @var{args}. @end example @end defun +@anchor{-npartial} +@defun -npartial (n fn &rest args) +Takes an offset @var{n}, a function @var{fn} and fewer than the normal +arguments to @var{fn}, and returns a function which takes a variable +number of additional @var{args}. When called, the returned function +calls @var{fn} with the first @var{n} additional args first, then @var{args}, then +the remaining additional args. + +@example +@group +(funcall (-npartial 1 (lambda (a b c) (+ a (* b c))) 5) 2 3) + @result{} 17 +@end group +@group +(funcall (-npartial 2 (lambda (a b c d) (+ a (* b c) d)) 3) 2 4 5) + @result{} 19 +@end group +@end example +@end defun + @anchor{-juxt} @defun -juxt (&rest fns) Takes a list of functions and returns a fn that is the diff --git a/dev/examples.el b/dev/examples.el index a35ae338..353b14c5 100644 --- a/dev/examples.el +++ b/dev/examples.el @@ -1055,6 +1055,10 @@ new list." (funcall (-rpartial '- 5) 8) => 3 (funcall (-rpartial '- 5 2) 10) => 3) + (defexamples -npartial + (funcall (-npartial 1 (lambda (a b c) (+ a (* b c))) 5) 2 3) => 17 + (funcall (-npartial 2 (lambda (a b c d) (+ a (* b c) d)) 3) 2 4 5) => 19) + (defexamples -juxt (funcall (-juxt '+ '-) 3 5) => '(8 -2) (-map (-juxt 'identity 'square) '(1 2 3)) => '((1 1) (2 4) (3 9)))