0
# Mathematical Operations
1

2
Comprehensive mathematical functions including basic arithmetic, trigonometry, logarithmic operations, and number property testing. The Number module provides 29 functions covering all essential mathematical operations.
3

4
## Capabilities
5

6
### Basic Mathematical Operations
7

8
Core arithmetic and comparison functions.
9

10
```javascript { .api }
11
/**
12
 * Returns larger of two numbers
13
 * @param {number} a - First number
14
 * @param {number} b - Second number
15
 * @returns {number} Maximum of a and b
16
 */
17
function max(a, b);
18

19
/**
20
 * Returns smaller of two numbers
21
 * @param {number} a - First number
22
 * @param {number} b - Second number
23
 * @returns {number} Minimum of a and b
24
 */
25
function min(a, b);
26

27
/**
28
 * Negates number
29
 * @param {number} n - Number to negate
30
 * @returns {number} Negative of n
31
 */
32
function negate(n);
33

34
/**
35
 * Absolute value (Math.abs)
36
 * @param {number} n - Number to get absolute value of
37
 * @returns {number} Absolute value of n
38
 */
39
function abs(n);
40

41
/**
42
 * Sign function (-1, 0, or 1)
43
 * @param {number} n - Number to get sign of
44
 * @returns {number} -1 if negative, 0 if zero, 1 if positive
45
 */
46
function signum(n);
47
```
48

49
### Division Operations
50

51
Specialized division functions for different mathematical needs.
52

53
```javascript { .api }
54
/**
55
 * Integer division (truncates toward zero)
56
 * @param {number} a - Dividend
57
 * @param {number} b - Divisor
58
 * @returns {number} Integer quotient truncated toward zero
59
 */
60
function quot(a, b);
61

62
/**
63
 * Remainder operation (sign follows dividend)
64
 * @param {number} a - Dividend
65
 * @param {number} b - Divisor
66
 * @returns {number} Remainder of a/b
67
 */
68
function rem(a, b);
69

70
/**
71
 * Integer division (floors result)
72
 * @param {number} a - Dividend
73
 * @param {number} b - Divisor
74
 * @returns {number} Integer quotient floored
75
 */
76
function div(a, b);
77

78
/**
79
 * Modulo operation (always positive result)
80
 * @param {number} a - Dividend
81
 * @param {number} b - Divisor
82
 * @returns {number} Positive remainder of a/b
83
 */
84
function mod(a, b);
85

86
/**
87
 * Reciprocal (1/x)
88
 * @param {number} x - Number to get reciprocal of
89
 * @returns {number} 1/x
90
 */
91
function recip(x);
92
```
93

94
### Mathematical Constants
95

96
Important mathematical constants.
97

98
```javascript { .api }
99
/**
100
 * Math.PI constant (π ≈ 3.14159)
101
 * @type {number}
102
 */
103
const pi = Math.PI;
104

105
/**
106
 * Tau constant (2π ≈ 6.28318)
107
 * @type {number}
108
 */
109
const tau = 2 * Math.PI;
110
```
111

112
### Exponential and Logarithmic Functions
113

114
Power, exponential, and logarithmic operations.
115

116
```javascript { .api }
117
/**
118
 * e^x (Math.exp)
119
 * @param {number} x - Exponent
120
 * @returns {number} e raised to power x
121
 */
122
function exp(x);
123

124
/**
125
 * Square root (Math.sqrt)
126
 * @param {number} x - Number to get square root of
127
 * @returns {number} Square root of x
128
 */
129
function sqrt(x);
130

131
/**
132
 * Natural logarithm (Math.log)
133
 * @param {number} x - Number to get natural log of
134
 * @returns {number} Natural logarithm of x
135
 */
136
function ln(x);
137

138
/**
139
 * Exponentiation (Math.pow)
140
 * @param {number} base - Base number
141
 * @param {number} exponent - Exponent
142
 * @returns {number} Base raised to exponent
143
 */
144
function pow(base, exponent);
145
```
146

147
### Trigonometric Functions
148

149
Complete set of trigonometric and inverse trigonometric functions.
150

