lib.lists: list manipulation functions

lib.lists.singleton

Type: singleton :: a -> [a]

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.

x

Function argument

singleton "foo"
=> [ "foo" ]

Located at lib/lists.nix:23 in <nixpkgs>.

lib.lists.forEach

Type: forEach :: [a] -> (a -> b) -> [b]

Apply the function to each element in the list. Same as map, but arguments flipped.

xs

Function argument

f

Function argument

forEach [ 1 2 ] (x:
  toString x
)
=> [ "1" "2" ]

Located at lib/lists.nix:36 in <nixpkgs>.

lib.lists.foldr

Type: foldr :: (a -> b -> b) -> b -> [a] -> b

“right fold” a binary function op between successive elements of list with nul as the starting value, i.e., foldr op nul [x_1 x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul)).

op

Function argument

nul

Function argument

list

Function argument

concat = foldr (a: b: a + b) "z"
concat [ "a" "b" "c" ]
=> "abcz"
# different types
strange = foldr (int: str: toString (int + 1) + str) "a"
strange [ 1 2 3 4 ]
=> "2345a"

Located at lib/lists.nix:53 in <nixpkgs>.

lib.lists.fold

fold is an alias of foldr for historic reasons

Located at lib/lists.nix:64 in <nixpkgs>.

lib.lists.foldl

Type: foldl :: (b -> a -> b) -> b -> [a] -> b

“left fold”, like foldr, but from the left: foldl op nul [x_1 x_2 ... x_n] == op (... (op (op nul x_1) x_2) ... x_n).

op

Function argument

nul

Function argument

list

Function argument

lconcat = foldl (a: b: a + b) "z"
lconcat [ "a" "b" "c" ]
=> "zabc"
# different types
lstrange = foldl (str: int: str + toString (int + 1)) "a"
lstrange [ 1 2 3 4 ]
=> "a2345"

Located at lib/lists.nix:81 in <nixpkgs>.

lib.lists.foldl'

Type: foldl' :: (b -> a -> b) -> b -> [a] -> b

Strict version of foldl.

The difference is that evaluation is forced upon access. Usually used with small whole results (in contrast with lazily-generated list or large lists where only a part is consumed.)

Located at lib/lists.nix:97 in <nixpkgs>.

lib.lists.imap0

Type: imap0 :: (int -> a -> b) -> [a] -> [b]

Map with index starting from 0

f

Function argument

list

Function argument

imap0 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-0" "b-1" ]

Located at lib/lists.nix:107 in <nixpkgs>.

lib.lists.imap1

Type: imap1 :: (int -> a -> b) -> [a] -> [b]

Map with index starting from 1

f

Function argument

list

Function argument

imap1 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-1" "b-2" ]

Located at lib/lists.nix:117 in <nixpkgs>.

lib.lists.concatMap

Type: concatMap :: (a -> [b]) -> [a] -> [b]

Map and concatenate the result.

concatMap (x: [x] ++ ["z"]) ["a" "b"]
=> [ "a" "z" "b" "z" ]

Located at lib/lists.nix:127 in <nixpkgs>.

lib.lists.flatten

Flatten the argument into a single list; that is, nested lists are spliced into the top-level lists.

x

Function argument

flatten [1 [2 [3] 4] 5]
=> [1 2 3 4 5]
flatten 1
=> [1]

Located at lib/lists.nix:138 in <nixpkgs>.

lib.lists.remove

Type: remove :: a -> [a] -> [a]

Remove elements equal to 'e' from a list. Useful for buildInputs.

e

Element to remove from the list

remove 3 [ 1 3 4 3 ]
=> [ 1 4 ]

Located at lib/lists.nix:151 in <nixpkgs>.

lib.lists.findSingle

Type: findSingle :: (a -> bool) -> a -> a -> [a] -> a

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.

pred

Predicate

default

Default value to return if element was not found.

multiple

Default value to return if more than one element was found

list

Input list

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"

Located at lib/lists.nix:169 in <nixpkgs>.

lib.lists.findFirstIndex

Type: findFirstIndex :: (a -> Bool) -> b -> [a] -> (Int | b)

Find the first index in the list matching the specified predicate or return default if no such element exists.

pred

Predicate

default

