0
# Primitive Matchers
1

2
Comprehensive matchers for all Kotlin primitive types including Boolean, Integer, Long, Short, Byte, Character, Float, and Double values with type-specific validations, comparisons, and range operations.
3

4
## Capabilities
5

6
### Boolean Matchers
7

8
Simple true/false assertions for Boolean values.
9

10
```kotlin { .api }
11
/**
12
 * Assert that this Boolean value is true
13
 * @return The original Boolean value for chaining
14
 */
15
fun Boolean.shouldBeTrue(): Boolean
16

17
/**
18
 * Assert that this Boolean value is not true (false or null)
19
 * @return The original Boolean value for chaining
20
 */
21
fun Boolean.shouldNotBeTrue(): Boolean
22

23
/**
24
 * Assert that this Boolean value is false
25
 * @return The original Boolean value for chaining
26
 */
27
fun Boolean.shouldBeFalse(): Boolean
28

29
/**
30
 * Assert that this Boolean value is not false (true or null)
31
 * @return The original Boolean value for chaining
32
 */
33
fun Boolean.shouldNotBeFalse(): Boolean
34

35
/**
36
 * Create a matcher that checks if value is true
37
 * @return Matcher that passes for true values
38
 */
39
fun beTrue(): Matcher<Boolean>
40

41
/**
42
 * Create a matcher that checks if value is false
43
 * @return Matcher that passes for false values
44
 */
45
fun beFalse(): Matcher<Boolean>
46
```
47

48
**Usage Examples:**
49

50
```kotlin
51
import io.kotest.matchers.booleans.*
52

53
val isValid = true
54
val isComplete = false
55

56
isValid.shouldBeTrue()
57
isComplete.shouldBeFalse()
58

59
// Using with should syntax
60
isValid should beTrue()
61
isComplete should beFalse()
62
```
63

64
### Integer Matchers
65

66
Comprehensive matchers for Int values including comparisons, ranges, and percentage tolerance.
67

68
```kotlin { .api }
69
/**
70
 * Assert that this Int is between two values (inclusive)
71
 * @param a Lower bound (inclusive)
72
 * @param b Upper bound (inclusive)
73
 * @return The original Int value for chaining
74
 */
75
fun Int.shouldBeBetween(a: Int, b: Int): Int
76

77
/**
78
 * Assert that this Int is not between two values
79
 * @param a Lower bound
80
 * @param b Upper bound
81
 * @return The original Int value for chaining
82
 */
83
fun Int.shouldNotBeBetween(a: Int, b: Int): Int
84

85
/**
86
 * Assert that this Int is within the specified range
87
 * @param range IntRange to check membership
88
 * @return The original Int value for chaining
89
 */
90
infix fun Int.shouldBeInRange(range: IntRange): Int
91

92
/**
93
 * Assert that this Int is not within the specified range
94
 * @param range IntRange to check non-membership
95
 * @return The original Int value for chaining
96
 */
97
infix fun Int.shouldNotBeInRange(range: IntRange): Int
98

99
/**
100
 * Assert that this Int is within percentage tolerance of another value
101
 * @param other The target value to compare against
102
 * @param percentage The allowed percentage difference (0.0 to 100.0)
103
 * @return The original Int value for chaining
104
 */
105
fun Int.shouldBeWithinPercentageOf(other: Int, percentage: Double): Int
106

107
/**
108
 * Assert that this Int is not within percentage tolerance of another value
109
 * @param other The target value to compare against
110
 * @param percentage The percentage threshold (0.0 to 100.0)
111
 * @return The original Int value for chaining
112
 */
113
fun Int.shouldNotBeWithinPercentageOf(other: Int, percentage: Double): Int
114
```
115

116
#### Integer Comparison Matchers
117

