typedash/dist/sample/index.d.cts

modern, type-safe collection of utility functions

import { M as Maybe } from '../Maybe-D6dwMjD9.cjs';

/**
 * Returns a random item from the input iterable.
 * @param source The iterable to get a random item from.
 * @returns A random item from the input iterable.
 * @example
 * ```ts
 * sample([1, 2, 3]) // 2
 * ```
 */
declare function sample<const T>(source: Iterable<T>): T;
/**
 * Returns N random items from the input iterable.
 * If the input iterable has less than N items, all items will be returned.
 * @param source The iterable to get a random item from.
 * @param count The number of items to return.
 * @returns A random item from the input iterable.
 * @example
 * ```ts
 * sample([1, 2, 3], 2) // [2, 3]
 * sample([1, 2, 3], 4) // [1, 2, 3]
 * sample([1, 2, 3], 0) // []
 * sample([1, 2, 3], -1) // []
 * ```
 */
declare function sample<const T>(source: Iterable<T>, count: number): T[];
/**
 * Returns a random item from the input iterable.
 * @param source The iterable to get a random item from.
 * @returns A random item from the input iterable.
 * @example
 * ```ts
 * sample(null) // undefined
 * sample(undefined) // undefined
 * ```
 */
declare function sample<const T>(source: Maybe<Iterable<T>>): T | undefined;
/**
 * Returns N random items from the input iterable.
 * If the input iterable has less than N items, all items will be returned.
 * @param source The iterable to get a random item from.
 * @param count The number of items to return.
 * @returns A random item from the input iterable.
 * @example
 * ```ts
 * sample([1, 2, 3], 2) // [2, 3]
 * sample([1, 2, 3], 4) // [1, 2, 3]
 * sample([1, 2, 3], 0) // []
 * sample([1, 2, 3], -1) // []
 * ```
 */
declare function sample<const T>(source: Maybe<Iterable<T>>, count: number): T[] | undefined;

export { sample };