0
# Numeric Functions
1

2
Functions for mathematical calculations, aggregations, and numeric transformations.
3

4
## Capabilities
5

6
### Aggregation Functions
7

8
#### Sum Function
9

10
Calculates the sum of numeric values in an array.
11

12
```javascript { .api }
13
/**
14
 * Sum numeric values in array
15
 * @param args - Array of numbers to sum
16
 * @returns Sum of all numeric values, undefined if input is undefined
17
 */
18
function $sum(args);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const data = { values: [1, 2, 3, 4, 5] };
25
const expr = jsonata("$sum(values)");
26
const result = await expr.evaluate(data); // 15
27

28
// With path expression
29
const orders = { orders: [{ total: 100 }, { total: 200 }, { total: 150 }] };
30
const total = await jsonata("$sum(orders.total)").evaluate(orders); // 450
31
```
32

33
#### Count Function
34

35
Returns the count of elements in an array.
36

37
```javascript { .api }
38
/**
39
 * Count elements in array
40
 * @param args - Array to count
41
 * @returns Number of elements, 0 if undefined
42
 */
43
function $count(args);
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
const data = { items: ["a", "b", "c"] };
50
const count = await jsonata("$count(items)").evaluate(data); // 3
51

52
// Count filtered results
53
const users = { users: [{ active: true }, { active: false }, { active: true }] };
54
const activeCount = await jsonata("$count(users[active])").evaluate(users); // 2
55
```
56

57
#### Maximum Function
58

59
Returns the maximum value from an array.
60

61
```javascript { .api }
62
/**
63
 * Find maximum value in array
64
 * @param args - Array of numbers
65
 * @returns Maximum value, undefined if array is empty or undefined
66
 */
67
function $max(args);
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
const data = { scores: [85, 92, 78, 96, 88] };
74
const highest = await jsonata("$max(scores)").evaluate(data); // 96
75

76
// With date comparison
77
const events = { 
78
  events: [
79
    { date: "2023-01-15" },
80
    { date: "2023-03-22" }, 
81
    { date: "2023-02-08" }
82
  ]
83
};
84
const latest = await jsonata("$max(events.date)").evaluate(events); // "2023-03-22"
85
```
86

87
#### Minimum Function
88

89
Returns the minimum value from an array.
90

91
```javascript { .api }
92
/**
93
 * Find minimum value in array
94
 * @param args - Array of numbers
95
 * @returns Minimum value, undefined if array is empty or undefined
96
 */
97
function $min(args);
98
```
99

100
#### Average Function
101

102
Calculates the average of numeric values in an array.
103

104
```javascript { .api }
105
/**
106
 * Calculate average of numeric values
107
 * @param args - Array of numbers
108
 * @returns Average value, undefined if array is empty or undefined
109
 */
110
function $average(args);
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
const data = { temperatures: [20, 22, 19, 23, 21] };
117
const avg = await jsonata("$average(temperatures)").evaluate(data); // 21
118

119
// Calculate grade point average
120
const student = {
121
  grades: [
122
    { course: "Math", points: 3.7 },
123
    { course: "Science", points: 3.9 },
124
    { course: "English", points: 3.5 }
125
  ]
126
};
127
const gpa = await jsonata("$average(grades.points)").evaluate(student); // 3.7
128
```
129

130
### Mathematical Functions
131

132
#### Absolute Value
133

134
Returns the absolute value of a number.
135

136
```javascript { .api }
137
/**
138
 * Calculate absolute value
139
 * @param arg - Number input
140
 * @returns Absolute value of the input
141
 */
142
function $abs(arg);
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const result1 = await jsonata("$abs(-5)").evaluate({}); // 5
149
const result2 = await jsonata("$abs(3.14)").evaluate({}); // 3.14
150

151
// With data
152
const data = { difference: -10.5 };
153
const absolute = await jsonata("$abs(difference)").evaluate(data); // 10.5
154
```
155

156
#### Floor Function
157

158
Returns the floor (largest integer less than or equal to) of a number.
159

160
```javascript { .api }
161
/**
162
 * Calculate floor value
163
 * @param arg - Number input
164
 * @returns Floor value
165
 */
166
function $floor(arg);
167
```
168

169
#### Ceiling Function
170

171
Returns the ceiling (smallest integer greater than or equal to) of a number.
172

173
```javascript { .api }
174
/**
175
 * Calculate ceiling value
176
 * @param arg - Number input
177
 * @returns Ceiling value
178
 */
179
function $ceil(arg);
180
```
181

182
#### Round Function
183

184
Rounds a number to a specified precision.
185

186
```javascript { .api }
187
/**
188
 * Round number to specified precision
189
 * @param arg - Number to round
190
 * @param precision - Number of decimal places (optional, defaults to 0)
191
 * @returns Rounded number
192
 */
193
function $round(arg, precision);
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
const result1 = await jsonata("$round(3.14159)").evaluate({}); // 3
200
const result2 = await jsonata("$round(3.14159, 2)").evaluate({}); // 3.14
201
const result3 = await jsonata("$round(3.14159, 4)").evaluate({}); // 3.1416
202

203
// Financial calculations
204
const price = { amount: 123.456 };
205
const rounded = await jsonata("$round(amount, 2)").evaluate(price); // 123.46
206
```
207