Default value to return

list

Input list

findFirstIndex (x: x > 3) null [ 0 6 4 ]
=> 1
findFirstIndex (x: x > 9) null [ 0 6 4 ]
=> null

Located at lib/lists.nix:194 in <nixpkgs>.

lib.lists.findFirst

Type: findFirst :: (a -> bool) -> a -> [a] -> a

Find the first element in the list matching the specified predicate or return default if no such element exists.

pred

Predicate

default

Default value to return

list

Input list

findFirst (x: x > 3) 7 [ 1 6 4 ]
=> 6
findFirst (x: x > 9) 7 [ 1 6 4 ]
=> 7

Located at lib/lists.nix:245 in <nixpkgs>.

lib.lists.any

Type: any :: (a -> bool) -> [a] -> bool

Return true if function pred returns true for at least one element of list.

any isString [ 1 "a" { } ]
=> true
any isString [ 1 { } ]
=> false

Located at lib/lists.nix:271 in <nixpkgs>.

lib.lists.all

Type: all :: (a -> bool) -> [a] -> bool

Return true if function pred returns true for all elements of list.

all (x: x < 3) [ 1 2 ]
=> true
all (x: x < 3) [ 1 2 3 ]
=> false

Located at lib/lists.nix:284 in <nixpkgs>.

lib.lists.count

Type: count :: (a -> bool) -> [a] -> int

Count how many elements of list match the supplied predicate function.

pred

Predicate

count (x: x == 3) [ 3 2 3 4 6 ]
=> 2

Located at lib/lists.nix:295 in <nixpkgs>.

lib.lists.optional

Type: optional :: bool -> a -> [a]

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

cond

Function argument

elem

Function argument

optional true "foo"
=> [ "foo" ]
optional false "foo"
=> [ ]

Located at lib/lists.nix:311 in <nixpkgs>.

lib.lists.optionals

Type: optionals :: bool -> [a] -> [a]

Return a list or an empty list, depending on a boolean value.

cond

Condition

elems

List to return if condition is true

optionals true [ 2 3 ]
=> [ 2 3 ]
optionals false [ 2 3 ]
=> [ ]

Located at lib/lists.nix:323 in <nixpkgs>.

lib.lists.toList

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.

x

Function argument

toList [ 1 2 ]
=> [ 1 2 ]
toList "hi"
=> [ "hi "]

Located at lib/lists.nix:340 in <nixpkgs>.

lib.lists.range

Type: range :: int -> int -> [int]

Return a list of integers from first up to and including last.

first

First integer in the range

last

Last integer in the range

range 2 4
=> [ 2 3 4 ]
range 3 2
=> [ ]

Located at lib/lists.nix:352 in <nixpkgs>.

lib.lists.replicate

Type: replicate :: int -> a -> [a]

Return a list with n copies of an element.

n

Function argument

elem

Function argument

replicate 3 "a"
=> [ "a" "a" "a" ]
replicate 2 true
=> [ true true ]

Located at lib/lists.nix:372 in <nixpkgs>.

lib.lists.partition

Type: (a -> bool) -> [a] -> { right :: [a]; wrong :: [a]; }

Splits the elements of a list in two lists, right and wrong, depending on the evaluation of a predicate.

partition (x: x > 2) [ 5 1 2 3 4 ]
=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }

Located at lib/lists.nix:383 in <nixpkgs>.

lib.lists.groupBy'

Splits the elements of a list into many lists, using the return value of a predicate. Predicate should return a string which becomes keys of attrset groupBy returns.

groupBy' allows to customise the combining function and initial value

op

Function argument

nul

Function argument

pred

Function argument

lst

Function argument

groupBy (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = [ 5 3 4 ]; false = [ 1 2 ]; }
groupBy (x: x.name) [ {name = "icewm"; script = "icewm &";}
                      {name = "xfce";  script = "xfce4-session &";}
                      {name = "icewm"; script = "icewmbg &";}
                      {name = "mate";  script = "gnome-session &";}
                    ]
=> { icewm = [ { name = "icewm"; script = "icewm &"; }
               { name = "icewm"; script = "icewmbg &"; } ];
     mate  = [ { name = "mate";  script = "gnome-session &"; } ];
     xfce  = [ { name = "xfce";  script = "xfce4-session &"; } ];
   }

