diff --git a/benchmarks/head.bench.ts b/benchmarks/head.bench.ts new file mode 100644 index 00000000..f1abf697 --- /dev/null +++ b/benchmarks/head.bench.ts @@ -0,0 +1,13 @@ +import { bench, describe } from 'vitest'; +import { head as headToolkit } from 'es-toolkit'; +import { head as headLodash } from 'lodash'; + +describe('head', () => { + bench('es-toolkit/head', () => { + headToolkit([1, 2, 3, 4]); + }); + + bench('lodash/head', () => { + headLodash([1, 2, 3, 4]); + }); +}); diff --git a/docs/.vitepress/en.mts b/docs/.vitepress/en.mts index 119aeca4..d31c2734 100644 --- a/docs/.vitepress/en.mts +++ b/docs/.vitepress/en.mts @@ -89,6 +89,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'zip', link: '/reference/array/zip' }, { text: 'zipObject', link: '/reference/array/zipObject' }, { text: 'zipWith', link: '/reference/array/zipWith' }, + { text: 'head', link: '/reference/array/head' }, ], }, { diff --git a/docs/.vitepress/ko.mts b/docs/.vitepress/ko.mts index 6536e9ac..c2c3e2e2 100644 --- a/docs/.vitepress/ko.mts +++ b/docs/.vitepress/ko.mts @@ -88,6 +88,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'zip', link: '/ko/reference/array/zip' }, { text: 'zipObject', link: '/ko/reference/array/zipObject' }, { text: 'zipWith', link: '/ko/reference/array/zipWith' }, + { text: 'head', link: '/ko/reference/array/head' }, ], }, { diff --git a/docs/ko/reference/array/head.md b/docs/ko/reference/array/head.md new file mode 100644 index 00000000..a03a06ed --- /dev/null +++ b/docs/ko/reference/array/head.md @@ -0,0 +1,44 @@ +# head + +배열의 첫 번째 요소를 반환해요. + +이 함수는 배열을 입력받아 배열의 첫 번째 요소를 반환해요. 배열이 비어 있는 경우, 함수는 `undefined`를 반환해요. + +## 인터페이스 + +```typescript +export function head(arr: readonly [T, ...T[]]): T; +export function head(arr: readonly T[]): T | undefined; +``` + +### 파라미터 + +- `arr` (`T[]`): 첫 번째 요소를 가져올 배열이에요. + +### 반환 값 + +(`T | undefined`): 배열의 첫 번째 요소, 배열이 비어 있는 경우 `undefined`를 반환해요. + +## 예시 + +```typescript +const arr1 = [1, 2, 3]; +const firstElement1 = head(arr1); +// firstElement1은 1이에요. + +const arr2: string[] = []; +const firstElement2 = head(arr2); +// firstElement2는 undefined에요. + +const arr3 = ['a', 'b', 'c']; +const firstElement3 = head(arr3); +// firstElement3는 'a'이에요. + +const arr4 = [true, false, true]; +const firstElement4 = head(arr4); +// firstElement4는 true에요. + +const arr5: [number, string, boolean] = [1, 'a', true]; +const firstElement5 = head(arr5); +// firstElement5는 1이에요. +``` diff --git a/docs/reference/array/head.md b/docs/reference/array/head.md new file mode 100644 index 00000000..d9d24ad3 --- /dev/null +++ b/docs/reference/array/head.md @@ -0,0 +1,44 @@ +# head + +Returns the first element of an array. + +This function takes an array and returns the first element of the array. If the array is empty, the function returns `undefined`. + +## Signature + +```typescript +export function head(arr: readonly [T, ...T[]]): T; +export function head(arr: readonly T[]): T | undefined; +``` + +### Parameters + +- `arr` (`T[]`): The array from which to get the first element. + +### Returns + +(`T | undefined`): The first element of the array, or `undefined` if the array is empty. + +## Examples + +```typescript +const arr1 = [1, 2, 3]; +const firstElement1 = head(arr1); +// firstElement1 will be 1 + +const arr2: string[] = []; +const firstElement2 = head(arr2); +// firstElement2 will be undefined + +const arr3 = ['a', 'b', 'c']; +const firstElement3 = head(arr3); +// firstElement3 will be 'a' + +const arr4 = [true, false, true]; +const firstElement4 = head(arr4); +// firstElement4 will be true + +const arr5: [number, string, boolean] = [1, 'a', true]; +const firstElement5 = head(arr5); +// firstElement5 will be 1 +``` diff --git a/src/array/head.spec.ts b/src/array/head.spec.ts new file mode 100644 index 00000000..9300d100 --- /dev/null +++ b/src/array/head.spec.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from 'vitest'; +import { head } from './head'; + +describe('head', () => { + it('returns the first element of an array or undefined for empty arrays', () => { + expect(head([1, 2, 3])).toBe(1); + + expect(head(['a', 'b', 'c'])).toBe('a'); + + expect(head([true, false, true])).toBe(true); + + expect(head([])).toBeUndefined(); + }); +}); diff --git a/src/array/head.ts b/src/array/head.ts new file mode 100644 index 00000000..798a5e42 --- /dev/null +++ b/src/array/head.ts @@ -0,0 +1,23 @@ +/** + * Returns the first element of an array. + * + * This function takes an array and returns the first element of the array. + * If the array is empty, the function returns `undefined`. + * + * @param {T[]} arr - The array from which to get the first element. + * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty. + * + * @example + * const arr = [1, 2, 3]; + * const firstElement = head(arr); + * // firstElement will be 1 + * + * const emptyArr: number[] = []; + * const noElement = head(emptyArr); + * // noElement will be undefined + */ +export function head(arr: readonly [T, ...T[]]): T; +export function head(arr: readonly T[]): T | undefined; +export function head(arr: readonly T[]): T | undefined { + return arr[0]; +} diff --git a/src/array/index.ts b/src/array/index.ts index 02577998..ecebc958 100644 --- a/src/array/index.ts +++ b/src/array/index.ts @@ -40,3 +40,4 @@ export { zip } from './zip.ts'; export { zipObject } from './zipObject.ts'; export { zipWith } from './zipWith.ts'; export { without } from './without.ts'; +export { head } from './head.ts';