0
# Number Operations
1

2
Precise arithmetic operations and number formatting utilities. Solves JavaScript's floating-point precision issues and provides advanced number formatting capabilities. Essential for financial calculations, scientific computing, and user interface number display.
3

4
## Capabilities
5

6
### Precise Arithmetic
7

8
High-precision arithmetic operations that avoid JavaScript floating-point issues.
9

10
```javascript { .api }
11
/**
12
 * Precise addition avoiding floating-point errors
13
 * @param num1 - First number
14
 * @param num2 - Second number
15
 * @returns Sum with correct precision
16
 */
17
function add(num1: number, num2: number): number;
18

19
/**
20
 * Precise subtraction avoiding floating-point errors
21
 * @param num1 - First number (minuend)
22
 * @param num2 - Second number (subtrahend)
23
 * @returns Difference with correct precision
24
 */
25
function subtract(num1: number, num2: number): number;
26

27
/**
28
 * Precise multiplication avoiding floating-point errors
29
 * @param num1 - First number
30
 * @param num2 - Second number
31
 * @returns Product with correct precision
32
 */
33
function multiply(num1: number, num2: number): number;
34

35
/**
36
 * Precise division avoiding floating-point errors
37
 * @param num1 - Dividend
38
 * @param num2 - Divisor
39
 * @returns Quotient with correct precision
40
 */
41
function divide(num1: number, num2: number): number;
42
```
43

44
### Rounding & Precision
45

46
Advanced rounding functions with customizable precision.
47

48
```javascript { .api }
49
/**
50
 * Round number to specified decimal places
51
 * @param num - Number to round
52
 * @param digits - Number of decimal places (default: 0)
53
 * @returns Rounded number
54
 */
55
function round(num: number, digits?: number): number;
56

57
/**
58
 * Ceiling (round up) to specified decimal places
59
 * @param num - Number to round up
60
 * @param digits - Number of decimal places (default: 0)
61
 * @returns Rounded up number
62
 */
63
function ceil(num: number, digits?: number): number;
64

65
/**
66
 * Floor (round down) to specified decimal places
67
 * @param num - Number to round down
68
 * @param digits - Number of decimal places (default: 0)
69
 * @returns Rounded down number
70
 */
71
function floor(num: number, digits?: number): number;
72

73
/**
74
 * Format number to fixed decimal places
75
 * @param num - Number, string, or null to format
76
 * @param digits - Number of decimal places (optional)
77
 * @returns Formatted number string
78
 */
79
function toFixed(num: number | string | null, digits?: number): string;
80
```
81

82
### Number Conversion
83

84
Type conversion utilities for numbers and numeric strings.
85

86
```javascript { .api }
87
/**
88
 * Convert value to integer
89
 * @param num - Value to convert
90
 * @returns Integer value or NaN if conversion fails
91
 */
92
function toInteger(num: any): number;
93

94
/**
95
 * Convert value to number
96
 * @param num - Value to convert
97
 * @returns Number value or NaN if conversion fails
98
 */
99
function toNumber(num: any): number;
100

101
/**
102
 * Convert number to string representation
103
 * @param num - Number to convert
104
 * @returns String representation of number
105
 */
106
function toNumberString(num: number): string;
107
```
108

109
### Number Formatting
110

111
Advanced number formatting with thousand separators and custom options.
112

113
```javascript { .api }
114
/**
115
 * Add thousand separators to number with comprehensive formatting options
116
 * @param num - Number or string to format
117
 * @param options - Formatting options
118
 * @returns Formatted number string with separators
119
 */
120
function commafy(num: number | string, options?: CommafyOptions): string;
121

122
interface CommafyOptions {
123
  /** Number of digits in each group (default: 3) */
124
  spaceNumber?: number;
125
  /** Separator character (default: ',') */
126
  separator?: string;
127
  /** Number of decimal places to display (default: null) */
128
  digits?: number;
129
  /** Whether to round the number (default: true) */
130
  round?: boolean;
131
  /** Whether to round up (ceil) */
132
  ceil?: boolean;
133
  /** Whether to round down (floor) */
134
  floor?: boolean;
135
}
136
```
137

138
### Aggregate Operations
139

140
Functions for calculating aggregate values from arrays of numbers.
141

