effect 4.0.0-rc.112 → 4.0.0-rc.113

package/dist/Array.d.ts

@@ -131,6 +131,7 @@ export declare const make: <Elements extends NonEmptyArray<unknown>>(...elements
  *
  * **Details**
  *
+ * `n` is rounded down. `NaN` and non-positive values are treated as `0`.
  * Elements are typed as `A | undefined` because the slots are empty.
  *
  * **Example** (Allocating a fixed-size array)
@@ -156,9 +157,9 @@ export declare const allocate: <A = never>(n: number) => Array<A | undefined>;
  *
  * **Details**
  *
- * `n` is normalized to an integer greater than or equal to 1, so this function
- * always returns at least one element. Supports both data-first and data-last
- * usage.
+ * `n` is rounded down and normalized to an integer greater than or equal to 1.
+ * `NaN` is treated as `1`, so this function always returns at least one
+ * element. Supports both data-first and data-last usage.
  *
  * **Example** (Generating values from indices)
  *
@@ -184,9 +185,9 @@ export declare const makeBy: {
      *
      * **Details**
      *
-     * `n` is normalized to an integer greater than or equal to 1, so this function
-     * always returns at least one element. Supports both data-first and data-last
-     * usage.
+     * `n` is rounded down and normalized to an integer greater than or equal to 1.
+     * `NaN` is treated as `1`, so this function always returns at least one
+     * element. Supports both data-first and data-last usage.
      *
      * **Example** (Generating values from indices)
      *
@@ -212,9 +213,9 @@ export declare const makeBy: {
      *
      * **Details**
      *
-     * `n` is normalized to an integer greater than or equal to 1, so this function
-     * always returns at least one element. Supports both data-first and data-last
-     * usage.
+     * `n` is rounded down and normalized to an integer greater than or equal to 1.
+     * `NaN` is treated as `1`, so this function always returns at least one
+     * element. Supports both data-first and data-last usage.
      *
      * **Example** (Generating values from indices)
      *
@@ -1976,7 +1977,8 @@ export declare const initNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the start)
  *
@@ -2003,7 +2005,8 @@ export declare const take: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the start)
      *
@@ -2030,7 +2033,8 @@ export declare const take: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the start)
      *
@@ -2058,7 +2062,8 @@ export declare const take: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the end)
  *
@@ -2084,7 +2089,8 @@ export declare const takeRight: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the end)
      *
@@ -2110,7 +2116,8 @@ export declare const takeRight: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the end)
      *
@@ -2506,8 +2513,8 @@ export declare const span: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
- * full array.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+ * When `n <= 0`, this returns a copy of the full array.
  *
  * **Example** (Dropping from the start)
  *
@@ -2535,8 +2542,8 @@ export declare const drop: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
-     * full array.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * When `n <= 0`, this returns a copy of the full array.
      *
      * **Example** (Dropping from the start)
      *
@@ -2564,8 +2571,8 @@ export declare const drop: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
-     * full array.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
+     * When `n <= 0`, this returns a copy of the full array.
      *
      * **Example** (Dropping from the start)
      *