118
```kotlin { .api }
119
/**
120
 * Create a matcher for less than comparison
121
 * @param x The upper bound (exclusive)
122
 * @return Matcher that passes for values less than x
123
 */
124
fun lt(x: Int): Matcher<Int>
125

126
/**
127
 * Create a matcher for less than comparison (alias for lt)
128
 * @param x The upper bound (exclusive)
129
 * @return Matcher that passes for values less than x
130
 */
131
fun beLessThan(x: Int): Matcher<Int>
132

133
/**
134
 * Create a matcher for less than or equal comparison
135
 * @param x The upper bound (inclusive)
136
 * @return Matcher that passes for values less than or equal to x
137
 */
138
fun lte(x: Int): Matcher<Int>
139

140
/**
141
 * Create a matcher for less than or equal comparison (alias for lte)
142
 * @param x The upper bound (inclusive)
143
 * @return Matcher that passes for values less than or equal to x
144
 */
145
fun beLessThanOrEqualTo(x: Int): Matcher<Int>
146

147
/**
148
 * Create a matcher for greater than comparison
149
 * @param x The lower bound (exclusive)
150
 * @return Matcher that passes for values greater than x
151
 */
152
fun gt(x: Int): Matcher<Int>
153

154
/**
155
 * Create a matcher for greater than comparison (alias for gt)
156
 * @param x The lower bound (exclusive)
157
 * @return Matcher that passes for values greater than x
158
 */
159
fun beGreaterThan(x: Int): Matcher<Int>
160

161
/**
162
 * Create a matcher for greater than or equal comparison
163
 * @param x The lower bound (inclusive)
164
 * @return Matcher that passes for values greater than or equal to x
165
 */
166
fun gte(x: Int): Matcher<Int>
167

168
/**
169
 * Create a matcher for greater than or equal comparison (alias for gte)
170
 * @param x The lower bound (inclusive)
171
 * @return Matcher that passes for values greater than or equal to x
172
 */
173
fun beGreaterThanOrEqualTo(x: Int): Matcher<Int>
174

175
/**
176
 * Create a matcher for exact value comparison
177
 * @param x The exact value to match
178
 * @return Matcher that passes for the exact value
179
 */
180
fun exactly(x: Int): Matcher<Int>
181

182
/**
183
 * Create a matcher for range membership
184
 * @param range The IntRange to check membership
185
 * @return Matcher that passes for values within the range
186
 */
187
fun beInRange(range: IntRange): Matcher<Int>
188

189
/**
190
 * Create a matcher for between comparison (inclusive)
191
 * @param a Lower bound (inclusive)
192
 * @param b Upper bound (inclusive)
193
 * @return Matcher that passes for values between a and b
194
 */
195
fun between(a: Int, b: Int): Matcher<Int>
196

197
/**
198
 * Create a matcher for percentage tolerance comparison
199
 * @param other The target value
200
 * @param percentage The allowed percentage difference
201
 * @return Matcher that passes for values within percentage of target
202
 */
203
fun beWithinPercentageOf(other: Int, percentage: Double): Matcher<Int>
204
```
205

206
**Usage Examples:**
207

208
```kotlin
209
import io.kotest.matchers.ints.*
210

211
val score = 85
212
val count = 42
213

214
// Range assertions
215
score.shouldBeBetween(80, 90)
216
count shouldBeInRange 40..50
217

218
// Comparison assertions
219
score should beGreaterThan(80)
220
score should beLessThanOrEqualTo(100)
221

222
// Percentage tolerance
223
score.shouldBeWithinPercentageOf(90, 10.0) // Within 10% of 90
224

225
// Exact value
226
count should exactly(42)
227
```
228

229
### Long Matchers
230

231
Similar pattern to Int matchers but for Long and ULong types.
232

233
```kotlin { .api }
234
/**
235
 * Assert that this Long is between two values (inclusive)
236
 * @param a Lower bound (inclusive)
237
 * @param b Upper bound (inclusive)
238
 * @return The original Long value for chaining
239
 */
240
fun Long.shouldBeBetween(a: Long, b: Long): Long
241

242
/**
243
 * Assert that this Long is within the specified range
244
 * @param range LongRange to check membership
245
 * @return The original Long value for chaining
246
 */
247
infix fun Long.shouldBeInRange(range: LongRange): Long
248

249
/**
250
 * Assert that this Long is within percentage tolerance of another value
251
 * @param other The target value to compare against
252
 * @param percentage The allowed percentage difference (0.0 to 100.0)
253
 * @return The original Long value for chaining
254
 */
255
fun Long.shouldBeWithinPercentageOf(other: Long, percentage: Double): Long
256

257
// Comparison functions follow same pattern as Int
258
fun lt(x: Long): Matcher<Long>
259
fun gt(x: Long): Matcher<Long>
260
fun lte(x: Long): Matcher<Long>
261
fun gte(x: Long): Matcher<Long>
262
fun exactly(x: Long): Matcher<Long>
263
fun between(a: Long, b: Long): Matcher<Long>
264
```
265