142
```javascript { .api }
143
/**
144
 * Calculate sum of array values
145
 * @param array - Array of numbers or objects
146
 * @param iterate - Optional function to extract numeric values
147
 * @param context - Optional context for iterator
148
 * @returns Sum of all values
149
 */
150
function sum<T, C = any>(
151
  array: T[], 
152
  iterate?: (this: C, item: T, index: number, array: T[]) => number, 
153
  context?: C
154
): number;
155

156
/**
157
 * Calculate mean (average) of array values
158
 * @param array - Array of numbers or objects
159
 * @param iterate - Optional function to extract numeric values
160
 * @param context - Optional context for iterator
161
 * @returns Mean of all values
162
 */
163
function mean<T, C = any>(
164
  array: T[], 
165
  iterate?: (this: C, item: T, index: number, array: T[]) => number, 
166
  context?: C
167
): number;
168
```
169

170
### Min/Max Operations
171

172
Functions for finding minimum and maximum values.
173

174
```javascript { .api }
175
/**
176
 * Find minimum value in array
177
 * @param array - Array of numbers or objects
178
 * @param iterate - Optional function to extract comparable values
179
 * @returns Minimum value or undefined for empty array
180
 */
181
function min<T>(array: T[], iterate?: (item: T) => any): T | undefined;
182

183
/**
184
 * Find maximum value in array
185
 * @param array - Array of numbers or objects
186
 * @param iterate - Optional function to extract comparable values
187
 * @returns Maximum value or undefined for empty array
188
 */
189
function max<T>(array: T[], iterate?: (item: T) => any): T | undefined;
190
```
191

192
### Random Numbers
193

194
Utility for generating random numbers within specified ranges.
195

196
```javascript { .api }
197
/**
198
 * Generate random number within range
199
 * @param min - Minimum value (inclusive)
200
 * @param max - Maximum value (inclusive)
201
 * @returns Random number between min and max
202
 */
203
function random(min: number, max: number): number;
204

205
/**
206
 * Generate random number from 0 to max
207
 * @param max - Maximum value (inclusive)
208
 * @returns Random number between 0 and max
209
 */
210
function random(max: number): number;
211

212
/**
213
 * Generate random number from 0 to 1
214
 * @returns Random number between 0 and 1
215
 */
216
function random(): number;
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
import { 
223
  add, subtract, multiply, divide, round, commafy, 
224
  sum, mean, min, max, random, toFixed 
225
} from 'xe-utils';
226

227
// Precise arithmetic (solves 0.1 + 0.2 = 0.30000000000000004)
228
console.log(add(0.1, 0.2)); // 0.3 (exact)
229
console.log(subtract(1.5, 1.2)); // 0.3 (exact)
230
console.log(multiply(0.3, 3)); // 0.9 (exact)
231
console.log(divide(0.9, 3)); // 0.3 (exact)
232

233
// Rounding with precision
234
console.log(round(3.14159, 2)); // 3.14
235
console.log(round(3.14159, -1)); // 0 (round to nearest 10)
236

237
// Number formatting
238
console.log(commafy(1234567.89)); // '1,234,567.89'
239
console.log(commafy(1234567.89, { separator: ' ', fixed: 2 })); // '1 234 567.89'
240

241
// Aggregate calculations
242
const scores = [85, 92, 78, 96, 89];
243
console.log(sum(scores)); // 440
244
console.log(mean(scores)); // 88
245

246
const products = [
247
  { name: 'A', price: 10.99 },
248
  { name: 'B', price: 25.50 },
249
  { name: 'C', price: 8.75 }
250
];
251

252
const totalPrice = sum(products, item => item.price); // 45.24
253
const avgPrice = mean(products, item => item.price); // 15.08
254

255
// Min/Max operations
256
console.log(min(scores)); // 78
257
console.log(max(scores)); // 96
258

259
const cheapest = min(products, item => item.price); // { name: 'C', price: 8.75 }
260
const mostExpensive = max(products, item => item.price); // { name: 'B', price: 25.50 }
261

262
// Random numbers
263
console.log(random()); // Random between 0-1
264
console.log(random(10)); // Random between 0-10
265
console.log(random(5, 15)); // Random between 5-15
266

267
// Financial calculations example
268
function calculateTax(amount, rate) {
269
  const tax = multiply(amount, divide(rate, 100));
270
  const total = add(amount, tax);
271
  
272
  return {
273
    subtotal: commafy(amount, { fixed: 2 }),
274
    tax: commafy(tax, { fixed: 2 }),
275
    total: commafy(total, { fixed: 2 })
276
  };
277
}
278

279
console.log(calculateTax(99.99, 8.25));
280
// { subtotal: '99.99', tax: '8.25', total: '108.24' }
281
```