0
# Interval & Range Operations
1

2
Functions for clamping, wrapping, and constraining values within intervals. Essential for bounds checking and value normalization.
3

4
## Capabilities
5

6
### Clamping Functions
7

8
Constrain values to specific ranges by clamping them to the nearest boundary.
9

10
```typescript { .api }
11
/**
12
 * Clamps value x to given closed interval [min, max]
13
 * @param x - Value to clamp
14
 * @param min - Minimum boundary (inclusive)
15
 * @param max - Maximum boundary (inclusive)
16
 * @returns Clamped value
17
 */
18
function clamp(x: number, min: number, max: number): number;
19

20
/**
21
 * Clamps value x to closed [0, ∞] interval
22
 * @param x - Value to clamp
23
 * @returns Value clamped to non-negative range
24
 */
25
function clamp0(x: number): number;
26

27
/**
28
 * Clamps value x to closed [0, 1] interval
29
 * @param x - Value to clamp
30
 * @returns Value clamped to unit range
31
 */
32
function clamp01(x: number): number;
33

34
/**
35
 * Clamps value x to closed [-1, 1] interval
36
 * @param x - Value to clamp
37
 * @returns Value clamped to normalized range
38
 */
39
function clamp11(x: number): number;
40

41
/**
42
 * Clamps value x to closed [0, 0.5] interval
43
 * @param x - Value to clamp
44
 * @returns Value clamped to half-unit range
45
 */
46
function clamp05(x: number): number;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { clamp, clamp01, clamp11 } from "@thi.ng/math/interval";
53

54
// General clamping
55
const bounded = clamp(15, 0, 10); // 10
56
const negative = clamp(-5, 0, 10); // 0
57

58
// Specialized clamping
59
const normalized = clamp01(1.5); // 1
60
const symmetric = clamp11(-2.5); // -1
61
```
62

63
### Wrapping Functions
64

65
Fold values back into intervals by wrapping them around the boundaries.
66

67
```typescript { .api }
68
/**
69
 * Folds x back inside closed [min, max] interval
70
 * @param x - Value to wrap
71
 * @param min - Minimum boundary
72
 * @param max - Maximum boundary
73
 * @returns Wrapped value
74
 */
75
function wrap(x: number, min: number, max: number): number;
76

77
/**
78
 * Optimized wrap for cases where x is in [min-d, max+d] interval
79
 * @param x - Value to wrap (should be close to target range)
80
 * @param min - Minimum boundary
81
 * @param max - Maximum boundary
82
 * @returns Wrapped value
83
 */
84
function wrapOnce(x: number, min: number, max: number): number;
85

86
/**
87
 * Wraps to [0, 1] interval
88
 * @param x - Value to wrap
89
 * @returns Value wrapped to unit interval
90
 */
91
function wrap01(x: number): number;
92

93
/**
94
 * Wraps to [-1, 1] interval
95
 * @param x - Value to wrap
96
 * @returns Value wrapped to symmetric unit interval
97
 */
98
function wrap11(x: number): number;
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { wrap, wrap01, wrap11 } from "@thi.ng/math/interval";
105

106
// General wrapping
107
const wrapped = wrap(15, 0, 10); // 5 (15 - 10 = 5)
108
const negativeWrap = wrap(-3, 0, 10); // 7 (wraps around)
109

110
// Specialized wrapping
111
const unitWrap = wrap01(1.3); // 0.3
112
const symmetricWrap = wrap11(2.5); // -1.5 (wrapped)
113
```
114

115
### Min/Max Operations
116

117
Functions for finding minimum and maximum values with various constraints.
118