208
#### Square Root
209

210
Returns the square root of a number.
211

212
```javascript { .api }
213
/**
214
 * Calculate square root
215
 * @param arg - Number input (must be non-negative)
216
 * @returns Square root of the input
217
 */
218
function $sqrt(arg);
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
const result = await jsonata("$sqrt(16)").evaluate({}); // 4
225

226
// Calculate distance
227
const point = { x: 3, y: 4 };
228
const distance = await jsonata("$sqrt($power(x, 2) + $power(y, 2))").evaluate(point); // 5
229
```
230

231
#### Power Function
232

233
Raises a base number to an exponent.
234

235
```javascript { .api }
236
/**
237
 * Calculate power (base^exponent)
238
 * @param arg - Base number
239
 * @param exp - Exponent
240
 * @returns Base raised to the power of exponent
241
 */
242
function $power(arg, exp);
243
```
244

245
**Usage Examples:**
246

247
```javascript
248
const result1 = await jsonata("$power(2, 3)").evaluate({}); // 8
249
const result2 = await jsonata("$power(9, 0.5)").evaluate({}); // 3
250

251
// Compound interest calculation
252
const investment = { principal: 1000, rate: 0.05, years: 3 };
253
const future = await jsonata("principal * $power(1 + rate, years)").evaluate(investment);
254
```
255

256
#### Random Function
257

258
Returns a random number between 0 and 1.
259

260
```javascript { .api }
261
/**
262
 * Generate random number
263
 * @returns Random number between 0 (inclusive) and 1 (exclusive)
264
 */
265
function $random();
266
```
267

268
**Usage Examples:**
269

270
```javascript
271
const random = await jsonata("$random()").evaluate({}); // e.g., 0.7341234
272

273
// Random integer between 1 and 10
274
const randomInt = await jsonata("$floor($random() * 10) + 1").evaluate({});
275

276
// Random element from array
277
const data = { options: ["red", "green", "blue"] };
278
const randomChoice = await jsonata("options[$floor($random() * $count(options))]").evaluate(data);
279
```
280

281
### Type Conversion
282

283
#### Number Conversion
284

285
Converts a value to a number.
286

287
```javascript { .api }
288
/**
289
 * Convert value to number
290
 * @param arg - Value to convert
291
 * @returns Numeric representation of the value
292
 */
293
function $number(arg);
294
```
295

296
**Usage Examples:**
297

298
```javascript
299
const result1 = await jsonata('$number("123")').evaluate({}); // 123
300
const result2 = await jsonata('$number("3.14")').evaluate({}); // 3.14
301
const result3 = await jsonata('$number(true)').evaluate({}); // 1
302

303
// Convert string data to numbers
304
const data = { prices: ["10.99", "25.50", "7.25"] };
305
const numbers = await jsonata("prices.$number($)").evaluate(data); // [10.99, 25.5, 7.25]
306
```
307

308
### Formatting Functions
309

310
#### Number Formatting
311

312
Formats a number according to a picture string.
313

314
```javascript { .api }
315
/**
316
 * Format number according to picture string
317
 * @param value - Number to format
318
 * @param picture - Picture string defining the format
319
 * @param options - Optional formatting options
320
 * @returns Formatted string representation
321
 */
322
function $formatNumber(value, picture, options);
323
```
324

325
**Usage Examples:**
326

327
```javascript
328
// Basic formatting
329
const result1 = await jsonata('$formatNumber(1234.5, "#,###.00")').evaluate({}); // "1,234.50"
330
const result2 = await jsonata('$formatNumber(0.75, "0%")').evaluate({}); // "75%"
331

332
// Currency formatting
333
const price = { amount: 1234.56 };
334
const formatted = await jsonata('$formatNumber(amount, "$#,##0.00")').evaluate(price); // "$1,234.56"
335
```
336

337
#### Base Formatting
338

339
Formats a number in a specified radix (base).
340

341
```javascript { .api }
342
/**
343
 * Format number in specified radix
344
 * @param value - Number to format
345
 * @param radix - Base (2-36)
346
 * @returns String representation in specified base
347
 */
348
function $formatBase(value, radix);
349
```
350

351
**Usage Examples:**
352

353
```javascript
354
const binary = await jsonata("$formatBase(10, 2)").evaluate({}); // "1010"
355
const hex = await jsonata("$formatBase(255, 16)").evaluate({}); // "ff"
356
const octal = await jsonata("$formatBase(64, 8)").evaluate({}); // "100"
357

358
// Convert array of numbers to hex
359
const data = { values: [10, 15, 255] };
360
const hexValues = await jsonata("values.$formatBase($, 16)").evaluate(data); // ["a", "f", "ff"]
361
```