0
# Mathematical Operations
1

2
Mathematical operations helper that performs arithmetic calculations within templates with full precision control and error handling.
3

4
## Capabilities
5

6
### Math Helper
7

8
Performs mathematical operations on numeric values with optional rounding and conditional rendering support.
9

10
```javascript { .api }
11
/**
12
 * Performs mathematical operations on numeric values
13
 * @param key - First operand value (required)
14
 * @param method - Mathematical operation to perform (required)
15
 * @param operand - Second operand value (required for binary operations)
16
 * @param round - If truthy, rounds the result to nearest integer
17
 */
18
{@math key="operand1" method="operation" operand="operand2" round="boolean"/}
19

20
// With conditional body (acts like @select helper)
21
{@math key="operand1" method="operation" operand="operand2"}
22
  {@eq value="expected"}Result matches expected value{/eq}
23
  {@gt value="threshold"}Result is above threshold{/gt}
24
{/math}
25
```
26

27
**Supported Operations:**
28

29
- `add`: Addition (key + operand)
30
- `subtract`: Subtraction (key - operand)
31
- `multiply`: Multiplication (key * operand)
32
- `divide`: Division (key / operand) - logs error if operand is 0
33
- `mod`: Modulo (key % operand) - logs error if operand is 0
34
- `ceil`: Ceiling (Math.ceil(key)) - operand not required
35
- `floor`: Floor (Math.floor(key)) - operand not required
36
- `round`: Round (Math.round(key)) - operand not required
37
- `abs`: Absolute value (Math.abs(key)) - operand not required
38
- `toint`: Convert to integer (parseInt(key, 10)) - operand not required
39

40
**Usage Examples:**
41

42
```javascript
43
// Basic arithmetic operations
44
{@math key="15" method="add" operand="5"/}
45
<!-- Output: 20 -->
46

47
{@math key="100" method="divide" operand="3" round="true"/}
48
<!-- Output: 33 -->
49

50
// Using context variables
51
{@math key="{price}" method="multiply" operand="{quantity}"/}
52

53
// Single operand operations
54
{@math key="-42" method="abs"/}
55
<!-- Output: 42 -->
56

57
{@math key="3.7" method="floor"/}
58
<!-- Output: 3 -->
59

60
// With conditional body
61
{@math key="{score}" method="mod" operand="10"}
62
  {@eq value="0"}Score is divisible by 10{/eq}
63
  {@ne value="0"}Score has remainder: {.}{/ne}
64
{/math}
65

66
// Complex calculation with variables
67
{@math key="{$idx}" method="mod" operand="2"}
68
  {@eq value="0"}Even row{/eq}
69
  {@eq value="1"}Odd row{/eq}
70
{/math}
71
```
72

73
**Error Handling:**
74

75
- **Division by zero**: Outputs `NaN` and logs error message `"{@math}: Division by 0"`
76
- **Missing key parameter**: Logs error `"{@math}: \`key\` or \`method\` was not provided"` and returns empty output
77
- **Missing method parameter**: Logs error `"{@math}: \`key\` or \`method\` was not provided"` and returns empty output
78
- **Invalid method**: Logs error `"{@math}: Method \`methodName\` is not supported"` and returns empty output
79
- **Non-numeric values**: Converted using `parseFloat()` - may result in `NaN` output
80
- **Undefined context variables**: Resolve to `undefined`, then convert to `NaN`
81

82
**Type Coercion:**
83

84
All key and operand values are processed as follows:
85
1. Context variables are resolved using `context.resolve()`
86
2. Resolved values are converted to numbers using `parseFloat()`
87
3. Invalid numeric strings result in `NaN`
88
4. Operations with `NaN` propagate `NaN` to the result
89

90
**Logging:**
91

92
All error messages are logged using `dust.log(helperName, message, level)` where:
93
- `helperName` is "math"
94
- `message` describes the specific error
95
- `level` is "ERROR" for critical issues like missing parameters