0
# Numeric Assertions
1

2
Type-safe numeric assertions with comparison operations and tolerance-based floating-point comparisons.
3

4
## Capabilities
5

6
### Numeric Subject Creation
7

8
```java { .api }
9
/**
10
 * Creates an IntegerSubject for asserting about Integer values.
11
 * @param actual the Integer under test
12
 */
13
public static IntegerSubject assertThat(Integer actual);
14

15
/**
16
 * Creates a LongSubject for asserting about Long values.
17
 * @param actual the Long under test
18
 */
19
public static LongSubject assertThat(Long actual);
20

21
/**
22
 * Creates a DoubleSubject for asserting about Double values.
23
 * @param actual the Double under test
24
 */
25
public static DoubleSubject assertThat(Double actual);
26

27
/**
28
 * Creates a FloatSubject for asserting about Float values.
29
 * @param actual the Float under test
30
 */
31
public static FloatSubject assertThat(Float actual);
32

33
/**
34
 * Creates a BigDecimalSubject for asserting about BigDecimal values.
35
 * @param actual the BigDecimal under test
36
 */
37
public static BigDecimalSubject assertThat(BigDecimal actual);
38
```
39

40
### Comparable Assertions
41

42
All numeric subjects inherit from ComparableSubject providing comparison operations.
43

44
```java { .api }
45
/**
46
 * Fails if the subject is not greater than or equal to the given value.
47
 * @param other the value to compare against
48
 */
49
public void isAtLeast(T other);
50

51
/**
52
 * Fails if the subject is not less than or equal to the given value.
53
 * @param other the value to compare against
54
 */
55
public void isAtMost(T other);
56

57
/**
58
 * Fails if the subject is not strictly greater than the given value.
59
 * @param other the value to compare against
60
 */
61
public void isGreaterThan(T other);
62

63
/**
64
 * Fails if the subject is not strictly less than the given value.  
65
 * @param other the value to compare against
66
 */
67
public void isLessThan(T other);
68
```
69

70
**Usage Examples:**
71

72
```java
73
// Integer comparisons
74
assertThat(42).isGreaterThan(30);
75
assertThat(42).isAtLeast(42);
76
assertThat(42).isAtMost(50);
77
assertThat(42).isLessThan(100);
78

79
// Long comparisons
80
assertThat(1000L).isGreaterThan(999L);
81
assertThat(1000L).isAtLeast(1000L);
82

83
// BigDecimal comparisons
84
BigDecimal price = new BigDecimal("19.99");
85
assertThat(price).isGreaterThan(new BigDecimal("15.00"));
86
assertThat(price).isLessThan(new BigDecimal("25.00"));
87
```
88

89
### Range Assertions (Guava Integration)
90

91
```java { .api }
92
/**
93
 * Fails if the subject is not within the given range (Guava Range).
94
 * @param range the range that should contain the subject
95
 */
96
public void isIn(Range<T> range);
97

98
/**
99
 * Fails if the subject is within the given range.
100
 * @param range the range that should not contain the subject
101
 */
102
public void isNotIn(Range<T> range);
103
```
104

105
**Usage Examples:**
106

107
```java
108
import com.google.common.collect.Range;
109

110
// Range checking
111
assertThat(5).isIn(Range.closed(1, 10));      // [1, 10]
112
assertThat(5).isIn(Range.open(0, 10));        // (0, 10)
113
assertThat(5).isIn(Range.atLeast(5));         // [5, +∞)
114
assertThat(5).isNotIn(Range.greaterThan(10)); // (10, +∞)
115
```
116

117
### Floating-Point Tolerance Assertions
118

119
Special handling for floating-point comparisons with tolerance.
120

121
```java { .api }
122
/**
123
 * Prepares for a tolerance-based comparison of double values.
124
 * @param tolerance the allowed difference between actual and expected
125
 */
126
public TolerantDoubleComparison isWithin(double tolerance);
127

128
/**
129
 * Prepares for a tolerance-based comparison of float values.
130
 * @param tolerance the allowed difference between actual and expected
131
 */
132
public TolerantFloatComparison isWithin(float tolerance);
133
```
134

135
#### TolerantDoubleComparison Methods
136

