feat: Add inRange (#124)

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

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

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

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); // 최솟값이 최댓값보다 크거나 같으면 에러가 발생해요.
+```

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.
+```

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.]`
+    );
+  });
+});

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

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';