151
```javascript { .api }
152
/**
153
 * Sine (Math.sin)
154
 * @param {number} x - Angle in radians
155
 * @returns {number} Sine of x
156
 */
157
function sin(x);
158

159
/**
160
 * Tangent (Math.tan)
161
 * @param {number} x - Angle in radians
162
 * @returns {number} Tangent of x
163
 */
164
function tan(x);
165

166
/**
167
 * Cosine (Math.cos)
168
 * @param {number} x - Angle in radians
169
 * @returns {number} Cosine of x
170
 */
171
function cos(x);
172

173
/**
174
 * Arcsine (Math.asin)
175
 * @param {number} x - Value between -1 and 1
176
 * @returns {number} Arcsine of x in radians
177
 */
178
function asin(x);
179

180
/**
181
 * Arccosine (Math.acos)
182
 * @param {number} x - Value between -1 and 1
183
 * @returns {number} Arccosine of x in radians
184
 */
185
function acos(x);
186

187
/**
188
 * Arctangent (Math.atan)
189
 * @param {number} x - Any number
190
 * @returns {number} Arctangent of x in radians
191
 */
192
function atan(x);
193

194
/**
195
 * Two-argument arctangent (Math.atan2)
196
 * @param {number} y - Y coordinate
197
 * @param {number} x - X coordinate
198
 * @returns {number} Angle from x-axis to point (x,y) in radians
199
 */
200
function atan2(y, x);
201
```
202

203
### Rounding Functions
204

205
Functions for different types of number rounding.
206

207
```javascript { .api }
208
/**
209
 * Truncates to integer (removes decimal part)
210
 * @param {number} n - Number to truncate
211
 * @returns {number} Integer part of n
212
 */
213
function truncate(n);
214

215
/**
216
 * Rounds to nearest integer (Math.round)
217
 * @param {number} n - Number to round
218
 * @returns {number} Nearest integer to n
219
 */
220
function round(n);
221

222
/**
223
 * Rounds up to next integer (Math.ceil)
224
 * @param {number} n - Number to round up
225
 * @returns {number} Smallest integer ≥ n
226
 */
227
function ceiling(n);
228

229
/**
230
 * Rounds down to previous integer (Math.floor)
231
 * @param {number} n - Number to round down
232
 * @returns {number} Largest integer ≤ n
233
 */
234
function floor(n);
235
```
236

237
### Number Properties and Testing
238

239
Functions for testing number properties.
240

241
```javascript { .api }
242
/**
243
 * Checks if value is NaN
244
 * @param {*} value - Value to test
245
 * @returns {boolean} True if value is NaN
246
 */
247
function isItNaN(value);
248

249
/**
250
 * Tests if number is even
251
 * @param {number} n - Integer to test
252
 * @returns {boolean} True if n is even
253
 */
254
function even(n);
255

256
/**
257
 * Tests if number is odd
258
 * @param {number} n - Integer to test
259
 * @returns {boolean} True if n is odd
260
 */
261
function odd(n);
262

263
/**
264
 * Greatest common divisor
265
 * @param {number} a - First integer
266
 * @param {number} b - Second integer
267
 * @returns {number} Greatest common divisor of a and b
268
 */
269
function gcd(a, b);
270

271
/**
272
 * Least common multiple
273
 * @param {number} a - First integer
274
 * @param {number} b - Second integer
275
 * @returns {number} Least common multiple of a and b
276
 */
277
function lcm(a, b);
278
```
279

280
## Usage Examples
281

282
**Basic Arithmetic:**
283

284
```javascript
285
const { max, min, abs, signum } = require('prelude-ls');
286

287
const numbers = [5, -3, 8, -12, 0];
288

289
const maximum = max(5, 8);                // 8
290
const minimum = min(-3, -12);             // -12
291

292
const absolute = abs(-12);                // 12
293
const sign = signum(-5);                  // -1
294

295
// Finding max/min in arrays (with apply or reduce)
296
const arrayMax = numbers.reduce(max);     // 8
297
const arrayMin = numbers.reduce(min);     // -12
298
```
299

300
**Division Operations:**
301

302
```javascript
303
const { quot, rem, div, mod } = require('prelude-ls');
304

305
const a = 17, b = 5;
306

307
const quotient = quot(a, b);              // 3 (17 ÷ 5, truncated)
308
const remainder = rem(a, b);              // 2 (17 % 5)
309

310
const division = div(a, b);               // 3 (17 ÷ 5, floored)
311
const modulo = mod(a, b);                 // 2 (17 mod 5)
312

313
// Difference with negative numbers
314
const negA = -17, negB = 5;
315
const quotNeg = quot(negA, negB);         // -3 (truncated toward zero)
316
const divNeg = div(negA, negB);           // -4 (floored)
317
const remNeg = rem(negA, negB);           // -2 (sign follows dividend)
318
const modNeg = mod(negA, negB);           // 3 (always positive)
319
```
320

321
**Trigonometry:**
322