137
```java { .api }
138
/**
139
 * Fails if the subject is not equal to the given value within the tolerance.
140
 * @param expected the expected value
141
 */
142
public void of(double expected);
143

144
/**
145
 * Fails if the subject is not equal to the given Double within the tolerance.
146
 * @param expected the expected Double value
147
 */
148
public void of(Double expected);
149

150
/**
151
 * Fails if the subject is not equal to the given int within the tolerance.
152
 * @param expected the expected int value  
153
 */
154
public void of(int expected);
155

156
/**
157
 * Fails if the subject is not equal to the given long within the tolerance.
158
 * @param expected the expected long value
159
 */
160
public void of(long expected);
161
```
162

163
#### TolerantFloatComparison Methods
164

165
```java { .api }
166
/**
167
 * Fails if the subject is not equal to the given value within the tolerance.
168
 * @param expected the expected value
169
 */
170
public void of(float expected);
171

172
/**
173
 * Fails if the subject is not equal to the given Float within the tolerance.
174
 * @param expected the expected Float value
175
 */
176
public void of(Float expected);
177

178
/**
179
 * Fails if the subject is not equal to the given int within the tolerance.
180
 * @param expected the expected int value
181
 */
182
public void of(int expected);
183

184
/**
185
 * Fails if the subject is not equal to the given long within the tolerance.
186
 * @param expected the expected long value
187
 */
188
public void of(long expected);
189
```
190

191
**Usage Examples:**
192

193
```java
194
// Double tolerance comparisons
195
double result = 1.0 / 3.0;
196
assertThat(result).isWithin(0.0001).of(0.3333);
197
assertThat(result).isWithin(1e-10).of(1.0 / 3.0);
198

199
// Float tolerance comparisons
200
float calculation = 0.1f + 0.2f;
201
assertThat(calculation).isWithin(0.0001f).of(0.3f);
202

203
// Comparing with different numeric types
204
assertThat(3.14159).isWithin(0.001).of(Math.PI);
205
assertThat(2.0).isWithin(0.1).of(2);  // int
206
assertThat(2.0).isWithin(0.1).of(2L); // long
207
```
208

209
### Infinity and NaN Assertions
210

211
Special assertions for handling infinite and NaN values.
212

213
```java { .api }
214
/**
215
 * Fails if the subject is not positive infinity.
216
 */
217
public void isPositiveInfinity();
218

219
/**
220
 * Fails if the subject is not negative infinity.
221
 */
222
public void isNegativeInfinity();
223

224
/**
225
 * Fails if the subject is not NaN (Not a Number).
226
 */
227
public void isNaN();
228

229
/**
230
 * Fails if the subject is NaN.
231
 */
232
public void isNotNaN();
233

234
/**
235
 * Fails if the subject is not finite (i.e., is infinite or NaN).
236
 */
237
public void isFinite();
238
```
239

240
**Usage Examples:**
241

242
```java
243
// Infinity checks
244
assertThat(Double.POSITIVE_INFINITY).isPositiveInfinity();
245
assertThat(Double.NEGATIVE_INFINITY).isNegativeInfinity();
246
assertThat(1.0 / 0.0).isPositiveInfinity();
247

248
// NaN checks
249
assertThat(Double.NaN).isNaN();
250
assertThat(0.0 / 0.0).isNaN();
251
assertThat(Math.sqrt(-1)).isNaN();
252
assertThat(42.0).isNotNaN();
253

254
// Finite checks
255
assertThat(42.0).isFinite();
256
assertThat(Math.PI).isFinite();
257
```
258

259
### BigDecimal Special Assertions
260

261
Special methods for BigDecimal comparisons.
262

263
```java { .api }
264
/**
265
 * Fails if the subject is not equal to the given BigDecimal ignoring scale differences.
266
 * For example, 2.0 and 2.00 are considered equal.
267
 * @param expected the expected BigDecimal value
268
 */
269
public void isEqualToIgnoringScale(BigDecimal expected);
270

271
/**
272
 * Fails if the subject is equal to the given BigDecimal ignoring scale differences.
273
 * @param unexpected the BigDecimal value that should not be equal ignoring scale
274
 */
275
public void isNotEqualToIgnoringScale(BigDecimal unexpected);
276
```
277

278
**Usage Examples:**
279

280
```java
281
BigDecimal value1 = new BigDecimal("2.0");
282
BigDecimal value2 = new BigDecimal("2.00");
283
BigDecimal value3 = new BigDecimal("2.000");
284

285
// These would fail with regular isEqualTo due to scale differences
286
assertThat(value1).isEqualToIgnoringScale(value2);
287
assertThat(value2).isEqualToIgnoringScale(value3);
288
assertThat(value1).isNotEqualToIgnoringScale(new BigDecimal("3.0"));
289

290
// Regular equality considers scale
291
assertThat(value1).isNotEqualTo(value2); // Different scales
292
```
293

