nixpkgs/lib/lists.nix

436 lines
11 KiB
Nix
Raw Normal View History

# General list operations.
2013-11-12 12:48:19 +00:00
with import ./trivial.nix;
rec {
2013-11-12 12:48:19 +00:00
inherit (builtins) head tail length isList elemAt concatLists filter elem genList;
2016-02-28 23:27:06 +00:00
/* Create a list consisting of a single element. `singleton x' is
sometimes more convenient with respect to indentation than `[x]'
when x spans multiple lines.
Example:
singleton "foo"
=> [ "foo" ]
*/
singleton = x: [x];
2016-02-28 23:27:06 +00:00
/* "Fold" a binary function `op' between successive elements of
`list' with `nul' as the starting value, i.e., `fold op nul [x_1
x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul))'. (This is
Haskell's foldr).
2016-02-28 23:27:06 +00:00
Example:
concat = fold (a: b: a + b) "z"
concat [ "a" "b" "c" ]
=> "abcnul"
*/
fold = op: nul: list:
let
len = length list;
fold' = n:
if n == len
then nul
else op (elemAt list n) (fold' (n + 1));
in fold' 0;
2016-02-28 23:27:06 +00:00
/* Left fold: `fold op nul [x_1 x_2 ... x_n] == op (... (op (op nul
x_1) x_2) ... x_n)'.
Example:
lconcat = foldl (a: b: a + b) "z"
lconcat [ "a" "b" "c" ]
=> "zabc"
*/
foldl = op: nul: list:
let
len = length list;
foldl' = n:
if n == -1
then nul
else op (foldl' (n - 1)) (elemAt list n);
in foldl' (length list - 1);
2016-02-28 23:27:06 +00:00
/* Strict version of foldl.
2016-02-28 23:27:06 +00:00
The difference is that evaluation is forced upon access. Usually used
with small whole results (in contract with lazily-generated list or large
lists where only a part is consumed.)
*/
foldl' = builtins.foldl' or foldl;
2016-02-28 23:27:06 +00:00
/* Map with index
FIXME(zimbatm): why does this start to count at 1?
2016-02-28 23:27:06 +00:00
Example:
imap (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-1" "b-2" ]
*/
imap =
if builtins ? genList then
f: list: genList (n: f (n + 1) (elemAt list n)) (length list)
else
f: list:
let
len = length list;
imap' = n:
if n == len
then []
else [ (f (n + 1) (elemAt list n)) ] ++ imap' (n + 1);
in imap' 0;
2016-02-28 23:27:06 +00:00
/* Map and concatenate the result.
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
Example:
concatMap (x: [x] ++ ["z"]) ["a" "b"]
=> [ "a" "z" "b" "z" ]
*/
concatMap = f: list: concatLists (map f list);
2016-02-28 23:27:06 +00:00
/* Flatten the argument into a single list; that is, nested lists are
spliced into the top-level lists.
2016-02-28 23:27:06 +00:00
Example:
flatten [1 [2 [3] 4] 5]
=> [1 2 3 4 5]
flatten 1
=> [1]
*/
flatten = x:
if isList x
then foldl' (x: y: x ++ (flatten y)) [] x
else [x];
2016-02-28 23:27:06 +00:00
/* Remove elements equal to 'e' from a list. Useful for buildInputs.
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
Example:
remove 3 [ 1 3 4 3 ]
=> [ 1 4 ]
*/
remove = e: filter (x: x != e);
2016-02-28 23:27:06 +00:00
/* Find the sole element in the list matching the specified
predicate, returns `default' if no such element exists, or
`multiple' if there are multiple matching elements.
Example:
findSingle (x: x == 3) "none" "multiple" [ 1 3 3 ]
=> "multiple"
findSingle (x: x == 3) "none" "multiple" [ 1 3 ]
=> 3
findSingle (x: x == 3) "none" "multiple" [ 1 9 ]
=> "none"
*/
findSingle = pred: default: multiple: list:
let found = filter pred list; len = length found;
in if len == 0 then default
else if len != 1 then multiple
else head found;
2016-02-28 23:27:06 +00:00
/* Find the first element in the list matching the specified
predicate or returns `default' if no such element exists.
2016-02-28 23:27:06 +00:00
Example:
findFirst (x: x > 3) 7 [ 1 6 4 ]
=> 6
findFirst (x: x > 9) 7 [ 1 6 4 ]
=> 7
*/
findFirst = pred: default: list:
let found = filter pred list;
in if found == [] then default else head found;
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
/* Return true iff function `pred' returns true for at least element
of `list'.
2016-02-28 23:27:06 +00:00
Example:
any isString [ 1 "a" { } ]
=> true
any isString [ 1 { } ]
=> false
*/
2015-07-23 17:25:58 +00:00
any = builtins.any or (pred: fold (x: y: if pred x then true else y) false);
2016-02-28 23:27:06 +00:00
/* Return true iff function `pred' returns true for all elements of
`list'.
2016-02-28 23:27:06 +00:00
Example:
all (x: x < 3) [ 1 2 ]
=> true
all (x: x < 3) [ 1 2 3 ]
=> false
*/
2015-07-23 17:25:58 +00:00
all = builtins.all or (pred: fold (x: y: if pred x then y else false) true);
2016-02-28 23:27:06 +00:00
/* Count how many times function `pred' returns true for the elements
of `list'.
2016-02-28 23:27:06 +00:00
Example:
count (x: x == 3) [ 3 2 3 4 6 ]
=> 2
*/
count = pred: foldl' (c: x: if pred x then c + 1 else c) 0;
2016-02-28 23:27:06 +00:00
/* Return a singleton list or an empty list, depending on a boolean
value. Useful when building lists with optional elements
(e.g. `++ optional (system == "i686-linux") flashplayer').
2016-02-28 23:27:06 +00:00
Example:
optional true "foo"
=> [ "foo" ]
optional false "foo"
=> [ ]
*/
optional = cond: elem: if cond then [elem] else [];
2016-02-28 23:27:06 +00:00
/* Return a list or an empty list, dependening on a boolean value.
2016-02-28 23:27:06 +00:00
Example:
optionals true [ 2 3 ]
=> [ 2 3 ]
optionals false [ 2 3 ]
=> [ ]
*/
optionals = cond: elems: if cond then elems else [];
2016-02-28 23:27:06 +00:00
/* If argument is a list, return it; else, wrap it in a singleton
list. If you're using this, you should almost certainly
reconsider if there isn't a more "well-typed" approach.
Example:
toList [ 1 2 ]
=> [ 1 2 ]
toList "hi"
=> [ "hi "]
*/
2013-11-12 12:48:19 +00:00
toList = x: if isList x then x else [x];
2016-02-28 23:27:06 +00:00
/* Return a list of integers from `first' up to and including `last'.
2016-02-28 23:27:06 +00:00
Example:
range 2 4
=> [ 2 3 4 ]
range 3 2
=> [ ]
*/
range =
if builtins ? genList then
first: last:
if first > last
then []
else genList (n: first + n) (last - first + 1)
else
first: last:
if last < first
then []
else [first] ++ range (first + 1) last;
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
/* Splits the elements of a list in two lists, `right' and
`wrong', depending on the evaluation of a predicate.
2016-02-28 23:27:06 +00:00
Example:
partition (x: x > 2) [ 5 1 2 3 4 ]
=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }
*/
partition = pred:
fold (h: t:
if pred h
then { right = [h] ++ t.right; wrong = t.wrong; }
else { right = t.right; wrong = [h] ++ t.wrong; }
) { right = []; wrong = []; };
2016-02-28 23:27:06 +00:00
/* Merges two lists of the same size together. If the sizes aren't the same
the merging stops at the shortest. How both lists are merged is defined
by the first argument.
2016-02-28 23:27:06 +00:00
Example:
zipListsWith (a: b: a + b) ["h" "l"] ["e" "o"]
=> ["he" "lo"]
*/
zipListsWith =
if builtins ? genList then
f: fst: snd: genList (n: f (elemAt fst n) (elemAt snd n)) (min (length fst) (length snd))
else
f: fst: snd:
let
len = min (length fst) (length snd);
zipListsWith' = n:
if n != len then
[ (f (elemAt fst n) (elemAt snd n)) ]
++ zipListsWith' (n + 1)
else [];
in zipListsWith' 0;
2016-02-28 23:27:06 +00:00
/* Merges two lists of the same size together. If the sizes aren't the same
the merging stops at the shortest.
Example:
zipLists [ 1 2 ] [ "a" "b" ]
=> [ { fst = 1; snd = "a"; } { fst = 2; snd = "b"; } ]
*/
zipLists = zipListsWith (fst: snd: { inherit fst snd; });
2016-02-28 23:27:06 +00:00
/* Reverse the order of the elements of a list.
2016-02-28 23:27:06 +00:00
Example:
reverseList [ "b" "o" "j" ]
=> [ "j" "o" "b" ]
*/
reverseList =
if builtins ? genList then
xs: let l = length xs; in genList (n: elemAt xs (l - n - 1)) l
else
fold (e: acc: acc ++ [ e ]) [];
2016-02-28 23:27:06 +00:00
/* Sort a list based on a comparator function which compares two
elements and returns true if the first argument is strictly below
the second argument. The returned list is sorted in an increasing
order. The implementation does a quick-sort.
2016-02-28 23:27:06 +00:00
Example:
sort (a: b: a < b) [ 5 3 7 ]
=> [ 3 5 7 ]
*/
2015-07-28 16:42:04 +00:00
sort = builtins.sort or (
strictLess: list:
let
len = length list;
first = head list;
pivot' = n: acc@{ left, right }: let el = elemAt list n; next = pivot' (n + 1); in
if n == len
then acc
else if strictLess first el
then next { inherit left; right = [ el ] ++ right; }
else
next { left = [ el ] ++ left; inherit right; };
pivot = pivot' 1 { left = []; right = []; };
in
if len < 2 then list
2015-07-28 16:42:04 +00:00
else (sort strictLess pivot.left) ++ [ first ] ++ (sort strictLess pivot.right));
2016-02-28 23:27:06 +00:00
/* Return the first (at most) N elements of a list.
2016-02-28 23:27:06 +00:00
Example:
take 2 [ "a" "b" "c" "d" ]
=> [ "a" "b" ]
take 2 [ ]
=> [ ]
*/
take =
if builtins ? genList then
count: sublist 0 count
else
count: list:
let
len = length list;
take' = n:
if n == len || n == count
then []
else
[ (elemAt list n) ] ++ take' (n + 1);
in take' 0;
2016-02-28 23:27:06 +00:00
/* Remove the first (at most) N elements of a list.
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
Example:
drop 2 [ "a" "b" "c" "d" ]
=> [ "c" "d" ]
drop 2 [ ]
=> [ ]
*/
drop =
if builtins ? genList then
count: list: sublist count (length list) list
else
count: list:
let
len = length list;
drop' = n:
if n == -1 || n < count
then []
else
drop' (n - 1) ++ [ (elemAt list n) ];
in drop' (len - 1);
2016-02-28 23:27:06 +00:00
/* Return a list consisting of at most count elements of list,
starting at index start.
2016-02-28 23:27:06 +00:00
Example:
sublist 1 3 [ "a" "b" "c" "d" "e" ]
=> [ "b" "c" "d" ]
sublist 1 3 [ ]
=> [ ]
*/
sublist = start: count: list:
let len = length list; in
genList
(n: elemAt list (n + start))
(if start >= len then 0
else if start + count > len then len - start
else count);
2016-02-28 23:27:06 +00:00
/* Return the last element of a list.
2013-11-12 12:48:19 +00:00
2016-02-28 23:27:06 +00:00
Example:
last [ 1 2 3 ]
=> 3
*/
last = list:
assert list != []; elemAt list (length list - 1);
2016-02-28 23:27:06 +00:00
/* Return all elements but the last
2012-08-13 22:26:19 +00:00
2016-02-28 23:27:06 +00:00
Example:
init [ 1 2 3 ]
=> [ 1 2 ]
*/
2014-09-16 16:03:46 +00:00
init = list: assert list != []; take (length list - 1) list;
2016-02-28 23:27:06 +00:00
/* FIXME(zimbatm) Not used anywhere
*/
crossLists = f: foldl (fs: args: concatMap (f: map f args) fs) [f];
2016-02-28 23:27:06 +00:00
/* Remove duplicate elements from the list. O(n^2) complexity.
Example:
unique [ 3 2 3 4 ]
=> [ 3 2 4 ]
*/
unique = list:
if list == [] then
[]
else
let
x = head list;
xs = unique (drop 1 list);
in [x] ++ remove x xs;
2016-02-28 23:27:06 +00:00
/* Intersects list 'e' and another list. O(nm) complexity.
2016-02-28 23:27:06 +00:00
Example:
intersectLists [ 1 2 3 ] [ 6 3 2 ]
=> [ 3 2 ]
*/
intersectLists = e: filter (x: elem x e);
2016-02-28 23:27:06 +00:00
/* Subtracts list 'e' from another list. O(nm) complexity.
2016-02-28 23:27:06 +00:00
Example:
subtractLists [ 3 2 ] [ 1 2 3 4 5 3 ]
=> [ 1 4 5 ]
*/
subtractLists = e: filter (x: !(elem x e));
2016-02-28 23:27:06 +00:00
/*** deprecated stuff ***/
2016-02-28 23:27:06 +00:00
deepSeqList = throw "removed 2016-02-29 because unused and broken";
}