From 6702cd424436c7dc6c53ad4430f41173a6d5c2a7 Mon Sep 17 00:00:00 2001
From: Pavel Novikov <dev-ape@yandex.ru>
Date: Fri, 5 Sep 2025 13:28:27 +0300
Subject: [PATCH] added doc section in the README, added example code test
 executable

---
 README.md                             | 27 +++++++++++++++++++++++++++
 tests/CMakeLists.txt                  |  1 +
 tests/example_integer_times_pow10.cpp | 12 ++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 tests/example_integer_times_pow10.cpp

diff --git a/README.md b/README.md
index 8770ac4..7ebb163 100644
--- a/README.md
+++ b/README.md
@@ -357,6 +357,33 @@ int main() {
 }
 ```
 
+## Multiplication of an integer by a power of 10
+An integer `W` can be multiplied by a power of ten `10^Q` and
+converted to `double` with correctly rounded value
+(in "round to nearest, tie to even" fashion) using
+`fast_float::integer_times_pow10()`, e.g.:
+```C++
+const uint64_t W = 12345678901234567;
+const int Q = 23;
+const double result = fast_float::integer_times_pow10(W, Q);
+std::cout.precision(17);
+std::cout << W << " * 10^" << Q << " = " << result << " ("
+  << (result == 12345678901234567e23 ? "==" : "!=") << "expected)\n";
+```
+outputs
+```
+12345678901234567 * 10^23 = 1.2345678901234567e+39 (==expected)
+```
+`fast_float::integer_times_pow10()` gives the same result as
+using `fast_float::from_chars()` when parsing the string `"WeQ"`
+(in this example `"12345678901234567e23"`),
+except `fast_float::integer_times_pow10()` does not report out-of-range errors, and
+underflows to zero or overflows to infinity when the resulting value is
+out of range.
+
+Overloads of `fast_float::integer_times_pow10()` are provided for
+signed and unsigned integer types: `int64_t`, `uint64_t`, etc.
+
 
 ## Users and Related Work
 
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index c4e43b2..817c4e8 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -71,6 +71,7 @@ fast_float_add_cpp_test(wide_char_test)
 fast_float_add_cpp_test(supported_chars_test)
 fast_float_add_cpp_test(example_test)
 fast_float_add_cpp_test(example_comma_test)
+fast_float_add_cpp_test(example_integer_times_pow10)
 fast_float_add_cpp_test(basictest)
 option(FASTFLOAT_CONSTEXPR_TESTS "Require constexpr tests (build will fail if the compiler won't support it)" OFF)
 if (FASTFLOAT_CONSTEXPR_TESTS)
diff --git a/tests/example_integer_times_pow10.cpp b/tests/example_integer_times_pow10.cpp
new file mode 100644
index 0000000..3e86826
--- /dev/null
+++ b/tests/example_integer_times_pow10.cpp
@@ -0,0 +1,12 @@
+#include "fast_float/fast_float.h"
+
+#include <iostream>
+
+int main() {
+  const uint64_t W = 12345678901234567;
+  const int Q = 23;
+  const double result = fast_float::integer_times_pow10(W, Q);
+  std::cout.precision(17);
+  std::cout << W << " * 10^" << Q << " = " << result << " ("
+            << (result == 12345678901234567e23 ? "==" : "!=") << "expected)\n";
+}