Add example of new to_string method

doc/modules/ROOT/nav.adoc

@@ -8,6 +8,7 @@
 ** xref:examples.adoc#examples_numeric[`<numeric>` support (Saturating Arithmetic)]
 ** xref:examples.adoc#examples_numeric[`<numeric>` support (Numeric Logarithms)]
 ** xref:examples.adoc#examples_mixed_sign[Mixed Signedness Arithmetic]
+** xref:examples.adoc#examples_to_string[String Conversion (to_string)]
 ** xref:examples.adoc#examples_boost_math_random[Boost Math and Random Integration]
 ** xref:examples.adoc#examples_boost_charconv[Boost.Charconv Integration]
 ** xref:examples.adoc#examples_cstdlib[`<cstdlib>` support (Combined div and mod)]

doc/modules/ROOT/pages/examples.adoc

@@ -336,6 +336,44 @@ Parsed hex "DEADBEEFCAFEBABE12345678"
 ----
 ====
 
+[#examples_to_string]
+== String Conversion (to_string)
+
+.This https://github.com/cppalliance/int128/blob/develop/examples/to_string.cpp[example] demonstrates to_string for 128-bit integers, comparing results against std::to_string for values that fit in 64 bits
+====
+[source, c++]
+----
+include::example$to_string.cpp[]
+----
+
+.Expected Output
+[listing]
+----
+=== to_string with uint128_t ===
+uint128_t to_string(1234567890): 1234567890
+std::to_string(uint64_t 1234567890): 1234567890
+Match: true
+
+uint128_t to_string(UINT64_MAX): 18446744073709551615
+std::to_string(UINT64_MAX):      18446744073709551615
+Match: true
+
+uint128_t max: 340282366920938463463374607431768211455
+
+=== to_string with int128_t ===
+int128_t to_string(-42): -42
+std::to_string(int64_t -42): -42
+Match: true
+
+int128_t to_string(INT64_MAX): 9223372036854775807
+std::to_string(INT64_MAX):     9223372036854775807
+Match: true
+
+int128_t min: -170141183460469231731687303715884105728
+int128_t max: 170141183460469231731687303715884105727
+----
+====
+
 [#examples_fmt_format]
 == \{fmt} Library Integration
 

doc/modules/ROOT/pages/string.adoc

@@ -32,3 +32,4 @@ inline std::string to_string(const uint128_t& value);
 Returns a `std::string` containing the decimal(base-10) representation of `value`.
 These functions may throw `std::bad_alloc` from the constructor of `std::string`.
 
+An example of how to use these functions is available xref:examples.adoc#examples_to_string[on the examples page.]

examples/to_string.cpp

@@ -0,0 +1,65 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/int128/int128.hpp>
+#include <boost/int128/string.hpp>
+#include <boost/int128/literals.hpp>
+#include <iostream>
+#include <string>
+#include <cstdint>
+
+int main()
+{
+    using boost::int128::uint128_t;
+    using boost::int128::int128_t;
+    using boost::int128::to_string;
+    using namespace boost::int128::literals;
+
+    std::cout << "=== to_string with uint128_t ===" << std::endl;
+
+    // Compare against std::to_string for values that fit in 64 bits
+    constexpr uint128_t u_small {UINT64_C(1234567890)};
+    const auto u_small_str {to_string(u_small)};
+    const auto u_small_std {std::to_string(std::uint64_t{1234567890})};
+    std::cout << "uint128_t to_string(1234567890): " << u_small_str << std::endl;
+    std::cout << "std::to_string(uint64_t 1234567890): " << u_small_std << std::endl;
+    std::cout << "Match: " << std::boolalpha << (u_small_str == u_small_std) << std::endl;
+
+    constexpr uint128_t u_max64 {UINT64_MAX};
+    const auto u_max64_str {to_string(u_max64)};
+    const auto u_max64_std {std::to_string(UINT64_MAX)};
+    std::cout << "\nuint128_t to_string(UINT64_MAX): " << u_max64_str << std::endl;
+    std::cout << "std::to_string(UINT64_MAX):      " << u_max64_std << std::endl;
+    std::cout << "Match: " << (u_max64_str == u_max64_std) << std::endl;
+
+    // Values beyond 64-bit range
+    const auto large_unsigned {"340282366920938463463374607431768211455"_U128};
+    std::cout << "\nuint128_t max: " << to_string(large_unsigned) << std::endl;
+
+    std::cout << "\n=== to_string with int128_t ===" << std::endl;
+
+    // Compare against std::to_string for values that fit in 64 bits
+    constexpr int128_t s_negative {-42};
+    const auto s_neg_str {to_string(s_negative)};
+    const auto s_neg_std {std::to_string(std::int64_t{-42})};
+    std::cout << "int128_t to_string(-42): " << s_neg_str << std::endl;
+    std::cout << "std::to_string(int64_t -42): " << s_neg_std << std::endl;
+    std::cout << "Match: " << (s_neg_str == s_neg_std) << std::endl;
+
+    constexpr int128_t s_large {INT64_MAX};
+    const auto s_large_str {to_string(s_large)};
+    const auto s_large_std {std::to_string(INT64_MAX)};
+    std::cout << "\nint128_t to_string(INT64_MAX): " << s_large_str << std::endl;
+    std::cout << "std::to_string(INT64_MAX):     " << s_large_std << std::endl;
+    std::cout << "Match: " << (s_large_str == s_large_std) << std::endl;
+
+    // Values beyond 64-bit range
+    const auto large_negative {"-170141183460469231731687303715884105728"_i128};
+    std::cout << "\nint128_t min: " << to_string(large_negative) << std::endl;
+
+    const auto large_positive {"170141183460469231731687303715884105727"_I128};
+    std::cout << "int128_t max: " << to_string(large_positive) << std::endl;
+
+    return 0;
+}

include/boost/int128/string.hpp

@@ -22,7 +22,7 @@ auto to_string(const T& value) -> std::enable_if_t<(std::is_same<T, int128_t>::v
 {
     char buffer[64U] {};
     const auto last {detail::mini_to_chars(buffer, value, 10, false)};
-    return std::string{last, buffer + sizeof(buffer)};
+    return std::string{last};
 }
 
 } // namespace int128

test/Jamfile

@@ -100,6 +100,7 @@ run ../examples/fmt_format.cpp ;
 run ../examples/cstdlib.cpp ;
 run ../examples/numeric_algorithms.cpp ;
 run ../examples/rollover.cpp ;
+run ../examples/to_string.cpp ;
 
 run limits_link_1.cpp limits_link_2.cpp limits_link_3.cpp ;