294
### Numeric Testing Examples
295

296
Common patterns for numeric testing:
297

298
```java
299
// Testing calculations with tolerance
300
double calculateCircleArea(double radius) {
301
    return Math.PI * radius * radius;
302
}
303

304
double area = calculateCircleArea(5.0);
305
assertThat(area).isWithin(0.001).of(78.539);
306

307
// Testing ranges and bounds
308
int score = calculateScore();
309
assertThat(score).isAtLeast(0);
310
assertThat(score).isAtMost(100);
311
assertThat(score).isIn(Range.closed(0, 100));
312

313
// Testing statistical calculations
314
List<Double> values = Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0);
315
double average = values.stream().mapToDouble(Double::doubleValue).average().orElse(0.0);
316
assertThat(average).isWithin(0.0001).of(3.0);
317

318
// Testing financial calculations
319
BigDecimal price = new BigDecimal("19.99");
320
BigDecimal tax = new BigDecimal("0.08");
321
BigDecimal total = price.multiply(BigDecimal.ONE.add(tax));
322
assertThat(total).isEqualToIgnoringScale(new BigDecimal("21.5892"));
323

324
// Testing edge cases
325
double result = Math.log(-1);
326
assertThat(result).isNaN();
327

328
double division = 1.0 / 0.0;
329
assertThat(division).isPositiveInfinity();
330
```
331

332
## Types
333

334
```java { .api }
335
/**
336
 * Base subject class for comparable types providing comparison methods.
337
 */
338
public abstract class ComparableSubject<T extends Comparable<?>> extends Subject {
339
    /**
340
     * Constructor for ComparableSubject.
341
     * @param metadata failure metadata for context
342
     * @param actual the Comparable value under test
343
     */
344
    protected ComparableSubject(FailureMetadata metadata, T actual);
345
}
346

347
/**
348
 * Subject class for making assertions about Integer values.
349
 */
350
public class IntegerSubject extends ComparableSubject<Integer> {
351
    /**
352
     * Constructor for IntegerSubject.
353
     * @param metadata failure metadata for context
354
     * @param actual the Integer under test
355
     */
356
    protected IntegerSubject(FailureMetadata metadata, Integer actual);
357
}
358

359
/**
360
 * Subject class for making assertions about Long values.
361
 */
362
public class LongSubject extends ComparableSubject<Long> {
363
    /**
364
     * Constructor for LongSubject.
365
     * @param metadata failure metadata for context
366
     * @param actual the Long under test
367
     */
368
    protected LongSubject(FailureMetadata metadata, Long actual);
369
}
370

371
/**
372
 * Subject class for making assertions about Double values.
373
 */
374
public class DoubleSubject extends ComparableSubject<Double> {
375
    /**
376
     * Constructor for DoubleSubject.
377
     * @param metadata failure metadata for context
378
     * @param actual the Double under test
379
     */
380
    protected DoubleSubject(FailureMetadata metadata, Double actual);
381
}
382

383
/**
384
 * Subject class for making assertions about Float values.
385
 */
386
public class FloatSubject extends ComparableSubject<Float> {
387
    /**
388
     * Constructor for FloatSubject.
389
     * @param metadata failure metadata for context
390
     * @param actual the Float under test
391
     */
392
    protected FloatSubject(FailureMetadata metadata, Float actual);
393
}
394

395
/**
396
 * Subject class for making assertions about BigDecimal values.
397
 */
398
public class BigDecimalSubject extends ComparableSubject<BigDecimal> {
399
    /**
400
     * Constructor for BigDecimalSubject.
401
     * @param metadata failure metadata for context
402
     * @param actual the BigDecimal under test
403
     */
404
    protected BigDecimalSubject(FailureMetadata metadata, BigDecimal actual);
405
}
406

407
/**
408
 * Provides tolerance-based comparison methods for double values.
409
 */
410
public abstract class TolerantDoubleComparison {
411
    // Methods documented above
412
}
413

414
/**
415
 * Provides tolerance-based comparison methods for float values.
416
 */
417
public abstract class TolerantFloatComparison {
418
    // Methods documented above
419
}
420
```