@@ -2593,7 +2600,7 @@ export declare const drop: {
  *
  * **Details**
  *
- * `n` is clamped to `[0, length]`.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
  *
  * **Example** (Dropping from the end)
  *
@@ -2619,7 +2626,7 @@ export declare const dropRight: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
      *
      * **Example** (Dropping from the end)
      *
@@ -2645,7 +2652,7 @@ export declare const dropRight: {
      *
      * **Details**
      *
-     * `n` is clamped to `[0, length]`.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`.
      *
      * **Example** (Dropping from the end)
      *
@@ -5195,8 +5202,8 @@ export declare const chop: {
  *
  * **Details**
  *
- * `n` can be `0`, in which case all elements are placed in the second array.
- * The index is floored to an integer.
+ * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+ * which places all elements in the second array.
  *
  * **Example** (Splitting at an index)
  *
@@ -5222,8 +5229,8 @@ export declare const splitAt: {
      *
      * **Details**
      *
-     * `n` can be `0`, in which case all elements are placed in the second array.
-     * The index is floored to an integer.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+     * which places all elements in the second array.
      *
      * **Example** (Splitting at an index)
      *
@@ -5249,8 +5256,8 @@ export declare const splitAt: {
      *
      * **Details**
      *
-     * `n` can be `0`, in which case all elements are placed in the second array.
-     * The index is floored to an integer.
+     * `n` is rounded down and clamped to `[0, length]`. `NaN` is treated as `0`,
+     * which places all elements in the second array.
      *
      * **Example** (Splitting at an index)
      *
@@ -5277,6 +5284,10 @@ export declare const splitAt: {
  * Use when downstream code requires the left side of the split to contain at
  * least one element.
  *
+ * **Details**
+ *
+ * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+ *
  * **Example** (Splitting a non-empty array)
  *
  * ```ts import.meta.vitest
@@ -5300,6 +5311,10 @@ export declare const splitAtNonEmpty: {
      * Use when downstream code requires the left side of the split to contain at
      * least one element.
      *
+     * **Details**
+     *
+     * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+     *
      * **Example** (Splitting a non-empty array)
      *
      * ```ts import.meta.vitest
@@ -5323,6 +5338,10 @@ export declare const splitAtNonEmpty: {
      * Use when downstream code requires the left side of the split to contain at
      * least one element.
      *
+     * **Details**
+     *
+     * `n` is rounded down and clamped to `[1, length]`. `NaN` is treated as `1`.
+     *
      * **Example** (Splitting a non-empty array)
      *
      * ```ts import.meta.vitest
@@ -5347,7 +5366,8 @@ export declare const splitAtNonEmpty: {
  *
  * **Details**
  *
- * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+ * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+ * `1`. The last chunk may be shorter.
  *
  * **Example** (Splitting into groups)
  *
@@ -5372,7 +5392,8 @@ export declare const split: {
      *
      * **Details**
      *
-     * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+     * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+     * `1`. The last chunk may be shorter.
      *
      * **Example** (Splitting into groups)
      *
@@ -5397,7 +5418,8 @@ export declare const split: {
      *
      * **Details**
      *
-     * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
+     * `n` is rounded down and normalized to at least `1`, with `NaN` treated as
+     * `1`. The last chunk may be shorter.
      *
      * **Example** (Splitting into groups)
      *
@@ -5591,7 +5613,8 @@ export declare const copy: {
  *
  * **Details**
  *
- * Returns an empty array when `n <= 0`.
+ * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+ * returns an empty array.
  *
  * **Example** (Padding an array)
  *
@@ -5618,7 +5641,8 @@ export declare const pad: {
      *
      * **Details**
      *
-     * Returns an empty array when `n <= 0`.
+     * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+     * returns an empty array.
      *
      * **Example** (Padding an array)
      *
@@ -5645,7 +5669,8 @@ export declare const pad: {
      *
      * **Details**
      *
-     * Returns an empty array when `n <= 0`.
+     * `n` is rounded down. `NaN` and non-positive values are treated as `0`, which
+     * returns an empty array.
      *
      * **Example** (Padding an array)
      *
@@ -5674,8 +5699,10 @@ export declare const pad: {
  *
  * **Details**
  *
- * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
- * the outer return type preserves `NonEmptyArray`.
+ * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+ * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+ * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+ * `NonEmptyArray`.
  *
  * **Example** (Chunking an array)
  *
@@ -5703,8 +5730,10 @@ export declare const chunksOf: {
      *
      * **Details**
      *
-     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-     * the outer return type preserves `NonEmptyArray`.
+     * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+     * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+     * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+     * `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5732,8 +5761,10 @@ export declare const chunksOf: {
      *
      * **Details**
      *
-     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-     * the outer return type preserves `NonEmptyArray`.
+     * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+     * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+     * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+     * `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5761,8 +5792,10 @@ export declare const chunksOf: {
      *
      * **Details**
      *
-     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
-     * the outer return type preserves `NonEmptyArray`.
+     * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+     * values therefore produce singleton chunks. `chunksOf(n)([])` is `[]`, not
+     * `[[]]`. Each chunk is a `NonEmptyArray`, and the outer return type preserves
+     * `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5789,8 +5822,9 @@ export declare const chunksOf: {
  *
  * **Details**
  *
- * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
- * Each window is a tuple of exactly `n` elements.
+ * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+ * Returns an empty array if the normalized size is `0` or exceeds the array
+ * length. Each window is a tuple of exactly the normalized size.
  *
  * **Example** (Creating sliding windows)
  *
@@ -5818,8 +5852,9 @@ export declare const window: {
      *
      * **Details**
      *
-     * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-     * Each window is a tuple of exactly `n` elements.
+     * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+     * Returns an empty array if the normalized size is `0` or exceeds the array
+     * length. Each window is a tuple of exactly the normalized size.
      *
      * **Example** (Creating sliding windows)
      *
@@ -5847,8 +5882,9 @@ export declare const window: {
      *
      * **Details**
      *
-     * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-     * Each window is a tuple of exactly `n` elements.
+     * `n` is rounded down, with `NaN` and non-positive values treated as `0`.
+     * Returns an empty array if the normalized size is `0` or exceeds the array
+     * length. Each window is a tuple of exactly the normalized size.
      *
      * **Example** (Creating sliding windows)
      *