323
```javascript
324
const { sin, cos, tan, pi, tau } = require('prelude-ls');
325

326
// Basic trigonometric functions
327
const angle = pi / 4;                     // 45 degrees in radians
328

329
const sine = sin(angle);                  // √2/2 ≈ 0.707
330
const cosine = cos(angle);                // √2/2 ≈ 0.707
331
const tangent = tan(angle);               // 1
332

333
// Full circle calculations
334
const fullCircle = tau;                   // 2π ≈ 6.283
335
const halfCircle = pi;                    // π ≈ 3.142
336

337
// Common angles
338
const angles = [0, pi/6, pi/4, pi/3, pi/2];
339
const sines = angles.map(sin);
340
const cosines = angles.map(cos);
341
```
342

343
**Exponential and Logarithmic:**
344

345
```javascript
346
const { exp, ln, sqrt, pow } = require('prelude-ls');
347

348
const base = 2;
349
const exponent = 3;
350

351
const power = pow(base, exponent);        // 8 (2³)
352
const squareRoot = sqrt(16);              // 4
353
const naturalExp = exp(1);                // e ≈ 2.718
354
const naturalLog = ln(naturalExp);        // 1
355

356
// Compound calculations
357
const compound = exp(ln(5) * 2);          // 25 (equivalent to 5²)
358
const logBase = (base, n) => ln(n) / ln(base);
359
const log2of8 = logBase(2, 8);            // 3
360
```
361

362
**Rounding Operations:**
363

364
```javascript
365
const { round, floor, ceiling, truncate } = require('prelude-ls');
366

367
const number = 3.7;
368
const negative = -3.7;
369

370
const rounded = round(number);            // 4
371
const floored = floor(number);            // 3
372
const ceiled = ceiling(number);           // 4
373
const truncated = truncate(number);       // 3
374

375
// With negative numbers
376
const roundedNeg = round(negative);       // -4
377
const flooredNeg = floor(negative);       // -4
378
const ceiledNeg = ceiling(negative);      // -3
379
const truncatedNeg = truncate(negative);  // -3
380
```
381

382
**Number Properties:**
383

384
```javascript
385
const { even, odd, gcd, lcm, isItNaN } = require('prelude-ls');
386

387
const numbers = [12, 15, 18, 21];
388

389
const evens = numbers.filter(even);       // [12, 18]
390
const odds = numbers.filter(odd);         // [15, 21]
391

392
const greatestCommon = gcd(12, 18);       // 6
393
const leastCommon = lcm(12, 18);          // 36
394

395
// NaN checking
396
const validNumbers = [1, 2, NaN, 4].filter(n => !isItNaN(n)); // [1, 2, 4]
397
```
398

399
**Curried Mathematical Operations:**
400

401
```javascript
402
const { max, min, pow, mod } = require('prelude-ls');
403

404
// Create reusable functions
405
const atLeast = min(0);                   // Ensures non-negative
406
const atMost = max(100);                  // Caps at 100
407
const square = pow(2);                    // Square function (note: arguments flipped)
408
const isMultipleOf5 = n => mod(n, 5) === 0;
409

410
const numbers = [-5, 25, 150, 200];
411
const clamped = numbers.map(n => atMost(atLeast(n))); // [0, 25, 100, 100]
412
const multiples = numbers.filter(isMultipleOf5);     // [25, 150, 200]
413
```
414

415
**Advanced Mathematical Computations:**
416

417
```javascript
418
const { sin, cos, pow, sqrt, pi } = require('prelude-ls');
419

420
// Distance formula
421
const distance = (x1, y1, x2, y2) => 
422
  sqrt(pow(x2 - x1, 2) + pow(y2 - y1, 2));
423

424
const dist = distance(0, 0, 3, 4);        // 5
425

426
// Polar to Cartesian conversion
427
const polarToCartesian = (r, theta) => ({
428
  x: r * cos(theta),
429
  y: r * sin(theta)
430
});
431

432
const point = polarToCartesian(5, pi / 3); // {x: 2.5, y: ≈4.33}
433
```
434

435
**Statistical Calculations:**
436

437
```javascript
438
const { sqrt, pow, abs } = require('prelude-ls');
439

440
const standardDeviation = (numbers) => {
441
  const mean = numbers.reduce((a, b) => a + b) / numbers.length;
442
  const variance = numbers
443
    .map(n => pow(n - mean, 2))
444
    .reduce((a, b) => a + b) / numbers.length;
445
  return sqrt(variance);
446
};
447

448
const data = [10, 12, 23, 23, 16, 23, 21, 16];
449
const stdDev = standardDeviation(data);    // ≈5.237
450
```