266
### Short Matchers
267

268
Similar pattern to Int matchers but for Short and UShort types.
269

270
```kotlin { .api }
271
/**
272
 * Assert that this Short is between two values (inclusive)
273
 * @param a Lower bound (inclusive)
274
 * @param b Upper bound (inclusive)
275
 * @return The original Short value for chaining
276
 */
277
fun Short.shouldBeBetween(a: Short, b: Short): Short
278

279
// Range and comparison functions follow same pattern as Int
280
infix fun Short.shouldBeInRange(range: IntRange): Short
281
fun Short.shouldBeWithinPercentageOf(other: Short, percentage: Double): Short
282

283
fun lt(x: Short): Matcher<Short>
284
fun gt(x: Short): Matcher<Short>
285
fun exactly(x: Short): Matcher<Short>
286
```
287

288
### Byte Matchers
289

290
Similar pattern to Int matchers but for Byte and UByte types.
291

292
```kotlin { .api }
293
/**
294
 * Assert that this Byte is between two values (inclusive)
295
 * @param a Lower bound (inclusive)
296
 * @param b Upper bound (inclusive)
297
 * @return The original Byte value for chaining
298
 */
299
fun Byte.shouldBeBetween(a: Byte, b: Byte): Byte
300

301
// Range and comparison functions follow same pattern as Int
302
infix fun Byte.shouldBeInRange(range: IntRange): Byte
303
fun Byte.shouldBeWithinPercentageOf(other: Byte, percentage: Double): Byte
304

305
fun lt(x: Byte): Matcher<Byte>
306
fun gt(x: Byte): Matcher<Byte>
307
fun exactly(x: Byte): Matcher<Byte>
308
```
309

310
### Character Matchers
311

312
Character-specific matchers for ASCII validation, case checking, and character categories.
313

314
```kotlin { .api }
315
/**
316
 * Assert that this Char is a letter (alphabetic character)
317
 * @return The original Char value for chaining
318
 */
319
fun Char.shouldBeLetter(): Char
320

321
/**
322
 * Assert that this Char is not a letter
323
 * @return The original Char value for chaining
324
 */
325
fun Char.shouldNotBeLetter(): Char
326

327
/**
328
 * Assert that this Char is a digit (0-9)
329
 * @return The original Char value for chaining
330
 */
331
fun Char.shouldBeDigit(): Char
332

333
/**
334
 * Assert that this Char is not a digit
335
 * @return The original Char value for chaining
336
 */
337
fun Char.shouldNotBeDigit(): Char
338

339
/**
340
 * Assert that this Char is uppercase
341
 * @return The original Char value for chaining
342
 */
343
fun Char.shouldBeUpperCase(): Char
344

345
/**
346
 * Assert that this Char is lowercase
347
 * @return The original Char value for chaining
348
 */
349
fun Char.shouldBeLowerCase(): Char
350

351
/**
352
 * Assert that this Char is whitespace
353
 * @return The original Char value for chaining
354
 */
355
fun Char.shouldBeWhitespace(): Char
356

357
/**
358
 * Assert that this Char is an ASCII character (0-127)
359
 * @return The original Char value for chaining
360
 */
361
fun Char.shouldBeAscii(): Char
362

363
/**
364
 * Create matcher for letter validation
365
 * @return Matcher that passes for alphabetic characters
366
 */
367
fun beLetter(): Matcher<Char>
368

369
/**
370
 * Create matcher for digit validation
371
 * @return Matcher that passes for numeric characters (0-9)
372
 */
373
fun beDigit(): Matcher<Char>
374

375
/**
376
 * Create matcher for uppercase validation
377
 * @return Matcher that passes for uppercase characters
378
 */
379
fun beUpperCase(): Matcher<Char>
380

381
/**
382
 * Create matcher for lowercase validation
383
 * @return Matcher that passes for lowercase characters
384
 */
385
fun beLowerCase(): Matcher<Char>
386

387
/**
388
 * Create matcher for whitespace validation
389
 * @return Matcher that passes for whitespace characters
390
 */
391
fun beWhitespace(): Matcher<Char>
392

393
/**
394
 * Create matcher for ASCII validation
395
 * @return Matcher that passes for ASCII characters (0-127)
396
 */
397
fun beAscii(): Matcher<Char>
398
```
399

