npm-lodash

1
# Mathematical Operations
2

3
Mathematical utilities including basic arithmetic, rounding, and statistical operations. These methods provide safe and consistent mathematical computations.
4

5
## Capabilities
6

7
### Basic Arithmetic
8

9
Fundamental arithmetic operations.
10

11
```javascript { .api }
12
/**
13
 * Adds two numbers.
14
 * 
15
 * @param {number} augend The first number in an addition
16
 * @param {number} addend The second number in an addition
17
 * @returns {number} Returns the sum
18
 */
19
function add(augend: number, addend: number): number;
20

21
/**
22
 * Subtracts two numbers.
23
 * 
24
 * @param {number} minuend The first number in a subtraction
25
 * @param {number} subtrahend The second number in a subtraction
26
 * @returns {number} Returns the difference
27
 */
28
function subtract(minuend: number, subtrahend: number): number;
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
import { add, subtract } from "lodash";
35

36
add(6, 4); // 10
37
add(1.2, 0.8); // 2
38

39
subtract(6, 4); // 2
40
subtract(1.2, 0.8); // 0.4
41
```
42

43
### Rounding Operations
44

45
Round numbers to specified precision.
46

47
```javascript { .api }
48
/**
49
 * Computes `number` rounded up to `precision`.
50
 * 
51
 * @param {number} number The number to round up
52
 * @param {number} [precision=0] The precision to round up to
53
 * @returns {number} Returns the rounded up number
54
 */
55
function ceil(number: number, precision?: number): number;
56

57
/**
58
 * Computes `number` rounded down to `precision`.
59
 * 
60
 * @param {number} number The number to round down
61
 * @param {number} [precision=0] The precision to round down to
62
 * @returns {number} Returns the rounded down number
63
 */
64
function floor(number: number, precision?: number): number;
65

66
/**
67
 * Computes `number` rounded to `precision`.
68
 * 
69
 * @param {number} number The number to round
70
 * @param {number} [precision=0] The precision to round to
71
 * @returns {number} Returns the rounded number
72
 */
73
function round(number: number, precision?: number): number;
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
import { ceil, floor, round } from "lodash";
80

81
ceil(4.006); // 5
82
ceil(6.004, 2); // 6.01
83
ceil(6040, -2); // 6100
84

85
floor(4.006); // 4
86
floor(0.046, 2); // 0.04
87
floor(4060, -2); // 4000
88

89
round(4.006); // 4
90
round(4.006, 2); // 4.01
91
round(4060, -2); // 4100
92
```
93

94
### Statistical Operations
95

96
Find maximum and minimum values.
97

98
```javascript { .api }
99
/**
100
 * Computes the maximum value of `array`. If `array` is empty or falsey,
101
 * `undefined` is returned.
102
 * 
103
 * @param {Array} array The array to iterate over
104
 * @returns {*} Returns the maximum value
105
 */
106
function max(array: Array): any;
107

108
/**
109
 * This method is like `max` except that it accepts `iteratee` which is
110
 * invoked for each element in `array` to generate the criterion by which
111
 * the value is ranked.
112
 * 
113
 * @param {Array} array The array to iterate over
114
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
115
 * @returns {*} Returns the maximum value
116
 */
117
function maxBy(array: Array, iteratee?: Function|Object|string): any;
118

119
/**
120
 * Computes the minimum value of `array`. If `array` is empty or falsey,
121
 * `undefined` is returned.
122
 * 
123
 * @param {Array} array The array to iterate over
124
 * @returns {*} Returns the minimum value
125
 */
126
function min(array: Array): any;
127

128
/**
129
 * This method is like `min` except that it accepts `iteratee` which is
130
 * invoked for each element in `array` to generate the criterion by which
131
 * the value is ranked.
132
 * 
133
 * @param {Array} array The array to iterate over
134
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
135
 * @returns {*} Returns the minimum value
136
 */
137
function minBy(array: Array, iteratee?: Function|Object|string): any;
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
import { max, maxBy, min, minBy } from "lodash";
144

145
max([4, 2, 8, 6]); // 8
146
max([]); // undefined
147

148
const objects = [{ 'n': 1 }, { 'n': 2 }];
149
maxBy(objects, 'n'); // { 'n': 2 }
150
maxBy(objects, obj => obj.n); // { 'n': 2 }
151

152
min([4, 2, 8, 6]); // 2
153
min([]); // undefined
154

155
minBy(objects, 'n'); // { 'n': 1 }
156
minBy(objects, obj => obj.n); // { 'n': 1 }
157
```
158

159
### Summation Operations
160

