// Copyright 2018-2026 the Deno authors. MIT license.
// This module is browser compatible.
/**
* Returns a tuple of two arrays with the first one containing all elements in
* the given array that match the given predicate and the second one
* containing all that do not.
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* This version of the function is a type-guard version of the function. It
* allows you to specify a type-guard predicate function that narrows the type
* of the elements in the first output array.
*
* @typeParam T The type of the elements in the array.
* @typeParam U The type of the elements that match the predicate.
*
* @param array The array to partition.
* @param predicate The type-guard predicate function to determine which array
* an element belongs to.
*
* @returns A tuple of two arrays. The first array contains all elements that
* match the predicate, the second contains all elements that do not.
*
* @example Basic usage
* ```ts
* import { partition } from "@std/collections/unstable-partition";
* import { assertEquals } from "@std/assert";
*
* const mixed = [1, "a", 2, "b"];
* const isString = (x: unknown): x is string => typeof x === "string";
* const [strings, others] = partition(mixed, isString);
*
* assertEquals(strings, ["a", "b"]);
* assertEquals(others, [1, 2]);
* ```
*/
export function partition<T, U extends T>(
array: Iterable<T>,
predicate: (el: T) => el is U,
): [U[], Exclude<T, U>[]];
/**
* Returns a tuple of two arrays with the first one containing all elements in
* the given array that match the given predicate and the second one
* containing all that do not.
*
* @typeParam T The type of the elements in the array.
*
* @param array The array to partition.
* @param predicate The predicate function to determine which array an element
* belongs to.
*
* @returns A tuple of two arrays. The first array contains all elements that
* match the predicate, the second contains all elements that do not.
*
* @example Basic usage
* ```ts
* import { partition } from "@std/collections/unstable-partition";
* import { assertEquals } from "@std/assert";
*
* const numbers = [5, 6, 7, 8, 9];
* const [even, odd] = partition(numbers, (it) => it % 2 === 0);
*
* assertEquals(even, [6, 8]);
* assertEquals(odd, [5, 7, 9]);
* ```
*/
export function partition<T>(
array: Iterable<T>,
predicate: (el: T, index: number) => boolean,
): [T[], T[]];
export function partition(
array: Iterable<unknown>,
predicate: (el: unknown, index: number) => boolean,
): [unknown[], unknown[]] {
const matches: Array<unknown> = [];
const rest: Array<unknown> = [];
let index = 0;
for (const element of array) {
if (predicate(element, index++)) {
matches.push(element);
} else {
rest.push(element);
}
}
return [matches, rest];
}
|