From 494519b2ceb885a832a40d7760d7f66bfa58ec1e Mon Sep 17 00:00:00 2001
From: jgjgill <79239852+jgjgill@users.noreply.github.com>
Date: Fri, 5 Jul 2024 10:08:25 +0900
Subject: [PATCH] feat: Add inRange (#124)

---
 benchmarks/inRange.bench.ts       | 13 +++++++++++++
 docs/.vitepress/en.mts            |  1 +
 docs/.vitepress/ko.mts            |  1 +
 docs/ko/reference/math/inRange.md | 32 +++++++++++++++++++++++++++++++
 docs/reference/math/inRange.md    | 32 +++++++++++++++++++++++++++++++
 src/math/inRange.spec.ts          | 30 +++++++++++++++++++++++++++++
 src/math/inRange.ts               | 28 +++++++++++++++++++++++++++
 src/math/index.ts                 |  1 +
 8 files changed, 138 insertions(+)
 create mode 100644 benchmarks/inRange.bench.ts
 create mode 100644 docs/ko/reference/math/inRange.md
 create mode 100644 docs/reference/math/inRange.md
 create mode 100644 src/math/inRange.spec.ts
 create mode 100644 src/math/inRange.ts

diff --git a/benchmarks/inRange.bench.ts b/benchmarks/inRange.bench.ts
new file mode 100644
index 00000000..fc5672e9
--- /dev/null
+++ b/benchmarks/inRange.bench.ts
@@ -0,0 +1,13 @@
+import { bench, describe } from 'vitest';
+import { inRange as inRangeToolkit } from 'es-toolkit';
+import { inRange as inRangeLodash } from 'lodash';
+
+describe('inRange', () => {
+  bench('es-toolkit/inRange', () => {
+    inRangeToolkit(3, 5);
+  });
+
+  bench('lodash/inRange', () => {
+    inRangeLodash(3, 5);
+  });
+});
diff --git a/docs/.vitepress/en.mts b/docs/.vitepress/en.mts
index 9b38efe2..d3d060d1 100644
--- a/docs/.vitepress/en.mts
+++ b/docs/.vitepress/en.mts
@@ -103,6 +103,7 @@ function sidebar(): DefaultTheme.Sidebar {
           text: 'Math Utilities',
           items: [
             { text: 'clamp', link: '/reference/math/clamp' },
+            { text: 'inRange', link: '/reference/math/inRange' },
             { text: 'mean', link: '/reference/math/mean' },
             { text: 'meanBy', link: '/reference/math/meanBy' },
             { text: 'random', link: '/reference/math/random' },
diff --git a/docs/.vitepress/ko.mts b/docs/.vitepress/ko.mts
index 3b6693a9..7036b7ed 100644
--- a/docs/.vitepress/ko.mts
+++ b/docs/.vitepress/ko.mts
@@ -102,6 +102,7 @@ function sidebar(): DefaultTheme.Sidebar {
           text: '숫자',
           items: [
             { text: 'clamp', link: '/ko/reference/math/clamp' },
+            { text: 'inRange', link: '/ko/reference/math/inRange' },
             { text: 'mean', link: '/ko/reference/math/mean' },
             { text: 'meanBy', link: '/ko/reference/math/meanBy' },
             { text: 'random', link: '/ko/reference/math/random' },
diff --git a/docs/ko/reference/math/inRange.md b/docs/ko/reference/math/inRange.md
new file mode 100644
index 00000000..0383459f
--- /dev/null
+++ b/docs/ko/reference/math/inRange.md
@@ -0,0 +1,32 @@
+# inRange
+
+값이 지정된 범위 내에 있는지 확인해요.
+
+## 인터페이스
+
+```typescript
+export function inRange(value: number, maximum: number): boolean;
+export function inRange(value: number, minimum: number, maximum: number): boolean;
+```
+
+### 파라미터
+
+- `value` (`number`): 확인할 값이에요.
+- `minimum` (`number`): 범위의 최솟값(포함)이에요.
+- `maximum` (`number`): 범위의 최댓값(미포함)이에요.
+
+### 반환 값
+
+(`boolean`): 값이 지정된 범위 내에 있으면 `true`, 그렇지 않으면 `false`가 돼요.
+
+### 에러
+
+`minimum`이 `maximum`보다 크거나 같으면 에러를 던져요.
+
+## 예시
+
+```typescript
+const result1 = inRange(3, 5); // result1은 true가 돼요.
+const result2 = inRange(1, 2, 5); // result2은 false가 돼요.
+const result3 = inRange(1, 5, 2); // 최솟값이 최댓값보다 크거나 같으면 에러가 발생해요.
+```
diff --git a/docs/reference/math/inRange.md b/docs/reference/math/inRange.md
new file mode 100644
index 00000000..bfbd12bf
--- /dev/null
+++ b/docs/reference/math/inRange.md
@@ -0,0 +1,32 @@
+# inRange
+
+Checks if the value is within a specified range.
+
+## Signature
+
+```typescript
+export function inRange(value: number, maximum: number): boolean;
+export function inRange(value: number, minimum: number, maximum: number): boolean;
+```
+
+### Parameters
+
+- `value` (`number`): The value to check.
+- `minimum` (`number`): The lower bound of the range (inclusive).
+- `maximum` (`number`): The upper bound of the range (exclusive).
+
+### Returns
+
+(`boolean`): `true` if the value is within the specified range, otherwise `false`.
+
+### Throws
+
+Throws an error if the `minimum` is greater or equal than the `maximum`.
+
+## Examples
+
+```typescript
+const result1 = inRange(3, 5); // result1 will be true.
+const result2 = inRange(1, 2, 5); // result2 will be false.
+const result3 = inRange(1, 5, 2); // If the minimum is greater or equal than the maximum, an error is thrown.
+```
diff --git a/src/math/inRange.spec.ts b/src/math/inRange.spec.ts
new file mode 100644
index 00000000..3a4446d7
--- /dev/null
+++ b/src/math/inRange.spec.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { inRange } from './inRange';
+
+describe('inRange', () => {
+  it('returns true for values within the range when two parameters are provided', () => {
+    expect(inRange(3, 5)).toBe(true);
+    expect(inRange(3.2, 5.3)).toBe(true);
+  });
+
+  it('returns false for values outside the range when two parameters are provided', () => {
+    expect(inRange(3, 2)).toBe(false);
+    expect(inRange(5.3, 3.2)).toBe(false);
+  });
+
+  it('returns true for values within the range when three parameters are provided', () => {
+    expect(inRange(1, 0, 5)).toBe(true);
+    expect(inRange(-3, -5, -1)).toBe(true);
+  });
+
+  it('returns false for values outside the range when three parameters are provided', () => {
+    expect(inRange(1, 2, 5)).toBe(false);
+    expect(inRange(-5, -3, -1)).toBe(false);
+  });
+
+  it('throws an error if the minimum is greater or equal than the maximum', () => {
+    expect(() => inRange(1, 5, 2)).toThrowErrorMatchingInlineSnapshot(
+      `[Error: The maximum value must be greater than the minimum value.]`
+    );
+  });
+});
diff --git a/src/math/inRange.ts b/src/math/inRange.ts
new file mode 100644
index 00000000..71c23ef7
--- /dev/null
+++ b/src/math/inRange.ts
@@ -0,0 +1,28 @@
+export function inRange(value: number, maximum: number): boolean;
+export function inRange(value: number, minimum: number, maximum: number): boolean;
+/**
+ * Checks if the value is within a specified range.
+ *
+ * @param {number} value The value to check.
+ * @param {number} minimum The lower bound of the range (inclusive).
+ * @param {number} maximum The upper bound of the range (exclusive).
+ * @returns {boolean} `true` if the value is within the specified range, otherwise `false`.
+ * @throws {Error} Throws an error if the `minimum` is greater or equal than the `maximum`.
+ *
+ * @example
+ * const result1 = inRange(3, 5); // result1 will be true.
+ * const result2 = inRange(1, 2, 5); // result2 will be false.
+ * const result3 = inRange(1, 5, 2); // If the minimum is greater or equal than the maximum, an error is thrown.
+ */
+export function inRange(value: number, minimum: number, maximum?: number): boolean {
+  if (maximum == null) {
+    maximum = minimum;
+    minimum = 0;
+  }
+
+  if (minimum >= maximum) {
+    throw new Error('The maximum value must be greater than the minimum value.');
+  }
+
+  return minimum <= value && value < maximum;
+}
diff --git a/src/math/index.ts b/src/math/index.ts
index 80943cdb..2fe40c10 100644
--- a/src/math/index.ts
+++ b/src/math/index.ts
@@ -1,4 +1,5 @@
 export { clamp } from './clamp.ts';
+export { inRange } from './inRange.ts';
 export { mean } from './mean.ts';
 export { meanBy } from './meanBy.ts';
 export { random } from './random.ts';