161
Calculate sums and means.
162

163
```javascript { .api }
164
/**
165
 * Computes the sum of the values in `array`.
166
 * 
167
 * @param {Array} array The array to iterate over
168
 * @returns {number} Returns the sum
169
 */
170
function sum(array: Array): number;
171

172
/**
173
 * This method is like `sum` except that it accepts `iteratee` which is
174
 * invoked for each element in `array` to generate the value to be summed.
175
 * 
176
 * @param {Array} array The array to iterate over
177
 * @param {Function|Object|string} [iteratee] The iteratee invoked per element
178
 * @returns {number} Returns the sum
179
 */
180
function sumBy(array: Array, iteratee?: Function|Object|string): number;
181

182
/**
183
 * Computes the mean of the values in `array`.
184
 * 
185
 * @param {Array} array The array to iterate over
186
 * @returns {number} Returns the mean
187
 */
188
function mean(array: Array): number;
189
```
190

191
**Usage Examples:**
192

193
```javascript
194
import { sum, sumBy, mean } from "lodash";
195

196
sum([4, 2, 8, 6]); // 20
197

198
const objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }];
199
sumBy(objects, 'n'); // 20
200
sumBy(objects, obj => obj.n); // 20
201

202
mean([4, 2, 8, 6]); // 5
203
mean([]); // NaN
204
```
205

206
### Number Constraints
207

208
Constrain numbers within bounds.
209

210
```javascript { .api }
211
/**
212
 * Clamps `number` within the inclusive `lower` and `upper` bounds.
213
 * 
214
 * @param {number} number The number to clamp
215
 * @param {number} [lower] The lower bound
216
 * @param {number} upper The upper bound
217
 * @returns {number} Returns the clamped number
218
 */
219
function clamp(number: number, lower?: number, upper: number): number;
220
```
221

222
**Usage Examples:**
223

224
```javascript
225
import { clamp } from "lodash";
226

227
clamp(-10, -5, 5); // -5
228
clamp(10, -5, 5); // 5
229
clamp(3, -5, 5); // 3
230

231
// With only upper bound
232
clamp(10, 5); // 5
233
clamp(-10, 5); // -10
234
```
235

236
### Range Checking
237

238
Check if numbers are within ranges.
239

240
```javascript { .api }
241
/**
242
 * Checks if `n` is between `start` and up to, but not including, `end`. If
243
 * `end` is not specified, it's set to `start` with `start` then set to `0`.
244
 * If `start` is greater than `end` the params are swapped to support
245
 * negative ranges.
246
 * 
247
 * @param {number} number The number to check
248
 * @param {number} [start=0] The start of the range
249
 * @param {number} end The end of the range
250
 * @returns {boolean} Returns `true` if `number` is in the range, else `false`
251
 */
252
function inRange(number: number, start?: number, end: number): boolean;
253
```
254

255
**Usage Examples:**
256

257
```javascript
258
import { inRange } from "lodash";
259

260
inRange(3, 2, 4); // true
261
inRange(4, 8); // true (0 to 8)
262
inRange(4, 2); // false (0 to 2)
263
inRange(2, 2); // false (0 to 2, not including 2)
264
inRange(1.2, 2); // true (0 to 2)
265
inRange(5.2, 4); // false (0 to 4)
266
inRange(-3, -2, -6); // true (range is -6 to -2)
267
```
268

269
### Random Number Generation
270

271
Generate random numbers within specified ranges.
272

273
```javascript { .api }
274
/**
275
 * Produces a random number between the inclusive `lower` and `upper` bounds.
276
 * If only one argument is provided a number between `0` and the given number
277
 * is returned. If `floating` is `true`, or either `lower` or `upper` are
278
 * floats, a floating-point number is returned instead of an integer.
279
 * 
280
 * @param {number} [lower=0] The lower bound
281
 * @param {number} [upper=1] The upper bound
282
 * @param {boolean} [floating] Specify returning a floating-point number
283
 * @returns {number} Returns the random number
284
 */
285
function random(lower?: number, upper?: number, floating?: boolean): number;
286
```
287

288
**Usage Examples:**
289

290
```javascript
291
import { random } from "lodash";
292

293
random(0, 5); // an integer between 0 and 5
294
random(5); // an integer between 0 and 5
295
random(5, true); // a floating-point number between 0 and 5
296
random(1.2, 5.2); // a floating-point number between 1.2 and 5.2
297

298
// Examples of possible outputs:
299
random(0, 5); // 3
300
random(1.2, 5.2); // 3.7429
301
random(5, true); // 2.718
302
```