Merge from rust-lang/rust

1 files changed, 55 insertions, 0 deletions

diff --git a/src/tools/test-float-parse/README.md b/src/tools/test-float-parse/README.md
new file mode 100644
index 00000000000..5e2c43d1cad
--- /dev/null
+++ b/src/tools/test-float-parse/README.md
@@ -0,0 +1,55 @@
+# Float Parsing Tests
+
+These are tests designed to test decimal to float conversions (`dec2flt`) used
+by the standard library.
+
+It consists of a collection of test generators that each generate a set of
+patterns intended to test a specific property. In addition, there are exhaustive
+tests (for <= `f32`) and fuzzers (for anything that can't be run exhaustively).
+
+The generators work as follows:
+
+- Each generator is a struct that lives somewhere in the `gen` module. Usually
+  it is generic over a float type.
+- These generators must implement `Iterator`, which should return a context type
+  that can be used to construct a test string (but usually not the string
+  itself).
+- They must also implement the `Generator` trait, which provides a method to
+  write test context to a string as a test case, as well as some extra metadata.
+
+  The split between context generation and string construction is so that we can
+  reuse string allocations.
+- Each generator gets registered once for each float type. Each of these
+  generators then get their iterator called, and each test case checked against
+  the float type's parse implementation.
+
+Some generators produce decimal strings, others create bit patterns that need to
+be bitcasted to the float type, which then uses its `Display` implementation to
+write to a string. For these, float to decimal (`flt2dec`) conversions also get
+tested, if unintentionally.
+
+For each test case, the following is done:
+
+- The test string is parsed to the float type using the standard library's
+  implementation.
+- The test string is parsed separately to a `BigRational`, which acts as a
+  representation with infinite precision.
+- The rational value then gets checked that it is within the float's
+  representable values (absolute value greater than the smallest number to round
+  to zero, but less less than the first value to round to infinity). If these
+  limits are exceeded, check that the parsed float reflects that.
+- For real nonzero numbers, the parsed float is converted into a rational using
+  `significand * 2^exponent`. It is then checked against the actual rational
+  value, and verified to be within half a bit's precision of the parsed value.
+  Also it is checked that ties round to even.
+
+This is all highly parallelized with `rayon`; test generators can run in
+parallel, and their tests get chunked and run in parallel.
+
+There is a simple command line that allows filtering which tests are run,
+setting the number of iterations for fuzzing tests, limiting failures, setting
+timeouts, etc. See `main.rs` or run with `--help` for options.
+
+Note that when running via `./x`, only tests that take less than a few minutes
+are run by default. Navigate to the crate (or pass `-C` to Cargo) and run it
+directly to run all tests or pass specific arguments.