feat: take, drop, takeWhile, dropWhile, and more (#14)

* feat: `average`

* test: NaN checks for reducers

* feat: `drop`

* feat: `dropUntil`

* feat: `takeWhile`

* feat: `dropWhile`

Author: scarf005

fp.ts

@@ -18,13 +18,18 @@ export const includes = curryIterFunction(reducers.includes);
 export const find = curryIterFunction(reducers.find);
 export const findIndex = curryIterFunction(reducers.findIndex);
 export const sum = reducers.sum;
+export const average = reducers.average;
 export const product = reducers.product;
 export const norm = reducers.norm;
 
 // Transformers
 export const map = curryIterFunction(transformers.map);
 export const flatMap = curryIterFunction(transformers.flatMap);
 export const take = curryIterFunction(transformers.take);
+export const takeWhile = curryIterFunction(transformers.takeWhile);
+export const drop = curryIterFunction(transformers.drop);
+export const dropUntil = curryIterFunction(transformers.dropUntil);
+export const dropWhile = curryIterFunction(transformers.dropWhile);
 export const until = curryIterFunction(transformers.until);
 export const filter = curryIterFunction(transformers.filter);
 export const indexedPairs = transformers.indexedPairs;

lib/reducers.ts

@@ -301,6 +301,30 @@ export function sum(it: Iterable<number>): number {
   return reduce(it, (acc, n) => acc + n, 0, (acc) => isNaN(acc));
 }
 
+/**
+ * Finds the average of all items in `it`.
+ *
+ * :warning: When ran on an endless iterable, this never returns.
+ * @param it - The iterable to calculate the average of.
+ * @returns The average of all items in `it`.
+ * @example
+ * ```ts
+ * import * as iter from "https://deno.land/x/iter";
+ *
+ * const myRange = iter.create.range(1, 100);
+ * console.log(iter.average(myRange)); // -> 50.5
+ */
+export function average(it: Iterable<number>): number {
+  let count = 0;
+  let accumulator = 0;
+  for (const item of it) {
+    accumulator += item;
+    if (isNaN(accumulator)) break;
+    count++;
+  }
+  return accumulator / count;
+}
+
 /**
  * Finds the product of all items in `it`.
  *

lib/reducers_test.ts

@@ -108,13 +108,27 @@ Deno.test("includes", () => {
 
 Deno.test("sum", () => {
   assertEquals(reducers.sum([0, 3, 2, 4, -2, 5, 1, -3]), 10);
+
+  const withNaN = concat(range(10), [NaN], increments());
+  assertEquals(reducers.sum(withNaN), NaN);
+});
+
+Deno.test("avergage", () => {
+  assertEquals(reducers.average([0, 3, 2, 4, -2, 5, 1, -3]), 1.25);
+  assertEquals(reducers.average(range(1, 100)), 50.5);
+
+  const withNaN = concat(range(10), [NaN], increments());
+  assertEquals(reducers.average(withNaN), NaN);
 });
 
 Deno.test("product", () => {
   assertEquals(reducers.product(range(1, 9)), 362880);
 
   const determinableEndless = concat(range(100), [0], increments());
   assertEquals(reducers.product(determinableEndless), 0);
+
+  const withNaN = concat(range(1, 9), [NaN], increments());
+  assertEquals(reducers.product(withNaN), NaN);
 });
 
 Deno.test("norm", () => {

lib/transformers.ts

@@ -155,6 +155,39 @@ export function take<T>(it: Iterable<T>, n: number): IterableCircular<T> {
   };
 }
 
+/**
+ * Returns a new iterable containing the items of `it` except the first `n` items.
+ * @param it - The iterable being taken from.
+ * @param n - The number of items to drop.
+ * @typeParam T - The type of items in both `it` and the returned iterable.
+ * @returns A new iterable of `it` which skips the first `n` items.
+ * @example
+ * ```ts
+ * import * as iter from "https://deno.land/x/iter/mod.ts";
+ *
+ * const numbers = iter.create.range(1, 10);
+ * const from7 = iter.drop(numbers, 6);
+ *
+ * for (const num of from7) {
+ *   console.log(num);
+ * }
+ *
+ * // -> 7
+ * // -> 8
+ * // -> 9
+ * // -> 10
+ * ```
+ */
+export function drop<T>(it: Iterable<T>, n: number): IterableCircular<T> {
+  return {
+    *[Symbol.iterator]() {
+      const iterator = it[Symbol.iterator]();
+      for (let i = 0; i < n; i++) iterator.next();
+      yield* { [Symbol.iterator]: () => iterator };
+    },
+  };
+}
+
 /**
  * Returns a new iterable which yields until `f` returns true.
  *
@@ -208,6 +241,126 @@ export function until<T>(
   };
 }
 
+/**
+ * Returns a new iterable which skips items from `it` until `f` returns true.
+ * true.
+ * @param it - The iterable being skipped.
+ * @param {IterablePredicateCallback} f - A function that accepts up to three
+ * arguments. The `dropUntil` function calls `f` one time for each item
+ * in the iterable until `f` returns true.
+ * @param includeFirst - Whether the item for which `f` returns true should be
+ * included.
+ * @typeParam T - The type of items in both `it` and the returned iterable.
+ * @returns A new iterable of `it` which begins at the first element where `f` returns true
+ * @example
+ * ```ts
+ * import * as iter from "https://deno.land/x/iter/mod.ts";
+ *
+ * const numbers = iter.create.range(1, 10);
+ * const dropped = iter.dropUntil(numbers, (n) => n >= 5);
+ *
+ * for (const num of dropped) {
+ *   console.log(num);
+ * }
+ *
+ * // -> 5
+ * // -> 6
+ * // -> 7
+ * // -> 8
+ * // -> 9
+ * // -> 10
+ * ```
+ */
+export function dropUntil<T>(
+  it: Iterable<T>,
+  f: IterablePredicateCallback<T>,
+  includeFirst = true,
+): IterableCircular<T> {
+  return {
+    *[Symbol.iterator]() {
+      let index = 0;
+      let dropping = true;
+      for (const item of it) {
+        if (dropping) {
+          dropping = !f(item, index++, it);
+          if (dropping || !includeFirst) continue;
+        }
+        yield item;
+      }
+    },
+  };
+}
+
+/**
+ * Returns a new iterable which yields while `f` returns true.
+ *
+ * @param it - The iterable being cut.
+ * @param {IterablePredicateCallback} f - A function that accepts up to three
+ * arguments. The `takeWhile` function calls `f` one time for each item in the iterable.
+ * included.
+ * @typeParam T - The type of items in both `it` and the returned iterable.
+ * @returns A new iterables of `it` which terminates
+ * @example
+ * ```ts
+ * import * as iter from "https://deno.land/x/iter/mod.ts";
+ *
+ * const naturals = iter.create.increments(1);
+ * const numbers = iter.takeWhile(naturals, (n) => n <= 5);
+ *
+ * for (const num of numbers) {
+ *   console.log(num);
+ * }
+ *
+ * // -> 1
+ * // -> 2
+ * // -> 3
+ * // -> 4
+ * // -> 5
+ * ```
+ */
+export function takeWhile<T>(
+  it: Iterable<T>,
+  f: IterablePredicateCallback<T>,
+): IterableCircular<T> {
+  return until(it, (...args) => !f(...args), false);
+}
+
+/**
+ * Returns a new iterable which skips items from `it` while `f` returns true.
+ * true.
+ * @param it - The iterable being skipped.
+ * @param {IterablePredicateCallback} f - A function that accepts up to three
+ * arguments. The `dropWhile` function calls `f` one time for each item
+ * in the iterable.
+ *
+ * @typeParam T - The type of items in both `it` and the returned iterable.
+ * @returns A new iterable of `it` which begins at the first element where `f` returns false
+ * @example
+ * ```ts
+ * import * as iter from "https://deno.land/x/iter/mod.ts";
+ *
+ * const numbers = iter.create.range(1, 10);
+ * const dropped = iter.dropWhile(numbers, (n) => n < 5);
+ *
+ * for (const num of dropped) {
+ *   console.log(num);
+ * }
+ *
+ * // -> 5
+ * // -> 6
+ * // -> 7
+ * // -> 8
+ * // -> 9
+ * // -> 10
+ * ```
+ */
+export function dropWhile<T>(
+  it: Iterable<T>,
+  f: IterablePredicateCallback<T>,
+): IterableCircular<T> {
+  return dropUntil(it, (...args) => !f(...args));
+}
+
 /**
  * Returns the items of an iterable that meet the condition specified in a
  * callback function.

lib/transformers_test.ts

@@ -14,6 +14,17 @@ Deno.test("take", () => {
   assertEquals(testArray.slice(0, 5), [...transformers.take(testIter, 5)]);
 });
 
+Deno.test("drop", () => {
+  const testArray = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+  const testIter = testArray[Symbol.iterator]();
+
+  assertEquals(testArray.slice(5), [...transformers.drop(testIter, 5)]);
+
+  const numbers = create.range(1, 10);
+
+  assertEquals([...numbers].slice(6), [...transformers.drop(numbers, 6)]);
+});
+
 Deno.test("map", () => {
   const id: (x: number) => number = (x) => x;
 
@@ -83,6 +94,44 @@ Deno.test("until", () => {
   assertEquals(cutNumbersExclusive[cutNumbersExclusive.length - 1], 4);
 });
 
+Deno.test("dropUntil", () => {
+  const numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+  const cutNumbers = [...transformers.dropUntil(numbers, (n) => n === 5)];
+  const cutNumbersExclusive = [
+    ...transformers.dropUntil(numbers, (n) => n === 5, false),
+  ];
+
+  assertEquals(cutNumbers, [5, 6, 7, 8, 9]);
+  assertEquals(cutNumbersExclusive, [6, 7, 8, 9]);
+
+  {
+    const numbers = create.range(1, 10);
+    const dropped = transformers.dropUntil(numbers, (n) => n >= 5);
+    const droppedExclusive = transformers.dropUntil(
+      numbers,
+      (n) => n >= 5,
+      false,
+    );
+    assertEquals([...dropped], [5, 6, 7, 8, 9, 10]);
+    assertEquals([...droppedExclusive], [6, 7, 8, 9, 10]);
+  }
+});
+
+Deno.test("takeWhile", () => {
+  const numbers = create.range(1, 10);
+
+  const taken = transformers.takeWhile(numbers, (n) => n <= 5);
+  assertEquals([...taken], [1, 2, 3, 4, 5]);
+});
+
+Deno.test("dropWhile", () => {
+  const numbers = create.range(1, 10);
+
+  const dropped = transformers.dropWhile(numbers, (n) => n <= 5);
+  assertEquals([...dropped], [6, 7, 8, 9, 10]);
+});
+
 Deno.test("indexedPairs", () => {
   const numbers = [9, 8, 7, 6, 5, 4, 3, 2, 1];
   [...transformers.indexedPairs(numbers)].forEach(([i, v]) => {