119
```typescript { .api }
120
/**
121
 * Returns 2-tuple of [min(x,y), max(x,y)]
122
 * @param x - First value
123
 * @param y - Second value
124
 * @returns Tuple with minimum and maximum values
125
 */
126
function minMax(x: number, y: number): [number, number];
127

128
/** Returns index of minimum of 2 values */
129
function min2id(a: number, b: number): number;
130

131
/** Returns index of minimum of 3 values */
132
function min3id(a: number, b: number, c: number): number;
133

134
/** Returns index of minimum of 4 values */
135
function min4id(a: number, b: number, c: number, d: number): number;
136

137
/** Returns index of maximum of 2 values */
138
function max2id(a: number, b: number): number;
139

140
/** Returns index of maximum of 3 values */
141
function max3id(a: number, b: number, c: number): number;
142

143
/** Returns index of maximum of 4 values */
144
function max4id(a: number, b: number, c: number, d: number): number;
145

146
/**
147
 * Returns the non-zero minimum value of the given args
148
 * @param a - First value
149
 * @param b - Second value
150
 * @returns Minimum non-zero value
151
 */
152
function minNonZero2(a: number, b: number): number;
153

154
/**
155
 * Returns the non-zero minimum value of the given args
156
 * @param a - First value
157
 * @param b - Second value
158
 * @param c - Third value
159
 * @returns Minimum non-zero value
160
 */
161
function minNonZero3(a: number, b: number, c: number): number;
162

163
/** Returns value with smaller absolute value */
164
function absMin(a: number, b: number): number;
165

166
/** Returns value with larger absolute value */
167
function absMax(a: number, b: number): number;
168
```
169

170
### Smooth Operations
171

172
Smooth variants of min/max operations that avoid harsh discontinuities.
173

174
```typescript { .api }
175
/**
176
 * Smooth minimum using polynomial blending
177
 * @param a - First value
178
 * @param b - Second value
179
 * @param k - Smoothing factor (higher = smoother)
180
 * @returns Smooth minimum value
181
 */
182
function smin(a: number, b: number, k: number): number;
183

184
/**
185
 * Smooth maximum using polynomial blending
186
 * @param a - First value
187
 * @param b - Second value
188
 * @param k - Smoothing factor (higher = smoother)
189
 * @returns Smooth maximum value
190
 */
191
function smax(a: number, b: number, k: number): number;
192

193
/**
194
 * Smooth clamp combining smin and smax
195
 * @param x - Value to clamp
196
 * @param min - Minimum boundary
197
 * @param max - Maximum boundary
198
 * @param k - Smoothing factor
199
 * @returns Smoothly clamped value
200
 */
201
function sclamp(x: number, min: number, max: number, k: number): number;
202
```
203

204
### Range Testing
205

206
Functions to test if values fall within specific ranges.
207

208
```typescript { .api }
209
/**
210
 * Returns true iff x is in closed interval [min, max]
211
 * @param x - Value to test
212
 * @param min - Minimum boundary (inclusive)
213
 * @param max - Maximum boundary (inclusive)
214
 * @returns True if value is within range
215
 */
216
function inRange(x: number, min: number, max: number): boolean;
217

218
/**
219
 * Returns true iff x is in open interval (min, max)
220
 * @param x - Value to test
221
 * @param min - Minimum boundary (exclusive)
222
 * @param max - Maximum boundary (exclusive)
223
 * @returns True if value is within open range
224
 */
225
function inOpenRange(x: number, min: number, max: number): boolean;
226
```
227

228
### Foldback Functions
229

230
Advanced wrapping functions that create mirror-like behavior at boundaries.
231

232
```typescript { .api }
233
/**
234
 * Recursively mirrors x back into [-e, e] interval
235
 * @param e - Half-width of interval
236
 * @param x - Value to fold
237
 * @returns Folded value
238
 */
239
function foldback(e: number, x: number): number;
240

241
/**
242
 * Folds x into the closed [0, 1] interval with mirroring
243
 * @param x - Value to fold
244
 * @returns Value folded into unit interval
245
 */
246
function foldback01(x: number): number;
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
import { foldback01, smin, inRange } from "@thi.ng/math/interval";
253

254
// Foldback creates oscillating behavior
255
const folded = foldback01(1.3); // 0.7 (mirrors back from 1)
256

257
// Smooth operations avoid discontinuities
258
const smoothMin = smin(5, 8, 2); // ~4.8 (smoother than min)
259

260
// Range testing
261
const withinBounds = inRange(5, 0, 10); // true
262
const outsideBounds = inRange(15, 0, 10); // false
263
```