Merge pull request #324 from cppalliance/317

Add `to_string` functions

Author: mborland

doc/modules/ROOT/nav.adoc

@@ -21,6 +21,7 @@
 *** xref:api_reference.adoc#api_iostream[`<iostream>`]
 *** xref:api_reference.adoc#api_ios[`<ios>`]
 *** xref:api_reference.adoc#api_numeric[`<numeric>`]
+*** xref:api_reference.adoc#api_string[`<string>`]
 ** xref:api_reference.adoc#api_macros[Macros]
 *** xref:api_reference.adoc#api_macro_literals[Literals]
 *** xref:api_reference.adoc#api_macro_configuration[Configuration]
@@ -47,6 +48,7 @@
 * xref:charconv.adoc[]
 * xref:stream.adoc[]
 * xref:numeric.adoc[]
+* xref:string.adoc[]
 * Benchmarks
 ** xref:u128_benchmarks.adoc[]
 *** xref:u128_benchmarks.adoc#u128_linux[Linux]

doc/modules/ROOT/pages/api_reference.adoc

@@ -244,6 +244,16 @@ Listed by analogous STL header.
 | Midpoint between two values
 |===
 
+[#api_string]
+=== xref:string.adoc[`<string>`]
+[cols="1,2", options="header"]
+|===
+| Function | Description
+
+| xref:string.adoc[`to_string`]
+| `std::string` conversion of base-10 values
+|===
+
 [#api_macros]
 == Macros
 

doc/modules/ROOT/pages/string.adoc

@@ -0,0 +1,34 @@
+////
+Copyright 2026 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#String]
+= `<string>`
+:idprefix: string_
+
+[source,c++]
+----
+#include <boost/int128/string.hpp>
+----
+
+The following are functions analogous to those found in `<string>` for builtin integer types.
+
+[source,c++]
+----
+#include <boost/int128/string.hpp>
+
+namespace boost {
+namespace int128 {
+
+inline std::string to_string(const int128_t& value);
+inline std::string to_string(const uint128_t& value);
+
+} // namespace int128
+} // namespace boost
+----
+
+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`.
+

include/boost/int128.hpp

@@ -14,5 +14,6 @@
 #include <boost/int128/limits.hpp>
 #include <boost/int128/climits.hpp>
 #include <boost/int128/cstdlib.hpp>
+#include <boost/int128/string.hpp>
 
 #endif // BOOST_INT128_HPP

include/boost/int128/string.hpp

@@ -0,0 +1,31 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#ifndef BOOST_INT128_STRING_HPP
+#define BOOST_INT128_STRING_HPP
+
+#include <boost/int128/int128.hpp>
+#include <boost/int128/detail/mini_to_chars.hpp>
+
+#ifndef BOOST_INT128_BUILD_MODULE
+
+#include <string>
+
+#endif
+
+namespace boost {
+namespace int128 {
+
+template <typename T>
+auto to_string(const T& value) -> std::enable_if_t<(std::is_same<T, int128_t>::value || std::is_same<T, uint128_t>::value), std::string>
+{
+    char buffer[64U] {};
+    const auto last {detail::mini_to_chars(buffer, value, 10, false)};
+    return std::string{last, buffer + sizeof(buffer)};
+}
+
+} // namespace int128
+} // namespace boost
+
+#endif // BOOST_INT128_STRING_HPP

test/Jamfile

@@ -85,6 +85,7 @@ run test_div.cpp ;
 
 run test_num_digits.cpp ;
 run test_spaceship_operator.cpp ;
+run test_to_string.cpp ;
 
 # Make sure we run the examples as well
 run ../examples/construction.cpp ;
@@ -122,3 +123,4 @@ compile compile_tests/iostream_compile.cpp ;
 compile compile_tests/limits_compile.cpp ;
 compile compile_tests/literals_compile.cpp ;
 compile compile_tests/numeric_compile.cpp ;
+compile compile_tests/string_compile.cpp ;

test/compile_tests/string_compile.cpp

@@ -0,0 +1,10 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/int128/string.hpp>
+
+int main()
+{
+    return 0;
+}

test/test_to_string.cpp

@@ -0,0 +1,101 @@
+// Copyright 2026 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/int128.hpp>
+#include <boost/int128/charconv.hpp>
+#include <boost/charconv.hpp>
+#include <boost/core/lightweight_test.hpp>
+#include <string>
+#include <limits>
+#include <array>
+#include <cstdint>
+
+using namespace boost::int128;
+
+template <typename T>
+void test()
+{
+    constexpr T min {std::numeric_limits<T>::min()};
+    constexpr T max {std::numeric_limits<T>::max()};
+    constexpr std::array<T, 4> values = {{ min, max, T{0}, T{42} }};
+
+    for (const auto value : values)
+    {
+        char buffer[64];
+        const auto r {boost::charconv::to_chars(buffer, buffer + sizeof(buffer), value, 10)};
+        BOOST_TEST(r);
+        *r.ptr = '\0';
+
+        const auto value_str {to_string(value)};
+
+        BOOST_TEST_CSTR_EQ(buffer, value_str.c_str());
+    }
+}
+
+template <typename T, std::enable_if_t<std::is_signed<T>::value, bool> = true>
+void test_builtin()
+{
+    constexpr T min {std::numeric_limits<T>::min()};
+    constexpr T max {std::numeric_limits<T>::max()};
+    constexpr std::array<T, 4> values = {{ min, max, T{0}, T{42} }};
+
+    for (const auto value : values)
+    {
+        char buffer[64];
+        const auto r {boost::charconv::to_chars(buffer, buffer + sizeof(buffer), value, 10)};
+        BOOST_TEST(r);
+        *r.ptr = '\0';
+
+        const auto value_str {to_string(int128_t{value})};
+
+        BOOST_TEST_CSTR_EQ(buffer, value_str.c_str());
+        BOOST_TEST_CSTR_EQ(std::to_string(value).c_str(), value_str.c_str());
+    }
+}
+
+template <typename T, std::enable_if_t<std::is_unsigned<T>::value, bool> = true>
+void test_builtin()
+{
+    constexpr T min {std::numeric_limits<T>::min()};
+    constexpr T max {std::numeric_limits<T>::max()};
+    constexpr std::array<T, 4> values = {{ min, max, T{0}, T{42} }};
+
+    for (const auto value : values)
+    {
+        char buffer[64];
+        const auto r {boost::charconv::to_chars(buffer, buffer + sizeof(buffer), value, 10)};
+        BOOST_TEST(r);
+        *r.ptr = '\0';
+
+        {
+            const auto value_str {to_string(int128_t{value})};
+
+            BOOST_TEST_CSTR_EQ(buffer, value_str.c_str());
+            BOOST_TEST_CSTR_EQ(std::to_string(value).c_str(), value_str.c_str());
+        }
+        {
+            const auto value_str {to_string(uint128_t{value})};
+
+            BOOST_TEST_CSTR_EQ(buffer, value_str.c_str());
+            BOOST_TEST_CSTR_EQ(std::to_string(value).c_str(), value_str.c_str());
+        }
+    }
+}
+
+int main()
+{
+    test<uint128_t>();
+    test<int128_t>();
+
+    test_builtin<std::int8_t>();
+    test_builtin<std::uint8_t>();
+    test_builtin<std::int16_t>();
+    test_builtin<std::uint16_t>();
+    test_builtin<std::int32_t>();
+    test_builtin<std::uint32_t>();
+    test_builtin<std::int64_t>();
+    test_builtin<std::uint64_t>();
+
+    return boost::report_errors();
+}