400
**Usage Examples:**
401

402
```kotlin
403
import io.kotest.matchers.char.*
404

405
val letter = 'A'
406
val digit = '5'
407
val space = ' '
408

409
// Character category assertions
410
letter.shouldBeLetter()
411
letter.shouldBeUpperCase()
412
letter.shouldBeAscii()
413

414
digit.shouldBeDigit()
415
space.shouldBeWhitespace()
416

417
// Using matcher syntax
418
letter should beLetter()
419
digit should beDigit()
420
```
421

422
### Float Matchers
423

424
Floating-point matchers with tolerance support for precision handling.
425

426
```kotlin { .api }
427
/**
428
 * Assert that this Float is between two values (inclusive)
429
 * @param a Lower bound (inclusive)
430
 * @param b Upper bound (inclusive)
431
 * @return The original Float value for chaining
432
 */
433
fun Float.shouldBeBetween(a: Float, b: Float): Float
434

435
/**
436
 * Assert that this Float equals another value within default tolerance
437
 * @param other The expected value
438
 * @return The original Float value for chaining
439
 */
440
infix fun Float.shouldBeExactly(other: Float): Float
441

442
/**
443
 * Assert that this Float equals another value within specified tolerance
444
 * @param other The expected value
445
 * @param tolerance The maximum allowed difference
446
 * @return The original Float value for chaining
447
 */
448
fun Float.shouldBeWithinTolerance(other: Float, tolerance: Float): Float
449

450
/**
451
 * Assert that this Float is positive (greater than 0)
452
 * @return The original Float value for chaining
453
 */
454
fun Float.shouldBePositive(): Float
455

456
/**
457
 * Assert that this Float is negative (less than 0)
458
 * @return The original Float value for chaining
459
 */
460
fun Float.shouldBeNegative(): Float
461

462
/**
463
 * Assert that this Float is zero (within tolerance)
464
 * @return The original Float value for chaining
465
 */
466
fun Float.shouldBeZero(): Float
467

468
/**
469
 * Assert that this Float is NaN (Not a Number)
470
 * @return The original Float value for chaining
471
 */
472
fun Float.shouldBeNaN(): Float
473

474
/**
475
 * Assert that this Float is infinite
476
 * @return The original Float value for chaining
477
 */
478
fun Float.shouldBeInfinite(): Float
479

480
/**
481
 * Create matcher for exact equality with tolerance
482
 * @param expected The expected value
483
 * @param tolerance The maximum allowed difference
484
 * @return Matcher that passes for values within tolerance
485
 */
486
fun beExactly(expected: Float, tolerance: Float = 0.0001f): Matcher<Float>
487

488
/**
489
 * Create matcher for positive number validation
490
 * @return Matcher that passes for positive values
491
 */
492
fun bePositive(): Matcher<Float>
493

494
/**
495
 * Create matcher for negative number validation
496
 * @return Matcher that passes for negative values
497
 */
498
fun beNegative(): Matcher<Float>
499

500
/**
501
 * Create matcher for zero validation with tolerance
502
 * @return Matcher that passes for zero (within default tolerance)
503
 */
504
fun beZero(): Matcher<Float>
505

506
/**
507
 * Create matcher for NaN validation
508
 * @return Matcher that passes for NaN values
509
 */
510
fun beNaN(): Matcher<Float>
511

512
/**
513
 * Create matcher for infinity validation
514
 * @return Matcher that passes for infinite values
515
 */
516
fun beInfinite(): Matcher<Float>
517
```
518

