feat(at): Implement at function

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' },

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' },

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' },

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' },

docs/ja/reference/array/at.md

@@ -0,0 +1,28 @@
+# at
+
+指定したインデックスの位置から配列の要素を取得します。
+
+## インターフェース
+
+```typescript
+function at<T>(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]
+```

docs/ko/reference/array/at.md

@@ -0,0 +1,28 @@
+# at
+
+배열에서 주어진 인덱스에 있는 요소들을 선택해서, 새 배열을 반환해요.
+
+## 인터페이스
+
+```typescript
+function at<T>(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]
+```

docs/reference/array/at.md

@@ -0,0 +1,28 @@
+# at
+
+Retrieves elements from an array at the specified indices.
+
+## Signature
+
+```typescript
+function at<T>(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]
+```

docs/zh_hans/reference/array/at.md

@@ -0,0 +1,36 @@
+# at
+
+从数组中检索指定索引处的元素。
+
+## 签名
+
+```typescript
+function at<T>(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                    |

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([]);
+  });
+});

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<T>(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;
+}