diff --git a/docs/.vitepress/en.mts b/docs/.vitepress/en.mts index b4ba1b53..8c229d9e 100644 --- a/docs/.vitepress/en.mts +++ b/docs/.vitepress/en.mts @@ -48,6 +48,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'Array Utilities', items: [ + { text: 'at', link: '/reference/array/at' }, { text: 'chunk', link: '/reference/array/chunk' }, { text: 'concat (compat)', link: '/reference/compat/array/concat' }, { text: 'countBy', link: '/reference/array/countBy' }, diff --git a/docs/.vitepress/ja.mts b/docs/.vitepress/ja.mts index 13e9c541..a60a2b1a 100644 --- a/docs/.vitepress/ja.mts +++ b/docs/.vitepress/ja.mts @@ -47,6 +47,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: '配列', items: [ + { text: 'at', link: '/ja/reference/array/at' }, { text: 'chunk', link: '/ja/reference/array/chunk' }, { text: 'concat (compat)', link: '/ja/reference/compat/array/concat' }, { text: 'countBy', link: '/ja/reference/array/countBy' }, diff --git a/docs/.vitepress/ko.mts b/docs/.vitepress/ko.mts index fa2f69ab..0f715deb 100644 --- a/docs/.vitepress/ko.mts +++ b/docs/.vitepress/ko.mts @@ -47,6 +47,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: '배열', items: [ + { text: 'at', link: '/ko/reference/array/at' }, { text: 'chunk', link: '/ko/reference/array/chunk' }, { text: 'concat (호환성)', link: '/ko/reference/compat/array/concat' }, { text: 'countBy', link: '/ko/reference/array/countBy' }, diff --git a/docs/.vitepress/zh_hans.mts b/docs/.vitepress/zh_hans.mts index 7312b2ae..74e62f9a 100644 --- a/docs/.vitepress/zh_hans.mts +++ b/docs/.vitepress/zh_hans.mts @@ -48,6 +48,7 @@ function sidebar(): DefaultTheme.Sidebar { { text: '数组工具', items: [ + { text: 'at', link: '/zh_hans/reference/array/at' }, { text: 'chunk', link: '/zh_hans/reference/array/chunk' }, { text: 'concat (兼容性)', link: '/zh_hans/reference/compat/array/concat' }, { text: 'countBy', link: '/zh_hans/reference/array/countBy' }, diff --git a/docs/ja/reference/array/at.md b/docs/ja/reference/array/at.md new file mode 100644 index 00000000..0315b560 --- /dev/null +++ b/docs/ja/reference/array/at.md @@ -0,0 +1,28 @@ +# at + +指定したインデックスの位置から配列の要素を取得します。 + +## インターフェース + +```typescript +function at(arr: T[], indices: number[]): T[]; +``` + +### パラメータ + +- `arr` (`T[]`): 要素を取得する元の配列。 +- `indices` (`number[]`): 取得する要素の位置を指定するインデックスの配列。 + +### 戻り値 + +(`T[]`): 指定されたインデックスの位置にある要素を含む新しい配列。 + +## 例 + +```typescript +import { at } from 'es-toolkit/array'; + +const numbers = [10, 20, 30, 40, 50]; +const result = at(numbers, [1, 3, 4]); +console.log(result); // [20, 40, 50] +``` diff --git a/docs/ko/reference/array/at.md b/docs/ko/reference/array/at.md new file mode 100644 index 00000000..f09627f3 --- /dev/null +++ b/docs/ko/reference/array/at.md @@ -0,0 +1,28 @@ +# at + +배열에서 주어진 인덱스에 있는 요소들을 선택해서, 새 배열을 반환해요. + +## 인터페이스 + +```typescript +function at(arr: T[], indices: number[]): T[]; +``` + +### 파라미터 + +- `arr` (`T[]`): 요소를 가져올 배열. +- `indices` (`number[]`): 요소를 가져올 인덱스. + +### 반환 값 + +(`T[]`): 주어진 인덱스에 있는 요소들을 가지는 새 배열. + +## 예시 + +```typescript +import { at } from 'es-toolkit/array'; + +const numbers = [10, 20, 30, 40, 50]; +const result = at(numbers, [1, 3, 4]); +console.log(result); // [20, 40, 50] +``` diff --git a/docs/reference/array/at.md b/docs/reference/array/at.md new file mode 100644 index 00000000..e5be8fdb --- /dev/null +++ b/docs/reference/array/at.md @@ -0,0 +1,28 @@ +# at + +Retrieves elements from an array at the specified indices. + +## Signature + +```typescript +function at(arr: T[], indices: number[]): T[]; +``` + +### Parameters + +- `arr` (`T[]`): The array to retrieve elements from. +- `indices` (`number[]`): An array of indices specifying the positions of elements to retrieve. + +### Returns + +(`T[]`): A new array containing the elements at the specified indices. + +## Examples + +```typescript +import { at } from 'es-toolkit/array'; + +const numbers = [10, 20, 30, 40, 50]; +const result = at(numbers, [1, 3, 4]); +console.log(result); // [20, 40, 50] +``` diff --git a/docs/zh_hans/reference/array/at.md b/docs/zh_hans/reference/array/at.md new file mode 100644 index 00000000..0ff6f620 --- /dev/null +++ b/docs/zh_hans/reference/array/at.md @@ -0,0 +1,36 @@ +# at + +从数组中检索指定索引处的元素。 + +## 签名 + +```typescript +function at(arr: T[], indices: number[]): T[]; +``` + +### 参数 + +- `arr` (`T[]`): 要从中检索元素的数组。 +- `indices` (`number[]`): 一个指定元素位置的索引数组。 + +### 返回值 + +(`T[]`): 一个新数组,包含在指定索引处的元素。 + +## 示例 + +```typescript +import { at } from 'es-toolkit/array'; + +const numbers = [10, 20, 30, 40, 50]; +const result = at(numbers, [1, 3, 4]); +console.log(result); // [20, 40, 50] +``` + +## Performance Comparison + +| | [Bundle Size](../../bundle-size.md) | [Performance](../../performance.md) | +| ----------------- | ----------------------------------- | ----------------------------------- | +| es-toolkit | 238 bytes (92.4% smaller) | 9,338,821 times (11% slower) | +| es-toolkit/compat | 307 bytes (90.2% smaller) | 9,892,157 times (5% slower) | +| lodash-es | 3,153 bytes | 10,523,270 times | diff --git a/src/array/at.spec.ts b/src/array/at.spec.ts new file mode 100644 index 00000000..e1f1e411 --- /dev/null +++ b/src/array/at.spec.ts @@ -0,0 +1,17 @@ +import { describe, expect, it } from 'vitest'; +import { at } from './at'; + +describe('at', () => { + it('should return the elements corresponding to the specified keys', () => { + expect(at(['a', 'b', 'c'], [0, 2])).toEqual(['a', 'c']); + expect(at(['a', 'b', 'c'], [2, 0])).toEqual(['c', 'a']); + }); + + it('should return `undefined` for nonexistent keys', () => { + expect(at(['a', 'b', 'c'], [2, 4, 0])).toEqual(['c', undefined, 'a']); + }); + + it('should return an empty array when no keys are given', () => { + expect(at(['a', 'b', 'c'], [])).toEqual([]); + }); +}); diff --git a/src/array/at.ts b/src/array/at.ts new file mode 100644 index 00000000..5ef1fe3a --- /dev/null +++ b/src/array/at.ts @@ -0,0 +1,24 @@ +/** + * Retrieves elements from an array at the specified indices. + * + * @template T + * @param {readonly T[]} arr - The array to retrieve elements from. + * @param {number[]} indices - An array of indices specifying the positions of elements to retrieve. + * @returns {T[]} A new array containing the elements at the specified indices. + * + * @example + * const numbers = [10, 20, 30, 40, 50]; + * const result = at(numbers, [1, 3, 4]); + * console.log(result); // [20, 40, 50] + */ +export function at(arr: readonly T[], indices: number[]) { + const result: T[] = []; + + for (let i = 0; i < indices.length; i++) { + const index = indices[i]; + + result.push(arr[index]); + } + + return result; +}