|
| 1 | +# Float Parsing Tests |
| 2 | + |
| 3 | +These are tests designed to test decimal to float conversions (`dec2flt`) used |
| 4 | +by the standard library. |
| 5 | + |
| 6 | +It consistes of a collection of test generators that each generate a set of |
| 7 | +patterns intended to test a specific property. In addition, there are exhaustive |
| 8 | +tests (for <= `f32`) and fuzzers (for anything that can't be run exhaustively). |
| 9 | + |
| 10 | +The generators work as follows: |
| 11 | + |
| 12 | +- Each generator is a struct that lives somewhere in the `gen` module. Usually |
| 13 | + it is generic over a float type. |
| 14 | +- These generators must implement `Iterator`, which should return a context type |
| 15 | + that can be used to construct a test string (but usually not the string |
| 16 | + itself). |
| 17 | +- They must also implement the `Generator` trait, which provides a method to |
| 18 | + write test context to a string as a test case, as well as some extra metadata. |
| 19 | + |
| 20 | + The split between context generation and string construction is so that we can |
| 21 | + reuse string allocations. |
| 22 | +- Each generator gets registered once for each float type. Each of these |
| 23 | + generators then get their iterator called, and each test case checked against |
| 24 | + the float type's parse implementation. |
| 25 | + |
| 26 | +Some generators produce decimal strings, others create bit patterns that need to |
| 27 | +be bitcasted to the float type, which then uses its `Display` implementation to |
| 28 | +write to a string. For these, float to decimal (`flt2dec`) conversions also get |
| 29 | +tested, if unintentionally. |
| 30 | + |
| 31 | +For each test case, the following is done: |
| 32 | + |
| 33 | +- The test string is parsed to the float type using the standard library's |
| 34 | + implementation. |
| 35 | +- The test string is parsed separately to a `BigRational`, which acts as a |
| 36 | + representation with infinite precision. |
| 37 | +- The rational value then gets checked that it is within the float's |
| 38 | + representable values (absolute value greater than the smallest number to round |
| 39 | + to zero, but less less than the first value to round to infinity). If these |
| 40 | + limits are exceeded, check that the parsed float reflects that. |
| 41 | +- For real nonzero numbers, the parsed float is converted into a rational using |
| 42 | + `significand * 2^exponent`. It is then checked against the actual rational |
| 43 | + value, and verified to be within half a bit's precision of the parsed value. |
| 44 | + Also it is checked that ties round to even. |
| 45 | + |
| 46 | +This is all highly parallelized with `rayon`; test generators can run in |
| 47 | +parallel, and their tests get chunked and run in parallel. |
| 48 | + |
| 49 | +There is a simple command line that allows filtering which tests are run, |
| 50 | +setting the number of iterations for fuzzing tests, limiting failures, setting |
| 51 | +timeouts, etc. See `main.rs` or run with `--help` for options. |
| 52 | + |
| 53 | +Note that when running via `./x`, only tests that take less than a few minutes |
| 54 | +are run by default. Navigate to the crate (or pass `-C` to Cargo) and run it |
| 55 | +directly to run all tests or pass specific arguments. |
0 commit comments