feat(collections/unstable): support Iterable argument in slidingWindows (#6095)

Author: Liam-Tait

collections/deno.json

@@ -51,6 +51,7 @@
     "./unstable-drop-last-while": "./unstable_drop_last_while.ts",
     "./unstable-intersect": "./unstable_intersect.ts",
     "./unstable-sample": "./unstable_sample.ts",
+    "./unstable-sliding-windows": "./unstable_sliding_windows.ts",
     "./unstable-sort-by": "./unstable_sort_by.ts",
     "./unstable-take-last-while": "./unstable_take_last_while.ts",
     "./unstable-take-while": "./unstable_take_while.ts",

collections/unstable_sliding_windows.ts

@@ -0,0 +1,101 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/** Options for {@linkcode slidingWindows}. */
+export interface SlidingWindowsOptions {
+  /**
+   * If step is set, each window will start that many elements after the last
+   * window's start.
+   *
+   * @default {1}
+   */
+  step?: number;
+  /**
+   * If partial is set, windows will be generated for the last elements of the
+   * collection, resulting in some undefined values if size is greater than 1.
+   *
+   * @default {false}
+   */
+  partial?: boolean;
+}
+
+/**
+ * Generates sliding views of the given iterable of the given size and returns an
+ * array containing all of them.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * If step is set, each window will start that many elements after the last
+ * window's start. (Default: 1)
+ *
+ * If partial is set, windows will be generated for the last elements of the
+ * collection, resulting in some undefined values if size is greater than 1.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param iterable The iterable to generate sliding windows from.
+ * @param size The size of the sliding windows.
+ * @param options The options for generating sliding windows.
+ *
+ * @returns An array containing all sliding windows of the given size.
+ *
+ * @example Usage
+ * ```ts
+ * import { slidingWindows } from "@std/collections/unstable-sliding-windows";
+ * import { assertEquals } from "@std/assert";
+ * const numbers = [1, 2, 3, 4, 5];
+ *
+ * const windows = slidingWindows(numbers, 3);
+ * assertEquals(windows, [
+ *   [1, 2, 3],
+ *   [2, 3, 4],
+ *   [3, 4, 5],
+ * ]);
+ *
+ * const windowsWithStep = slidingWindows(numbers, 3, { step: 2 });
+ * assertEquals(windowsWithStep, [
+ *   [1, 2, 3],
+ *   [3, 4, 5],
+ * ]);
+ *
+ * const windowsWithPartial = slidingWindows(numbers, 3, { partial: true });
+ * assertEquals(windowsWithPartial, [
+ *   [1, 2, 3],
+ *   [2, 3, 4],
+ *   [3, 4, 5],
+ *   [4, 5],
+ *   [5],
+ * ]);
+ * ```
+ */
+export function slidingWindows<T>(
+  iterable: Iterable<T>,
+  size: number,
+  options: SlidingWindowsOptions = {},
+): T[][] {
+  const { step = 1, partial = false } = options;
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new RangeError(
+      `Cannot create sliding windows: size must be a positive integer, current value is ${size}`,
+    );
+  }
+  if (!Number.isInteger(step) || step <= 0) {
+    throw new RangeError(
+      `Cannot create sliding windows: step must be a positive integer, current value is ${step}`,
+    );
+  }
+  const array = Array.isArray(iterable) ? iterable : Array.from(iterable);
+  const len = array.length;
+  const result: T[][] = [];
+  for (let i = 0; i <= len; i += step) {
+    let last = i + size;
+    if (last > len) {
+      last = len;
+    }
+    const window: T[] = array.slice(i, last);
+    if ((partial && window.length) || window.length === size) {
+      result.push(window);
+    }
+  }
+  return result;
+}