feat(rangeRight): implement rangeRight (#646)

benchmarks/performance/rangeRight.bench.ts

@@ -0,0 +1,16 @@
+import { bench, describe } from 'vitest';
+import { rangeRight as rangeRightToolkit_ } from 'es-toolkit';
+import { rangeRight as rangeRightLodash_ } from 'lodash';
+
+const rangeRightToolkit = rangeRightToolkit_;
+const rangeRightLodash = rangeRightLodash_;
+
+describe('rangeRight', () => {
+  bench('es-toolkit/rangeRight', () => {
+    rangeRightToolkit(0, 100, 1);
+  });
+
+  bench('lodash/rangeRight', () => {
+    rangeRightLodash(0, 100, 1);
+  });
+});

docs/ja/reference/math/rangeRight.md

@@ -0,0 +1,42 @@
+# rangeRight
+
+`end`から始まり`start`の前で終わる数値の配列を返します。連続する数値は`step`だけ離れています。
+
+`step`のデフォルト値は1で、0にはできません。
+
+## インターフェース
+
+```typescript
+function rangeRight(end: number): number[];
+function rangeRight(start: number, end: number): number[];
+function rangeRight(start: number, end: number, step: number): number[];
+```
+
+### パラメータ
+
+- `start` (`number`): 開始する数値。配列はこの数値を含みます。
+- `end` (`number`): 終了する数値。配列はこの数値を含みません。
+- `step` (`number`): 配列内の連続する数値の差。デフォルト値は`1`です。
+
+### 戻り値
+
+- (`number[]`): `end`から始まり`start`の前で終わる、連続する数値が`step`だけ離れている配列。
+
+## 例
+
+```typescript
+// [3, 2, 1, 0] を返します
+rangeRight(4);
+
+// [15, 10, 5, 0] を返します
+rangeRight(0, 20, 5);
+
+// [20, 15, 10, 5, 0] を返します
+rangeRight(0, 21, 5);
+
+// [-3, -2, -1, 0] を返します
+rangeRight(0, -4, -1);
+
+// エラーを投げます: ステップ値は0以外の整数でなければなりません。
+rangeRight(1, 4, 0);
+```

docs/ko/reference/math/rangeRight.md

@@ -0,0 +1,42 @@
+# rangeRight
+
+`end`에서 시작해서 `start` 전에 끝나는 숫자의 배열을 반환해요. 연속한 숫자는 `step` 만큼 차이가 나요.
+
+`step`이 기본값은 1이고, 0일 수 없어요.
+
+## 인터페이스
+
+```typescript
+function rangeRight(end: number): number[];
+function rangeRight(start: number, end: number): number[];
+function rangeRight(start: number, end: number, step: number): number[];
+```
+
+### 파라미터
+
+- `start` (`number`): 시작할 숫자. 배열은 이 숫자를 포함해요.
+- `end` (`number`): 끝날 숫자. 배열은 이 숫자를 포함하지 않아요.
+- `step` (`number`): 배열에서 연속한 숫자의 차이. 기본값은 `1`이에요.
+
+### 반환 값
+
+- (`number[]`): `end`에서 시작해서 `start` 전에 끝나는, 연속한 숫자가 `step` 만큼 차이나는 배열.
+
+## 예시
+
+```typescript
+// Returns [3, 2, 1, 0]
+rangeRight(4);
+
+// Returns [15, 10, 5, 0]
+rangeRight(0, 20, 5);
+
+// Returns [20, 15, 10, 5, 0]
+rangeRight(0, 21, 5);
+
+// Returns [-3, -2, -1, 0]
+rangeRight(0, -4, -1);
+
+// Throws an error: The step value must be a non-zero integer.
+rangeRight(1, 4, 0);
+```

docs/reference/math/rangeRight.md

@@ -0,0 +1,42 @@
+# rangeRight
+
+Returns an array of numbers from `end` to `start`, decrementing by `step`.
+
+If `step` is not provided, it defaults to `1`. Note that `step` must be a non-zero integer.
+
+## Signature
+
+```typescript
+function rangeRight(end: number): number[];
+function rangeRight(start: number, end: number): number[];
+function rangeRight(start: number, end: number, step: number): number[];
+```
+
+### Parameters
+
+- `start` (`number`): The starting number of the range (inclusive).
+- `end` (`number`): The end number of the range (exclusive).
+- `step` (`number`): The step value for the range. (default: `1`)
+
+### Returns
+
+- (`number[]`): An array of numbers from `end` to `start` with the specified `step`.
+
+## Examples
+
+```typescript
+// Returns [3, 2, 1, 0]
+rangeRight(4);
+
+// Returns [15, 10, 5, 0]
+rangeRight(0, 20, 5);
+
+// Returns [20, 15, 10, 5, 0]
+rangeRight(0, 21, 5);
+
+// Returns [-3, -2, -1, 0]
+rangeRight(0, -4, -1);
+
+// Throws an error: The step value must be a non-zero integer.
+rangeRight(1, 4, 0);
+```

docs/zh_hans/reference/math/rangeRight.md

@@ -0,0 +1,42 @@
+# rangeRight
+
+返回一个从 `end` 到 `start` 的数字数组，步长为 `step`。
+
+如果未提供 `step` 参数，则默认为 `1`。注意，`step` 必须是一个非零整数。
+
+## 签名
+
+```typescript
+function rangeRight(end: number): number[];
+function rangeRight(start: number, end: number): number[];
+function rangeRight(start: number, end: number, step: number): number[];
+```
+
+### 参数
+
+- `start` (`number`): 数字范围的起始值（包含）。
+- `end` (`number`): 数字范围的结束值（不包含）。
+- `step` (`number`): 数字范围的步长值（默认为 `1`）。
+
+### 返回值
+
+- (`number[]`): 从 `end` 到 `start` 的数字数组，使用指定的 `step`。
+
+## 示例
+
+```typescript
+// 返回 [3, 2, 1, 0]
+rangeRight(4);
+
+// 返回 [15, 10, 5, 0]
+rangeRight(0, 20, 5);
+
+// 返回 [20, 15, 10, 5, 0]
+rangeRight(0, 21, 5);
+
+// 返回 [-3, -2, -1, 0]
+rangeRight(0, -4, -1);
+
+// 抛出错误：步长值必须是非零整数。
+rangeRight(1, 4, 0);
+```

src/math/index.ts

@@ -8,3 +8,4 @@ export { round } from './round.ts';
 export { sum } from './sum.ts';
 export { sumBy } from './sumBy.ts';
 export { range } from './range.ts';
+export { rangeRight } from './rangeRight.ts';

src/math/rangeRight.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { rangeRight } from './rangeRight';
+
+describe('rangeRight', () => {
+  it('returns 3, 2, 1, 0 for rangeRight 0 to 4', () => {
+    expect(rangeRight(4)).toEqual([3, 2, 1, 0]);
+    expect(rangeRight(0, 4)).toEqual([3, 2, 1, 0]);
+  });
+
+  it('returns an empty array for rangeRight 0 to -4', () => {
+    expect(rangeRight(-4)).toEqual([]);
+    expect(rangeRight(0, -4)).toEqual([]);
+  });
+
+  it('can have positive step', () => {
+    expect(rangeRight(0, 20, 5)).toEqual([15, 10, 5, 0]);
+  });
+
+  it('returns an empty array when the step is negative', () => {
+    expect(rangeRight(0, 4, -1)).toEqual([]);
+  });
+
+  it('throws an error when step is zero', () => {
+    expect(() => rangeRight(1, 4, 0)).toThrowErrorMatchingInlineSnapshot(
+      `[Error: The step value must be a non-zero integer.]`
+    );
+  });
+
+  it('returns an empty array when for rangeRight 0 to 0', () => {
+    expect(rangeRight(0)).toEqual([]);
+  });
+});

src/math/rangeRight.ts

@@ -0,0 +1,79 @@
+/**
+ * Returns an array of numbers from `end` (exclusive) to `0` (inclusive), decrementing by `1`.
+ *
+ * @param {number} end - The end number of the range (exclusive).
+ * @returns {number[]} An array of numbers from `end` (exclusive) to `0` (inclusive) with a step of `1`.
+ *
+ * @example
+ * // Returns [3, 2, 1, 0]
+ * rangeRight(4);
+ */
+export function rangeRight(end: number): number[];
+
+/**
+ * Returns an array of numbers from `end` (exclusive) to `start` (inclusive), decrementing by `1`.
+ *
+ * @param {number} start - The starting number of the range (inclusive).
+ * @param {number} end - The end number of the range (exclusive).
+ * @returns {number[]} An array of numbers from `end` (exclusive) to `start` (inclusive) with a step of `1`.
+ *
+ * @example
+ * // Returns [3, 2, 1]
+ * rangeRight(1, 4);
+ */
+export function rangeRight(start: number, end: number): number[];
+
+/**
+ * Returns an array of numbers from `end` (exclusive) to `start` (inclusive), decrementing by `step`.
+ *
+ * @param {number} start - The starting number of the range (inclusive).
+ * @param {number} end - The end number of the range (exclusive).
+ * @param {number} step - The step value for the range.
+ * @returns {number[]} An array of numbers from `end` (exclusive) to `start` (inclusive) with the specified `step`.
+ *
+ * @example
+ * // Returns [15, 10, 5, 0]
+ * rangeRight(0, 20, 5);
+ */
+export function rangeRight(start: number, end: number, step: number): number[];
+
+/**
+ * Returns an array of numbers from `end` (exclusive) to `start` (inclusive), decrementing by `step`.
+ *
+ * @param {number} start - The starting number of the range (inclusive).
+ * @param {number} end - The end number of the range (exclusive).
+ * @param {number} step - The step value for the range.
+ * @returns {number[]} An array of numbers from `end` (exclusive) to `start` (inclusive) with the specified `step`.
+ * @throws {Error} Throws an error if the step value is not a non-zero integer.
+ *
+ * @example
+ * // Returns [3, 2, 1, 0]
+ * rangeRight(4);
+ *
+ * @example
+ * // Returns [-3, -2, -1, 0]
+ * rangeRight(0, -4, -1);
+ */
+export function rangeRight(start: number, end?: number, step?: number): number[] {
+  if (end == null) {
+    end = start;
+    start = 0;
+  }
+
+  if (step == null) {
+    step = 1;
+  }
+
+  if (!Number.isInteger(step) || step === 0) {
+    throw new Error(`The step value must be a non-zero integer.`);
+  }
+
+  const length = Math.max(Math.ceil((end - start) / step), 0);
+  const result = new Array(length);
+
+  for (let i = 0; i < length; i++) {
+    result[i] = start + (length - i - 1) * step;
+  }
+
+  return result;
+}