![\"List](\"assets/listopard.png\")
\n\n\nA fast immutable list with a functional API.\n
\n\n\n ![\"Gitter\"](\"https://img.shields.io/gitter/room/funkia/General.svg\")
\n ![\"Build](\"https://travis-ci.org/funkia/list.svg?branch=master\")
\n ![\"codecov\"](\"https://codecov.io/gh/funkia/list/branch/master/graph/badge.svg\"){kind=icon}
\n
![\"Fantasy](\"https://raw.github.com/fantasyland/fantasy-land/master/logo.png\"){kind=logo}
\n![](\"https://raw.githubusercontent.com/rpominov/static-land/master/logo/logo.png\"){kind=logo}
\n\nList currently implements the following Fantasy Land and Static Land\nspecifications: Setoid, semigroup, monoid, foldable, functor, apply,\napplicative, chain, monad.\n\nThe following specifications have not been implemented yet:\nTraversable, Ord.\n\nSince methods hinder tree-shaking the Fantasy Land methods are not\nincluded by default. In order to get them you must import it likes\nthis:\n\n```js\nimport \"list/fantasy-land\";\n```\n\n## API documentation\n\nThe API is organized into three parts.\n\n1. [Creating lists](#creating-lists) — Functions that _create_ lists.\n2. [Updating lists](#updating-lists) — Functions that _transform_ lists.\n That is, functions that take one or more lists as arguments and\n returns a new list.\n3. [Folds](#folds) — Functions that _extracts_ values based on lists.\n They take one or more lists as arguments and returns something that\n is not a list.\n\n### Creating lists\n\n### `list`\n\nCreates a list based on the arguments given.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = list(1, 2, 3, 4); // creates a list of four elements\nconst l2 = list(\"foo\"); // creates a singleton\n```\n\n### `empty`\n\nReturns an empty list.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nconst emptyList = empty(); //=> list()\n```\n\n### `of`\n\nTakes a single arguments and returns a singleton list that contains it.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nof(\"foo\"); //=> list(\"foo\")\n```\n\n### `pair`\n\nTakes two arguments and returns a list that contains them.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\npair(\"foo\", \"bar\"); //=> list(\"foo\", \"bar\")\n```\n\n### `from`\n\nConverts an array, an array-like or an itearble into a list.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfrom([0, 1, 2, 3, 4]); //=> list(0, 1, 2, 3, 4)\n```\n\n### `range`\n\nReturns a list of numbers between an inclusive lower bound and an\nexclusive upper bound.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nrange(3, 8); //=> list(3, 4, 5, 6, 7)\n```\n\n### `repeat`\n\nReturns a list of a given length that contains the specified value in\nall positions.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nrepeat(1, 7); //=> list(1, 1, 1, 1, 1, 1, 1)\nrepeat(\"foo\", 3); //=> list(\"foo\", \"foo\", \"foo\")\n```\n\n### `times`\n\nReturns a list of given length that contains the value of the given function called with current index.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst twoFirsOdds = times(i => i * 2 + 1, 2);\nconst dots = times(() => {\n const x = Math.random() * width;\n const y = Math.random() * height;\n return { x, y };\n}, 50);\n```\n\n### Updating lists\n\n### `concat`\n\nConcatenates two lists.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nconcat(list(0, 1, 2), list(3, 4)); //=> list(0, 1, 2, 3, 4)\n```\n\n### `flatten`\n\nFlattens a list of lists into a list. Note that this function does\n_not_ flatten recursively. It removes one level of nesting only.\n\n**Complexity**: `O(n * log(m))` where `n` is the length of the outer\nlist and `m` the length of the inner lists.\n\n**Example**\n\n```js\nconst nested = list(list(0, 1, 2, 3), list(4), empty(), list(5, 6));\nflatten(nested); //=> list(0, 1, 2, 3, 4, 5, 6)\n```\n\n### `prepend`\n\nPrepends an element to the front of a list and returns the new list.\n\n**Complexity**: `O(log(n))`, practically constant\n\n**Example**\n\n```js\nconst newList = prepend(0, list(1, 2, 3)); //=> list(0, 1, 2, 3)\n```\n\n### `append`\n\nAppends an element to the end of a list and returns the new list.\n\n**Complexity**: `O(log(n))`, practically constant\n\n**Example**\n\n```js\nconst newList = append(3, list(0, 1, 2)); //=> list(0, 1, 2, 3)\n```\n\n### `intersperse`\n\nInserts a separator between each element in a list.\n\n**Example**\n\n```js\nintersperse(\"n\", list(\"ba\", \"a\", \"a\")); //=> list(\"ba\", \"n\", \"a\", \"n\", \"a\")\n```\n\n### `map`\n\nApplies a function to each element in the given list and returns a new\nlist of the values that the function return.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nmap(n => n * n, list(0, 1, 2, 3, 4)); //=> list(0, 1, 4, 9, 16)\n```\n\n### `pluck`\n\nExtracts the specified property from each object in the list.\n\n**Example**\n\n```js\nconst l = list(\n { foo: 0, bar: \"a\" },\n { foo: 1, bar: \"b\" },\n { foo: 2, bar: \"c\" }\n);\npluck(\"foo\", l); //=> list(0, 1, 2)\n```\n\n### `update`\n\nReturns a list that has the entry specified by the index replaced with\nthe given value.\n\nIf the index is out of bounds the given list is\nreturned unchanged.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nupdate(2, \"X\", list(\"a\", \"b\", \"c\", \"d\", \"e\")); //=> list(\"a\", \"b\", \"X\", \"d\", \"e\")\n```\n\n### `adjust`\n\nReturns a list that has the entry specified by the index replaced with\nthe value returned by applying the function to the value.\n\nIf the index is out of bounds the given list is\nreturned unchanged.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nadjust(2, inc, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 3, 3, 4, 5)\n```\n\n### `slice`\n\nReturns a slice of a list. Elements are removed from the beginning and\nend. Both the indices can be negative in which case they will count\nfrom the right end of the list.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4, 5);\nslice(1, 4, l); //=> list(1, 2, 3)\nslice(2, -2, l); //=> list(2, 3)\n```\n\n### `take`\n\nTakes the first `n` elements from a list and returns them in a new list.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ntake(3, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 2)\n```\n\n### `takeWhile`\n\nTakes the first elements in the list for which the predicate returns\n`true`.\n\n**Complexity**: `O(k + log(n))` where `k` is the number of elements\nsatisfying the predicate.\n\n**Example**\n\n```js\ntakeWhile(n => n < 4, list(0, 1, 2, 3, 4, 5, 6)); //=> list(0, 1, 2, 3)\ntakeWhile(_ => false, list(0, 1, 2, 3, 4, 5)); //=> list()\n```\n\n### `takeLast`\n\nTakes the last `n` elements from a list and returns them in a new\nlist.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ntakeLast(3, list(0, 1, 2, 3, 4, 5)); //=> list(3, 4, 5)\n```\n\n### `takeLastWhile`\n\nTakes the last elements in the list for which the predicate returns\n`true`.\n\n**Complexity**: `O(k + log(n))` where `k` is the number of elements\nsatisfying the predicate.\n\n**Example**\n\n```js\ntakeLastWhile(n => n > 2, list(0, 1, 2, 3, 4, 5)); //=> list(3, 4, 5)\ntakeLastWhile(_ => false, list(0, 1, 2, 3, 4, 5)); //=> list()\n```\n\n### `splitAt`\n\nSplits a list at the given index and return the two sides in a pair.\nThe left side will contain all elements before but not including the\nelement at the given index. The right side contains the element at the\nindex and all elements after it.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4, 5, 6, 7, 8);\nsplitAt(4, l); //=> [list(0, 1, 2, 3), list(4, 5, 6, 7, 8)]\n```\n\n### `splitWhen`\n\nSplits a list at the first element in the list for which the given\npredicate returns `true`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4, 5, 6, 7);\nsplitWhen((n) => n > 3, l); //=> [list(0, 1, 2, 3), list(4, 5, 6, 7)]\n```\n\n### `remove`\n\nTakes an index, a number of elements to remove and a list. Returns a\nnew list with the given amount of elements removed from the specified\nindex.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4, 5, 6, 7, 8);\nremove(4, 3, l); //=> list(0, 1, 2, 3, 7, 8)\nremove(2, 5, l); //=> list(0, 1, 7, 8)\n```\n\n### `drop`\n\nReturns a new list without the first `n` elements.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ndrop(2, list(0, 1, 2, 3, 4, 5)); //=> list(2, 3, 4, 5)\n```\n\n### `dropWhile`\n\nRemoves the first elements in the list for which the predicate returns\n`true`.\n\n**Complexity**: `O(k + log(n))` where `k` is the number of elements\nsatisfying the predicate.\n\n**Example**\n\n```js\ndropWhile(n => n < 4, list(0, 1, 2, 3, 4, 5, 6)); //=> list(4, 5, 6)\n```\n\n### `dropLast`\n\nReturns a new list without the last `n` elements.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ndropLast(2, list(0, 1, 2, 3, 4, 5)); //=> list(0, 1, 2, 3)\n```\n\n### `dropRepeats`\n\nReturns a new list without repeated elements.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\ndropRepeats(L.list(0, 0, 1, 1, 1, 2, 3, 3, 4, 4)); //=> list(0, 1, 2, 3, 4)\n```\n\n### `dropRepeatsWith`\n\nReturns a new list without repeated elements by using the given\nfunction to determine when elements are equal.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\ndropRepeatsWith(\n (n, m) => Math.floor(n) === Math.floor(m),\n list(0, 0.4, 1.2, 1.1, 1.8, 2.2, 3.8, 3.4, 4.7, 4.2)\n); //=> list(0, 1, 2, 3, 4)\n```\n\n### `tail`\n\nReturns a new list with the first element removed. If the list is\nempty the empty list is returne.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\ntail(list(0, 1, 2, 3)); //=> list(1, 2, 3)\ntail(empty()); //=> list()\n```\n\n### `pop`\n\nReturns a new list with the last element removed. If the list is empty\nthe empty list is returned.\n\n**Aliases**: `init`\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\npop(list(0, 1, 2, 3)); //=> list(0, 1, 2)\n```\n\n### `filter`\n\nReturns a new list that only contains the elements of the original\nlist for which the predicate returns `true`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfilter(isEven, list(0, 1, 2, 3, 4, 5, 6)); //=> list(0, 2, 4, 6)\n```\n\n### `reject`\n\nReturns a new list that only contains the elements of the original\nlist for which the predicate returns `false`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nreject(isEven, list(0, 1, 2, 3, 4, 5, 6)); //=> list(1, 3, 5)\n```\n\n### `reverse`\n\nReverses a list.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nreverse(list(0, 1, 2, 3, 4, 5)); //=> list(5, 4, 3, 2, 1, 0)\n```\n\n### `ap`\n\nApplies a list of functions to a list of values.\n\n**Example**\n\n```js\nap(list((n: number) => n + 2, n => 2 * n, n => n * n), list(1, 2, 3)); //=> list(3, 4, 5, 2, 4, 6, 1, 4, 9)\n```\n\n### `chain`\n\nMaps a function over a list and concatenates all the resulting lists\ntogether.\n\nAlso known as `flatMap`.\n\n**Example**\n\n```js\nchain(n => list(n, 2 * n, n * n), list(1, 2, 3)); //=> list(1, 2, 1, 2, 4, 4, 3, 6, 9)\n```\n\n### `partition`\n\nSplits the list into two lists. One list that contains all the values\nfor which the predicate returns `true` and one containing the values for\nwhich it returns `false`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\npartition(isEven, list(0, 1, 2, 3, 4, 5)); //=> list(list(0, 2, 4), list(1, 3, 5))\n```\n\n### `insert`\n\nInserts the given element at the given index in the list.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ninsert(2, \"c\", list(\"a\", \"b\", \"d\", \"e\")); //=> list(\"a\", \"b\", \"c\", \"d\", \"e\")\n```\n\n### `insertAll`\n\nInserts the given list of elements at the given index in the list.\n\n**Complexity**: `O(log(n))`\n\n**Example**\n\n```js\ninsertAll(2, list(\"c\", \"d\"), list(\"a\", \"b\", \"e\", \"f\")); //=> list(\"a\", \"b\", \"c\", \"d\", \"e\", \"f\")\n```\n\n### `zipWith`\n\nThis is like mapping over two lists at the same time. The two lists are\niterated over in parallel and each pair of elements is passed to the function.\nThe returned values are assembled into a new list.\n\nThe shortest list determine the size of the result.\n\n**Complexity**: `O(log(n))` where `n` is the length of the smallest list.\n\n**Example**\n\n```js\nconst names = list(\"Turing\", \"Curry\");\nconst years = list(1912, 1900);\nzipWith((name, year) => ({ name, year }), names, years);\n//=> list({ name: \"Turing\", year: 1912 }, { name: \"Curry\", year: 1900 });\n```\n\n### `zip`\n\nIterate over two lists in parallel and collect the pairs.\n\n**Complexity**: `O(log(n))` where `n` is the length of the smallest list.\n\n**Example**\n\n```js\nconst names = list(\"a\", \"b\", \"c\", \"d\", \"e\");\nconst years = list(0, 1, 2, 3, 4, 5, 6);\n//=> list([\"a\", 0], [\"b\", 1], [\"c\", 2], [\"d\", 3], [\"e\", 4]);\n```\n\n### `sort`\n\nSorts the given list. The list should contain values that can be compared using\nthe `<` operator or values that implement the Fantasy Land\n[Ord](https://github.com/fantasyland/fantasy-land#ord) specification.\n\nPerforms a stable sort.\n\n**Complexity**: `O(n * log(n))`\n\n**Example**\n\n```js\nsort(list(5, 3, 1, 8, 2)); //=> list(1, 2, 3, 5, 8)\nsort(list(\"e\", \"a\", \"c\", \"b\", \"d\"); //=> list(\"a\", \"b\", \"c\", \"d\", \"e\")\n```\n\n### `sortBy`\n\nSort the given list by passing each value through the function and comparing\nthe resulting value. The function should either return values comparable using\n`<` or values that implement the Fantasy Land\n[Ord](https://github.com/fantasyland/fantasy-land#ord) specification.\n\nPerforms a stable sort.\n\n**Complexity**: `O(n * log(n))`\n\n**Example**\n\n```js\nsortBy(\n o => o.n,\n list({ n: 4, m: \"foo\" }, { n: 3, m: \"bar\" }, { n: 1, m: \"baz\" })\n);\n//=> list({ n: 1, m: \"baz\" }, { n: 3, m: \"bar\" }, { n: 4, m: \"foo\" })\n\nsortBy(s => s.length, list(\"foo\", \"bar\", \"ba\", \"aa\", \"list\", \"z\"));\n//=> list(\"z\", \"ba\", \"aa\", \"foo\", \"bar\", \"list\")\n```\n\n### `sortWith`\n\nSort the given list by comparing values using the given function. The function\nreceieves two values and should return `-1` if the first value is stricty\nlarger than the second, `0` is they are equal and `1` if the first values is\nstrictly smaller than the second.\n\nNote that the comparison function is equivalent to the one required by\n[`Array.prototype.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).\n\nPerforms a stable sort.\n\n**Complexity**: `O(n * log(n))`\n\n**Example**\n\n```js\nsortWith((a, b) => {\n if (a === b) {\n return 0;\n } else if (a < b) {\n return -1;\n } else {\n return 1;\n }\n}, list(5, 3, 1, 8, 2)); //=> list(1, 2, 3, 5, 8)\n```\n\n### `group`\n\nReturns a list of lists where each sublist's elements\nare all equal.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\ngroup(list(0, 0, 1, 2, 2, 2, 3, 3)); //=> list(list(0, 0), list(1), list(2, 2, 2), list(3, 3))\n```\n\n### `groupWith`\n\nReturns a list of lists where each sublist's elements are pairwise\nequal based on the given comparison function.\n\nNote that only adjacent elements are compared for equality. If all\nequal elements should be grouped together the list should be sorted\nbefore grouping.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst floorEqual = (a, b) => Math.round(a) === Math.round(b);\ngroupWith(floorEqual, list(1.1, 1.3, 1.8, 2, 2.2, 3.3, 3.4));\n//=> list(list(1.1, 1.3), list(1.8, 2, 2.2), list(3.3, 3.4))\n\nconst sameLength = (a, b) => a.length === b.length;\ngroupWith(sameLength, list(\"foo\", \"bar\", \"ab\", \"bc\", \"baz\"));\n//=> list(list(\"foo\", \"bar\"), list(\"ab\", \"bc\"), list(\"baz))\n```\n\n### Folds\n\n### `isList`\n\nReturns `true` if the given argument is a list.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nisList([0, 1, 2]); //=> false\nisList(\"string\"); //=> false\nisList({ foo: 0, bar: 1 }); //=> false\nisList(list(0, 1, 2)); //=> true\n```\n\n### `equals`\n\nReturns true if the two lists are equivalent.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nequals(list(0, 1, 2, 3), list(0, 1, 2, 3)); //=> true\nequals(list(\"a\", \"b\", \"c\"), list(\"a\", \"z\", \"c\")); //=> false\n```\n\n### `equalsWith`\n\nReturns `true` if the two lists are equivalent when comparing each\npair of elements with the given comparison function.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nequalsWith(\n (n, m) => n.length === m.length,\n list(\"foo\", \"hello\", \"one\"),\n list(\"bar\", \"world\", \"two\")\n); //=> true\n```\n\n### `toArray`\n\nConverts a list into an array.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\ntoArray(list(0, 1, 2, 3, 4)); //=> [0, 1, 2, 3, 4]\n```\n\n### `backwards`\n\nReturns an iterable that iterates backwards over the given list.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4)\nfor (const n of backwards(l)) {\n if (l < 2) {\n break;\n }\n console.log(l);\n}\n// => logs 4, 3, and then 2\n```\n\n### `nth`\n\nGets the `n`th element of the list. If `n` is out of bounds\n`undefined` is returned.\n\n**Complexity**: `O(log(n))`, practically constant\n\n**Example**\n\n```js\nconst l = list(0, 1, 2, 3, 4);\nnth(2, l); //=> 2\n```\n\n### `length`\n\nReturns the length of a list. I.e. the number of elements that it\ncontains.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nlength(list(0, 1, 2, 3)); //=> 4\n```\n\n### `first`\n\nReturns the first element of the list. If the list is empty the\nfunction returns `undefined`.\n\n**Aliases**: `head`\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nfirst(list(0, 1, 2, 3)); //=> 0\nfirst(list()); //=> undefined\n```\n\n### `last`\n\nReturns the last element of the list. If the list is empty the\nfunction returns `undefined`.\n\n**Complexity**: `O(1)`\n\n**Example**\n\n```js\nlast(list(0, 1, 2, 3)); //=> 3\nlast(list()); //=> undefined\n```\n\n### `foldl`\n\nFolds a function over a list. Left-associative.\n\n**Aliases**: `reduce`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfoldl((n, m) => n - m, 1, list(2, 3, 4, 5));\n1 - 2 - 3 - 4 - 5; //=> -13\n```\n\n### `foldr`\n\nFolds a function over a list. Right-associative.\n\n**Aliases**: `reduceRight`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfoldr((n, m) => n - m, 5, list(1, 2, 3, 4));\n1 - (2 - (3 - (4 - 5))); //=> 3\n```\n\n### `foldlWhile`\n\nSimilar to `foldl`. But, for each element it calls the predicate function\n_before_ the folding function and stops folding if it returns `false`.\n\n**Aliases**: `reduceWhile`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst isOdd = (_acc:, x) => x % 2 === 1;\n\nconst xs = L.list(1, 3, 5, 60, 777, 800);\nfoldlWhile(isOdd, (n, m) => n + m, 0, xs) //=> 9\n\nconst ys = L.list(2, 4, 6);\nfoldlWhile(isOdd, (n, m) => n + m, 111, ys) //=> 111\n```\n\n### `scan`\n\nFolds a function over a list from left to right while collecting all the\nintermediate steps in a resulting list.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = list(1, 3, 5, 4, 2);\nL.scan((n, m) => n + m, 0, l); //=> list(0, 1, 4, 9, 13, 15));\nL.scan((s, m) => s + m.toString(), \"\", l); //=> list(\"\", \"1\", \"13\", \"135\", \"1354\", \"13542\")\n```\n\n### `traverse`\n\nMap each element of list to an applicative, evaluate these\napplicatives from left to right, and collect the results.\n\nThis works with Fantasy Land\n[applicatives](https://github.com/fantasyland/fantasy-land#applicative).\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst safeDiv = n => d => d === 0 ? nothing : just(n / d)\n\nL.traverse(Maybe, safeDiv(10), list(2, 4, 5)); //=> just(list(5, 2.5, 2))\nL.traverse(Maybe, safeDiv(10), list(2, 0, 5)); //=> nothing\n```\n\n### `sequence`\n\nEvaluate each applicative in the list from left to right, and\ncollect the results.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nL.sequence(Maybe, list(just(1), just(2), just(3))); //=> just(list(1, 2, 3))\nL.sequence(Maybe, list(just(1), just(2), nothing())); //=> nothing\n```\n\n### `forEach`\n\nInvokes a given callback for each element in the list from left to\nright. Returns `undefined`.\n\nThis function is very similar to `map`. It should be used instead of\n`map` when the mapping function has side-effects. Whereas `map`\nconstructs a new list `forEach` merely returns `undefined`. This makes\n`forEach` faster when the new list is unneeded.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = list(0, 1, 2);\nforEach(element => console.log(element));\n//=> 0\n//=> 1\n//=> 2\n```\n\n### `every`\n\nReturns `true` if and only if the predicate function returns `true`\nfor all elements in the given list.\n\n**Aliases**: `all`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst isEven = n => n % 2 === 0;\nevery(isEven, empty()); //=> true\nevery(isEven, list(2, 4, 6, 8)); //=> true\nevery(isEven, list(2, 3, 4, 6, 7, 8)); //=> false\nevery(isEven, list(1, 3, 5, 7)); //=> false\n```\n\n### `some`\n\nReturns `true` if and only if there exists an element in the list for\nwhich the predicate returns `true`.\n\n**Aliases**: `any`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst isEven = n => n % 2 === 0;\nsome(isEven, empty()); //=> false\nsome(isEven, list(2, 4, 6, 8)); //=> true\nsome(isEven, list(2, 3, 4, 6, 7, 8)); //=> true\nsome(isEven, list(1, 3, 5, 7)); //=> false\n```\n\n### `indexOf`\n\nReturns the index of the _first_ element in the list that is equal to\nthe given element. If no such element is found `-1` is returned.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = list(12, 4, 2, 89, 6, 18, 7);\nindexOf(12, l); //=> 0\nindexOf(89, l); //=> 3\nindexOf(10, l); //=> -1\n```\n\n### `lastIndexOf`\n\nReturns the index of the _last_ element in the list that is equal to\nthe given element. If no such element is found `-1` is returned.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst l = L.list(12, 4, 2, 18, 89, 2, 18, 7);\nL.lastIndexOf(18, l); //=> 6\nL.lastIndexOf(2, l); //=> 5\nL.lastIndexOf(12, l); //=> 0\n```\n\n### `find`\n\nReturns the _first_ element for which the predicate returns `true`. If\nno such element is found the function returns `undefined`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfind(isEven, list(1, 3, 5, 6, 7, 9, 10)); //=> 6\nfind(isEven, list(1, 3, 5, 7, 9)); //=> undefined\n```\n\n### `findLast`\n\nReturns the _last_ element for which the predicate returns `true`. If\nno such element is found the function returns `undefined`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfindLast(isEven, list(1, 3, 5, 6, 7, 8, 9)); //=> 8\nfindLast(isEven, list(1, 3, 5, 7, 9)); //=> undefined\n```\n\n### `findIndex`\n\nReturns the index of the first element for which the predicate returns\n`true`. If no such element is found the function returns `-1`.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nfindIndex(isEven, list(1, 3, 5, 6, 7, 9, 10)); //=> 3\nfindIndex(isEven, list(1, 3, 5, 7, 9)); //=> -1\n```\n\n### `none`\n\nReturns `true` if and only if the predicate function returns `false`\nfor all elements in the given list.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nconst isEven = n => n % 2 === 0;\nnone(isEven, empty()); //=> true\nnone(isEven, list(2, 4, 6, 8)); //=> false\nnone(isEven, list(2, 3, 4, 6, 7, 8)); //=> false\nnone(isEven, list(1, 3, 5, 7)); //=> true\n```\n\n### `includes`\n\nReturns `true` if the list contains the specified element. Otherwise\nit returns `false`.\n\n**Aliases**: `contains`\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\nincludes(3, list(0, 1, 2, 3, 4, 5)); //=> true\nincludes(3, list(0, 1, 2, 4, 5)); //=> false\n```\n\n### `join`\n\nConcats the strings in a list separated by a specified separator.\n\n**Complexity**: `O(n)`\n\n**Example**\n\n```js\njoin(\", \", list(\"one\", \"two\", \"three\")); //=> \"one, two, three\"\n```\n\n## Benchmarks\n\nThe benchmarks are located in the [`bench` directory](/test/bench)."
}