feat(toFilled): Add toFilled (#154)

* feat: add toFilled

* feat: add test for toFilled

* feat: add bench for toFilled

* docs: add docs for toFilled

* chore: Modified benchmark wording

* Update benchmarks/toFilled.bench.ts

Co-authored-by: jgjgill <79239852+jgjgill@users.noreply.github.com>

* fix: toFilled benchmark

* Apply suggestions from code review

* Update docs/ko/reference/array/toFilled.md

* Update docs/reference/array/toFilled.md

---------

Co-authored-by: Sojin Park <raon0211@gmail.com>
Co-authored-by: jgjgill <79239852+jgjgill@users.noreply.github.com>

benchmarks/toFilled.bench.ts

@@ -0,0 +1,23 @@
+import { bench, describe } from 'vitest';
+import { fill as fillLodash } from 'lodash';
+import { toFilled as toFilledToolkit } from 'es-toolkit';
+
+describe('fill function performance comparison', () => {
+  bench('es-toolkit/toFilled', () => {
+    toFilledToolkit([1, 2, 3, 4, 5], '*');
+  });
+
+  bench('lodash/fill', () => {
+    fillLodash([1, 2, 3, 4, 5], '*');
+  });
+});
+
+describe('fill function performance with custom start and end', () => {
+  bench('es-toolkit/toFilled', () => {
+    toFilledToolkit([1, 2, 3, 4, 5], '*', 1, 3);
+  });
+
+  bench('lodash/fill', () => {
+    fillLodash([1, 2, 3, 4, 5], '*', 1, 3);
+  });
+});

docs/.vitepress/en.mts

@@ -58,6 +58,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropRight', link: '/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/reference/array/dropRightWhile' },
             { text: 'fill', link: '/reference/array/fill' },
+            { text: 'toFilled', link: '/reference/array/toFilled' },
             { text: 'flatten', link: '/reference/array/flatten' },
             { text: 'forEachRight', link: '/reference/array/forEachRight' },
             { text: 'groupBy', link: '/reference/array/groupBy' },

docs/.vitepress/ko.mts

@@ -57,6 +57,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropRight', link: '/ko/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/ko/reference/array/dropRightWhile' },
             { text: 'fill', link: '/ko/reference/array/fill' },
+            { text: 'toFilled', link: '/ko/reference/array/toFilled' },
             { text: 'flatten', link: '/ko/reference/array/flatten' },
             { text: 'forEachRight', link: '/reference/array/forEachRight' },
             { text: 'groupBy', link: '/ko/reference/array/groupBy' },

docs/ko/reference/array/toFilled.md

@@ -0,0 +1,46 @@
+# toFilled
+
+배열의 요소를 지정된 값으로 채워요. 시작 위치부터 끝 위치까지의 요소들을 제공된 값으로 대체한 새로운 배열을 반환해요. 시작 또는 끝 인덱스를 제공하지 않으면 배열 전체를 채워요.
+
+음수 인덱스를 사용할 수도 있어요. 이 경우 배열의 끝에서부터 인덱스를 계산해요.
+
+## 인터페이스
+
+```typescript
+function toFilled<T, U>(arr: T[], value: U): Array<T | U>;
+function toFilled<T, U>(arr: T[], value: U, start: number): Array<T | U>;
+function toFilled<T, U>(arr: T[], value: U, start: number, end: number): Array<T | U>;
+```
+
+### 파라미터
+
+- `arr` (`Array<T>`): 채울 배얼이에요.
+- `value` (`U`): 배열을 채울 값이에요.
+- `start` (`number, 기본값 = 0`): 시작 위치예요. 기본값은 0이에요.
+- `end` (`number, 기본값 = array.length`): 끝 위치예요. 기본값은 배열의 길이예요.
+
+### 반환 값
+
+(`Array<T | U>`): 지정된 값으로 채워진 새로운 배열이에요.
+
+### 예시
+
+```typescript
+const array = [1, 2, 3, 4, 5];
+
+let result = toFilled(array, '*', 2);
+console.log(result); // [1, 2, '*', '*', '*']
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*', 1, 4);
+console.log(result); // [1, '*', '*', '*', 5]
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*');
+console.log(result); // ['*', '*', '*', '*', '*']
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*', -4, -1);
+console.log(result); // [1, '*', '*', '*', 5]
+console.log(array); // [1, 2, 3, 4, 5]
+```

docs/reference/array/toFilled.md

@@ -0,0 +1,48 @@
+# toFilled
+
+Creates a new array filled with a specified value from the start position up to, but not including, the end position.
+
+If the start or end indices are not provided, it defaults to filling the entire array.
+
+Negative indices can also be used, in which case they are counted from the end of the array.
+
+## Interface
+
+```typescript
+function toFilled<T, U>(arr: T[], value: U): Array<T | U>;
+function toFilled<T, U>(arr: T[], value: U, start: number): Array<T | U>;
+function toFilled<T, U>(arr: T[], value: U, start: number, end: number): Array<T | U>;
+```
+
+### Parameters
+
+- `arr` (`Array<T>`): The array to base the new array on.
+- `value` (`U`): The value to fill the new array with.
+- `start` (`number, default = 0`): The start position. Defaults to 0.
+- `end` (`number, default = array.length`): The end position. Defaults to the array's length.
+
+### Return Value
+
+(`Array<T | U>`): A new array with the specified values filled in.
+
+### Examples
+
+```typescript
+const array = [1, 2, 3, 4, 5];
+
+let result = toFilled(array, '*', 2);
+console.log(result); // [1, 2, '*', '*', '*']
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*', 1, 4);
+console.log(result); // [1, '*', '*', '*', 5]
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*');
+console.log(result); // ['*', '*', '*', '*', '*']
+console.log(array); // [1, 2, 3, 4, 5]
+
+result = toFilled(array, '*', -4, -1);
+console.log(result); // [1, '*', '*', '*', 5]
+console.log(array); // [1, 2, 3, 4, 5]
+```

src/array/index.ts

@@ -44,4 +44,5 @@ export { zipWith } from './zipWith.ts';
 export { without } from './without.ts';
 export { head } from './head.ts';
 export { tail } from './tail.ts';
+export { toFilled } from './toFilled.ts';
 export { last } from './last.ts';

src/array/toFilled.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'vitest';
+import { toFilled } from './toFilled';
+
+describe('toFilled function tests', () => {
+  test('handles empty array', () => {
+    const result = toFilled([], '*');
+    expect(result).toEqual([]);
+  });
+
+  test('fills middle values', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*', 1, 4);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
+
+  test('fills entire array', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*');
+    expect(result).toEqual(['*', '*', '*', '*', '*']);
+  });
+
+  test('fills from specified start position', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*', 2);
+    expect(result).toEqual([1, 2, '*', '*', '*']);
+  });
+
+  test('handles negative start position', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*', -3);
+    expect(result).toEqual([1, 2, '*', '*', '*']);
+  });
+
+  test('handles positive start and negative end positions', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*', 1, -1);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
+
+  test('handles both negative start and end positions', () => {
+    const result = toFilled([1, 2, 3, 4, 5], '*', -4, -1);
+    expect(result).toEqual([1, '*', '*', '*', 5]);
+  });
+});