groupBy' builtins.add 0 (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = 12; false = 3; }

Located at lib/lists.nix:412 in <nixpkgs>.

lib.lists.zipListsWith

Type: zipListsWith :: (a -> b -> c) -> [a] -> [b] -> [c]

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.

f

Function to zip elements of both lists

fst

First list

snd

Second list

zipListsWith (a: b: a + b) ["h" "l"] ["e" "o"]
=> ["he" "lo"]

Located at lib/lists.nix:432 in <nixpkgs>.

lib.lists.zipLists

Type: zipLists :: [a] -> [b] -> [{ fst :: a; snd :: b; }]

Merges two lists of the same size together. If the sizes aren't the same the merging stops at the shortest.

zipLists [ 1 2 ] [ "a" "b" ]
=> [ { fst = 1; snd = "a"; } { fst = 2; snd = "b"; } ]

Located at lib/lists.nix:451 in <nixpkgs>.

lib.lists.reverseList

Type: reverseList :: [a] -> [a]

Reverse the order of the elements of a list.

xs

Function argument

reverseList [ "b" "o" "j" ]
=> [ "j" "o" "b" ]

Located at lib/lists.nix:462 in <nixpkgs>.

lib.lists.listDfs

Depth-First Search (DFS) for lists list != [].

before a b == true means that b depends on a (there's an edge from b to a).

stopOnCycles

Function argument

before

Function argument

list

Function argument

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" ]
  == { minimal = "/";                  # minimal element
       visited = [ "/home/user" ];     # seen elements (in reverse order)
       rest    = [ "/home" "other" ];  # everything else
     }

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
  == { cycle   = "/";                  # cycle encountered at this element
       loops   = [ "/" ];              # and continues to these elements
       visited = [ "/" "/home/user" ]; # elements leading to the cycle (in reverse order)
       rest    = [ "/home" "other" ];  # everything else

Located at lib/lists.nix:484 in <nixpkgs>.

lib.lists.toposort

Sort a list based on a partial ordering using DFS. This implementation is O(N^2), if your ordering is linear, use sort instead.

before a b == true means that b should be after a in the result.

before

Function argument

list

Function argument

toposort hasPrefix [ "/home/user" "other" "/" "/home" ]
  == { result = [ "/" "/home" "/home/user" "other" ]; }

toposort hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
  == { cycle = [ "/home/user" "/" "/" ]; # path leading to a cycle
       loops = [ "/" ]; }                # loops back to these elements

toposort hasPrefix [ "other" "/home/user" "/home" "/" ]
  == { result = [ "other" "/" "/home" "/home/user" ]; }

toposort (a: b: a < b) [ 3 2 1 ] == { result = [ 1 2 3 ]; }

Located at lib/lists.nix:523 in <nixpkgs>.

lib.lists.sort

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.

sort (a: b: a < b) [ 5 3 7 ]
=> [ 3 5 7 ]

Located at lib/lists.nix:551 in <nixpkgs>.

lib.lists.compareLists

Compare two lists element-by-element.

cmp

Function argument

a

Function argument

b

Function argument

compareLists compare [] []
=> 0
compareLists compare [] [ "a" ]
=> -1
compareLists compare [ "a" ] []
=> 1
compareLists compare [ "a" "b" ] [ "a" "c" ]
=> -1

Located at lib/lists.nix:580 in <nixpkgs>.

lib.lists.naturalSort

Sort list using "Natural sorting". Numeric portions of strings are sorted in numeric order.

lst

Function argument

naturalSort ["disk11" "disk8" "disk100" "disk9"]
=> ["disk8" "disk9" "disk11" "disk100"]
naturalSort ["10.46.133.149" "10.5.16.62" "10.54.16.25"]
=> ["10.5.16.62" "10.46.133.149" "10.54.16.25"]
naturalSort ["v0.2" "v0.15" "v0.0.9"]
=> [ "v0.0.9" "v0.2" "v0.15" ]

Located at lib/lists.nix:603 in <nixpkgs>.

lib.lists.take

Type: take :: int -> [a] -> [a]

Return the first (at most) N elements of a list.

count

Number of elements to take

take 2 [ "a" "b" "c" "d" ]
=> [ "a" "b" ]
take 2 [ ]
=> [ ]

Located at lib/lists.nix:621 in <nixpkgs>.

lib.lists.drop

Type: drop :: int -> [a] -> [a]

Remove the first (at most) N elements of a list.

count

Number of elements to drop

list

Input list

drop 2 [ "a" "b" "c" "d" ]
=> [ "c" "d" ]
drop 2 [ ]
=> [ ]

Located at lib/lists.nix:635 in <nixpkgs>.

lib.lists.hasPrefix

Type: hasPrefix :: [a] -> [a] -> bool

Whether the first list is a prefix of the second list.

list1

Function argument

list2

Function argument

hasPrefix [ 1 2 ] [ 1 2 3 4 ]
=> true
hasPrefix [ 0 1 ] [ 1 2 3 4 ]
=> false

Located at lib/lists.nix:651 in <nixpkgs>.

lib.lists.removePrefix

Type: removePrefix :: [a] -> [a] -> [a]

Remove the first list as a prefix from the second list. Error if the first list isn't a prefix of the second list.

list1

Function argument

list2

Function argument

removePrefix [ 1 2 ] [ 1 2 3 4 ]
=> [ 3 4 ]
removePrefix [ 0 1 ] [ 1 2 3 4 ]
=> <error>

Located at lib/lists.nix:667 in <nixpkgs>.

lib.lists.sublist

Type: sublist :: int -> int -> [a] -> [a]

Return a list consisting of at most count elements of list, starting at index start.

start

Index at which to start the sublist

count

Number of elements to take

list

Input list

sublist 1 3 [ "a" "b" "c" "d" "e" ]
=> [ "b" "c" "d" ]
sublist 1 3 [ ]
=> [ ]

Located at lib/lists.nix:686 in <nixpkgs>.

lib.lists.commonPrefix

Type: commonPrefix :: [a] -> [a] -> [a]

The common prefix of two lists.

list1

Function argument

list2

Function argument

commonPrefix [ 1 2 3 4 5 6 ] [ 1 2 4 8 ]
=> [ 1 2 ]
commonPrefix [ 1 2 3 ] [ 1 2 3 4 5 ]
=> [ 1 2 3 ]
commonPrefix [ 1 2 3 ] [ 4 5 6 ]
=> [ ]

Located at lib/lists.nix:712 in <nixpkgs>.

lib.lists.last

Type: last :: [a] -> a

Return the last element of a list.

This function throws an error if the list is empty.

list

Function argument

last [ 1 2 3 ]
=> 3

Located at lib/lists.nix:736 in <nixpkgs>.

lib.lists.init

Type: init :: [a] -> [a]

Return all elements but the last.

This function throws an error if the list is empty.

list

Function argument

init [ 1 2 3 ]
=> [ 1 2 ]

Located at lib/lists.nix:750 in <nixpkgs>.

lib.lists.crossLists

Return the image of the cross product of some lists by a function.

crossLists (x:y: "${toString x}${toString y}") [[1 2] [3 4]]
=> [ "13" "14" "23" "24" ]

Located at lib/lists.nix:761 in <nixpkgs>.

lib.lists.unique

Type: unique :: [a] -> [a]

Remove duplicate elements from the list. O(n^2) complexity.

unique [ 3 2 3 4 ]
=> [ 3 2 4 ]

Located at lib/lists.nix:774 in <nixpkgs>.

lib.lists.intersectLists

Intersects list 'e' and another list. O(nm) complexity.

e

Function argument

intersectLists [ 1 2 3 ] [ 6 3 2 ]
=> [ 3 2 ]

Located at lib/lists.nix:782 in <nixpkgs>.

lib.lists.subtractLists

Subtracts list 'e' from another list. O(nm) complexity.

e

Function argument

subtractLists [ 3 2 ] [ 1 2 3 4 5 3 ]
=> [ 1 4 5 ]

Located at lib/lists.nix:790 in <nixpkgs>.

lib.lists.mutuallyExclusive

Test if two lists have no common element. It should be slightly more efficient than (intersectLists a b == [])

a

Function argument

b

Function argument

Located at lib/lists.nix:795 in <nixpkgs>.