519
### Double Matchers
520

521
Double precision matchers with enhanced tolerance support.
522

523
```kotlin { .api }
524
/**
525
 * Assert that this Double is between two values (inclusive)
526
 * @param a Lower bound (inclusive)
527
 * @param b Upper bound (inclusive)
528
 * @return The original Double value for chaining
529
 */
530
fun Double.shouldBeBetween(a: Double, b: Double): Double
531

532
/**
533
 * Assert that this Double equals another value within default tolerance
534
 * @param other The expected value
535
 * @return The original Double value for chaining
536
 */
537
infix fun Double.shouldBeExactly(other: Double): Double
538

539
/**
540
 * Assert that this Double equals another value within specified tolerance
541
 * @param other The expected value
542
 * @param tolerance The maximum allowed difference
543
 * @return The original Double value for chaining
544
 */
545
fun Double.shouldBeWithinTolerance(other: Double, tolerance: Double): Double
546

547
/**
548
 * Assert that this Double is within percentage of another value
549
 * @param other The target value
550
 * @param percentage The allowed percentage difference (0.0 to 100.0)
551
 * @return The original Double value for chaining
552
 */
553
fun Double.shouldBeWithinPercentageOf(other: Double, percentage: Double): Double
554

555
/**
556
 * Assert that this Double is positive (greater than 0)
557
 * @return The original Double value for chaining
558
 */
559
fun Double.shouldBePositive(): Double
560

561
/**
562
 * Assert that this Double is negative (less than 0)
563
 * @return The original Double value for chaining
564
 */
565
fun Double.shouldBeNegative(): Double
566

567
/**
568
 * Assert that this Double is zero (within tolerance)
569
 * @return The original Double value for chaining
570
 */
571
fun Double.shouldBeZero(): Double
572

573
/**
574
 * Assert that this Double is NaN (Not a Number)
575
 * @return The original Double value for chaining
576
 */
577
fun Double.shouldBeNaN(): Double
578

579
/**
580
 * Assert that this Double is infinite
581
 * @return The original Double value for chaining
582
 */
583
fun Double.shouldBeInfinite(): Double
584

585
// Matcher factory functions follow same pattern as Float
586
fun beExactly(expected: Double, tolerance: Double = 0.000000001): Matcher<Double>
587
fun beWithinPercentageOf(other: Double, percentage: Double): Matcher<Double>
588
fun bePositive(): Matcher<Double>
589
fun beNegative(): Matcher<Double>
590
fun beZero(): Matcher<Double>
591
fun beNaN(): Matcher<Double>
592
fun beInfinite(): Matcher<Double>
593
```
594

595
**Usage Examples:**
596

597
```kotlin
598
import io.kotest.matchers.doubles.*
599
import io.kotest.matchers.floats.*
600

601
val price = 19.99
602
val calculation = 0.1 + 0.2
603

604
// Tolerance-based equality
605
price.shouldBeWithinTolerance(20.0, 0.01)
606
calculation.shouldBeExactly(0.3) // Uses default tolerance
607

608
// Percentage comparison  
609
price.shouldBeWithinPercentageOf(20.0, 5.0) // Within 5% of 20.0
610

611
// Sign validation
612
price.shouldBePositive()
613
(-price).shouldBeNegative()
614

615
// Special value validation
616
val invalid = Double.NaN
617
invalid.shouldBeNaN()
618

619
// Using matcher syntax
620
price should beWithinPercentageOf(20.0, 10.0)
621
calculation should beExactly(0.3, 0.0001)
622
```
623

624
## Error Handling
625

626
Primitive matchers provide detailed error messages for failures:
627

628
- **Numeric comparisons**: Show expected vs actual values with clear comparison operators
629
- **Range failures**: Indicate the range bounds and actual value position  
630
- **Tolerance failures**: Display the expected value, actual value, tolerance, and actual difference
631
- **Character category failures**: Specify which category check failed and the actual character
632
- **Special value failures**: Clear messages for NaN, infinity, and other special cases
633

634
All matchers preserve type safety and provide meaningful error messages that help identify the specific assertion failure.