src/array/toFilled.ts

@@ -0,0 +1,45 @@
+/**
+ * Creates a new array filled with the specified value from the start position up to, but not including, the end position.
+ * This function does not mutate the original array.
+ *
+ * @param {Array<T>} arr - The array to base the new array on.
+ * @param {U} value - The value to fill the new array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
+ * @returns {Array<T | U>} The new array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * let result = toFilled(array, '*', 2);
+ * console.log(result); // [1, 2, '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', 1, 4);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*');
+ * console.log(result); // ['*', '*', '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', -4, -1);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ */
+
+export function toFilled<T, U>(arr: T[], value: U): Array<T | U>;
+export function toFilled<T, U>(arr: T[], value: U, start: number): Array<T | U>;
+export function toFilled<T, U>(arr: T[], value: U, start: number, end: number): Array<T | U>;
+export function toFilled<T, U>(arr: T[], value: U, start = 0, end = arr.length): Array<T | U> {
+  const length = arr.length;
+  const finalStart = Math.max(start >= 0 ? start : length + start, 0);
+  const finalEnd = Math.min(end >= 0 ? end : length + end, length);
+
+  const newArr: Array<T | U> = arr.slice();
+
+  for (let i = finalStart; i < finalEnd; i++) {
+    newArr[i] = value;
+  }
+
+  return newArr;
+}