feat(fill): Add fill function (#109)

* feat(fill): Add fill function

* feat(fill): Add test/brench code

* feat(fill): Update docs

* feat(fill): Refactor based on code review

* refactor(fill): array to arr

* fix(fill): update `fill` function signature to support mixed types

benchmarks/fill.bench.ts

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

docs/.vitepress/en.mts

@@ -56,6 +56,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropWhile', link: '/reference/array/dropWhile' },
             { text: 'dropRight', link: '/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/reference/array/dropRightWhile' },
+            { text: 'fill', link: '/reference/array/fill' },
             { text: 'groupBy', link: '/reference/array/groupBy' },
             { text: 'intersection', link: '/reference/array/intersection' },
             { text: 'intersectionBy', link: '/reference/array/intersectionBy' },

docs/.vitepress/ko.mts

@@ -55,6 +55,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'dropWhile', link: '/ko/reference/array/dropWhile' },
             { text: 'dropRight', link: '/ko/reference/array/dropRight' },
             { text: 'dropRightWhile', link: '/ko/reference/array/dropRightWhile' },
+            { text: 'fill', link: '/ko/reference/array/fill' },
             { text: 'groupBy', link: '/ko/reference/array/groupBy' },
             { text: 'intersection', link: '/ko/reference/array/intersection' },
             { text: 'intersectionBy', link: '/ko/reference/array/intersectionBy' },

docs/ko/reference/array/fill.md

@@ -0,0 +1,41 @@
+# fill
+
+배열의 요소를 지정된 값으로 채워요. 시작 위치부터 끝 위치까지의 요소들을 제공된 값으로 대체해요.
+
+이 함수는 원본 배열을 변경하고, 제공된 값으로 시작 인덱스부터 끝 인덱스까지의 요소를 대체해요.
+시작 또는 끝 인덱스를 제공하지 않으면 배열 전체를 채워요.
+
+## 인터페이스
+
+```typescript
+function fill<T>(array: unknown[], value: T): T[];
+function fill<T, P>(array: T[], value: P, start: number): Array<T | P>;
+function fill<T, P>(array: T[], value: P, start: number, end: number): Array<T | P>;
+```
+
+### 파라미터
+
+- `array` (`Array<T | P>`): 채울 배열이에요.
+- `value` (`P`): 배열을 채울 값이에요.
+- `start` (`number`, 기본값 = 0): 시작 위치에요. 기본값은 0이에요.
+- `end` (`number`, 기본값 = array.length): 끝 위치에요. 기본값은 배열의 길이에요.
+
+### 반환 값
+
+(`Array<T | P>`): 채워진 값이 있는 배열을 반환해요.
+
+## 예시
+
+```typescript
+const array1 = [1, 2, 3];
+const result1 = fill(array1, 'a');
+// result1는 ['a', 'a', 'a']가 돼요.
+
+const array2 = Array(3);
+const result2 = fill(array2, 2);
+// result2는 [2, 2, 2]가 돼요.
+
+const array3 = [4, 6, 8, 10];
+const result3 = fill(array3, '*', 1, 3);
+// result3는 [4, '*', '*', 10]가 돼요.
+```

docs/reference/array/fill.md

@@ -0,0 +1,40 @@
+# fill
+
+Fills elements of an array with a specified value from the start position up to, but not including, the end position.
+
+This function mutates the original array and replaces its elements with the provided value, starting from the specified start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the entire array.
+
+## Signature
+
+```typescript
+function fill<T>(array: unknown[], value: T): T[];
+function fill<T, P>(array: T[], value: P, start: number): Array<T | P>;
+function fill<T, P>(array: T[], value: P, start: number, end: number): Array<T | P>;
+```
+
+### Parameters
+
+- `array` (`Array<T | P>`): The array to fill.
+- `value` (`P`): The value to fill the 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.
+
+### Returns
+
+(`Array<T | P>`): The array with the filled values.
+
+## Examples
+
+```typescript
+const array1 = [1, 2, 3];
+const result1 = fill(array1, 'a');
+// result1 => ['a', 'a', 'a']
+
+const array2 = Array(3);
+const result2 = fill(array2, 2);
+// result2 => [2, 2, 2]
+
+const array3 = [4, 6, 8, 10];
+const result3 = fill(array3, '*', 1, 3);
+// result3 => [4, '*', '*', 10]
+```

src/array/fill.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { fill } from './fill';
+
+describe('fill', () => {
+  it('fills the entire array with the specified value', () => {
+    const array = [1, 2, 3];
+    expect(fill(array, 'a')).toEqual(['a', 'a', 'a']);
+  });
+
+  it('fills a new array with a specified value', () => {
+    expect(fill(Array(3), 2)).toEqual([2, 2, 2]);
+  });
+
+  it('fills part of an array from the start index to the end index', () => {
+    expect(fill([4, 6, 8, 10], '*', 1, 3)).toEqual([4, '*', '*', 10]);
+  });
+});

src/array/fill.ts

@@ -0,0 +1,38 @@
+/**
+ * Fills elements of an array with a specified value from the start position up to, but not including, the end position.
+ *
+ * This function mutates the original array and replaces its elements with the provided value, starting from the specified
+ * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
+ * entire array. Negative indices can be used to specify positions from the end of the array.
+ *
+ * @param {Array<T | P>} arr - The array to fill.
+ * @param {P} value - The value to fill the 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 | P>} The array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = fill(array, 'a');
+ * // => ['a', 'a', 'a']
+ *
+ * const result = fill(Array(3), 2);
+ * // => [2, 2, 2]
+ *
+ * const result = fill([4, 6, 8, 10], '*', 1, 3);
+ * // => [4, '*', '*', 10]
+ */
+
+export function fill<T>(arr: unknown[], value: T): T[];
+export function fill<T, P>(arr: Array<T | P>, value: P, start: number): Array<T | P>;
+export function fill<T, P>(arr: Array<T | P>, value: P, start: number, end: number): Array<T | P>;
+export function fill<T, P>(arr: Array<T | P>, value: P, start = 0, end = arr.length): Array<T | P> {
+  start = Math.max(start, 0);
+  end = Math.min(end, arr.length);
+
+  for (let i = start; i < end; i++) {
+    arr[i] = value;
+  }
+
+  return arr;
+}

src/array/index.ts

@@ -34,3 +34,4 @@ export { xorWith } from './xorWith.ts';
 export { zip } from './zip.ts';
 export { zipWith } from './zipWith.ts';
 export { zipObject } from './zipObject.ts';
+export { fill } from './fill.ts';