0
# lodash.clamp
1

2
The lodash method `_.clamp` exported as a Node.js module. Clamps numbers within inclusive lower and upper bounds to constrain values within a specified range.
3

4
## Package Information
5

6
- **Package Name**: lodash.clamp
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.clamp`
10

11
## Core Imports
12

13
```javascript
14
const clamp = require('lodash.clamp');
15
```
16

17
For ES modules:
18

19
```javascript
20
import clamp from 'lodash.clamp';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const clamp = require('lodash.clamp');
27

28
// Clamp with lower and upper bounds
29
clamp(-10, -5, 5);
30
// => -5
31

32
clamp(10, -5, 5);
33
// => 5
34

35
clamp(3, -5, 5);
36
// => 3
37

38
// Clamp with only upper bound (lower bound becomes undefined)
39
clamp(10, 5);
40
// => 5
41

42
clamp(3, 5);
43
// => 3
44
```
45

46
## Capabilities
47

48
### Number Clamping
49

50
Constrains a number within inclusive lower and upper bounds.
51

52
```javascript { .api }
53
/**
54
 * Clamps `number` within the inclusive `lower` and `upper` bounds.
55
 *
56
 * @param {*} number The number to clamp (will be converted to number)
57
 * @param {number} [lower] The lower bound (optional)
58
 * @param {number} upper The upper bound
59
 * @returns {number} Returns the clamped number
60
 */
61
function clamp(number, lower, upper);
62
```
63

64
**Parameter Details:**
65

66
- `number` (any): The value to clamp. Will be converted to a number using internal type conversion:
67
  - Numbers: Used directly
68
  - Strings: Parsed as numbers (supports binary "0b", octal "0o", hex formats)
69
  - Symbols: Converted to NaN
70
  - Objects: Uses `valueOf()` method if available, then string conversion
71
  - Invalid values: Result in NaN, which passes through unchanged
72
- `lower` (number, optional): The lower bound. If `upper` is undefined, this becomes the upper bound and lower becomes undefined
73
- `upper` (number): The upper bound. Required parameter
74

75
**Return Value:**
76
- Returns a number clamped within the specified bounds
77
- If the input cannot be converted to a valid number, returns NaN
78
- If bounds are NaN, they are treated as 0
79

80
**Type Conversion Behavior:**
81

82
The function performs comprehensive type conversion on all parameters:
83

84
```javascript
85
// String conversion examples
86
clamp("10", "2", "8");      // => 8
87
clamp("3.5", "1", "5");     // => 3.5
88
clamp("0b1010", "0", "15"); // => 10 (binary)
89
clamp("0o17", "0", "20");   // => 15 (octal)
90

91
// Object conversion examples
92
clamp({valueOf: () => 7}, 0, 5); // => 5
93
clamp([3], 0, 10);               // => 3
94

95
// Invalid input handling
96
clamp(Symbol(), 0, 10);    // => NaN
97
clamp("invalid", 0, 10);   // => NaN
98
clamp(null, 0, 10);        // => 0
99
clamp(undefined, 0, 10);   // => NaN
100
```
101

102
**Flexible Parameter Patterns:**
103

104
```javascript
105
// Three parameters: number, lower, upper
106
clamp(15, 5, 10);    // => 10
107

108
// Two parameters: number, upper (lower becomes undefined)
109
clamp(15, 10);       // => 10
110
clamp(5, 10);        // => 5
111

112
// Edge cases with undefined bounds
113
clamp(5, undefined, 10);  // => 5
114
clamp(5, 2, undefined);   // => 5 (no upper constraint)
115
```
116

117
**Common Use Cases:**
118

119
- **Input validation**: Ensure user input stays within acceptable ranges
120
- **Slider controls**: Constrain slider values between min/max
121
- **Data normalization**: Keep values within expected bounds
122
- **Animation**: Clamp animation values to prevent overflow
123
- **Color values**: Ensure RGB values stay between 0-255
124

125
**Examples:**
126

127
```javascript
128
const clamp = require('lodash.clamp');
129

130
// User input validation
131
function setVolume(level) {
132
  return clamp(level, 0, 100); // Ensure volume is 0-100
133
}
134

135
// Percentage calculations
136
function calculatePercent(value, total) {
137
  const percent = (value / total) * 100;
138
  return clamp(percent, 0, 100); // Cap at 100%
139
}
140

141
// Animation frame clamping
142
function updateProgress(current, duration) {
143
  const progress = current / duration;
144
  return clamp(progress, 0, 1); // Keep between 0 and 1
145
}
146
```