diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index ae2c1c61..f1b1df9b 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/doc/modules/ROOT/nav.adoc @@ -6,7 +6,7 @@ ** xref:examples.adoc#examples_rollover[Rollover Behavior] ** xref:examples.adoc#examples_bit[`` support] ** xref:examples.adoc#examples_numeric[`` support (Saturating Arithmetic)] -** xref:examples.adoc#examples_numeric[`` support (Numeric Logarithms)] +** xref:examples.adoc#examples_numeric_algorithms[`` support (Numeric Algorithms)] ** 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] diff --git a/doc/modules/ROOT/pages/api_reference.adoc b/doc/modules/ROOT/pages/api_reference.adoc index 3ef06c21..af870252 100644 --- a/doc/modules/ROOT/pages/api_reference.adoc +++ b/doc/modules/ROOT/pages/api_reference.adoc @@ -20,6 +20,9 @@ https://www.boost.org/LICENSE_1_0.txt | xref:literals.adoc[`boost::int128::literals`] | User-defined literals for 128-bit integers + +| xref:charconv.adoc[`boost::charconv`] +| `to_chars` and `from_chars` overloads for 128-bit integers (requires Boost.Charconv) |=== [#api_types] @@ -146,7 +149,7 @@ Listed by analogous STL header. |=== | Function | Description -| `abs` +| xref:int128_t.adoc#i128_math_operators[`abs`] | Absolute value |=== @@ -359,8 +362,8 @@ Listed by analogous STL header. | xref:format.adoc#std_format[``] | Formatting integration for pass:[C++20] `` -| xref:uint128_t.adoc[``] -| The `int128_t` and `uint128_t` types +| `` +| The xref:uint128_t.adoc[`uint128_t`] and xref:int128_t.adoc[`int128_t`] types | xref:stream.adoc[``] | Iostream overloads for `int128_t` and `uint128_t` diff --git a/doc/modules/ROOT/pages/config.adoc b/doc/modules/ROOT/pages/config.adoc index cbc57dc4..c9f0b9f8 100644 --- a/doc/modules/ROOT/pages/config.adoc +++ b/doc/modules/ROOT/pages/config.adoc @@ -19,7 +19,7 @@ These macros allow customization of library behavior. User-configurable macros s [#enable_cuda] - `BOOST_INT128_ENABLE_CUDA`: Defining this macro allows both types and selected functions to be run on both host and device when compiling with NVCC. -Allowed functions have `BOOST_IN128_HOST_DEVICE` as part of their function signature in their documentation. +Allowed functions have `BOOST_INT128_HOST_DEVICE` as part of their function signature in their documentation. [#no_int128] - `BOOST_INT128_NO_BUILTIN_INT128`: The user may define this when they do not want the internal implementations to rely on builtin `pass:[__int128]` or `pass:[unsigned __int128]` types. diff --git a/doc/modules/ROOT/pages/examples.adoc b/doc/modules/ROOT/pages/examples.adoc index 2db70e47..7a8a4693 100644 --- a/doc/modules/ROOT/pages/examples.adoc +++ b/doc/modules/ROOT/pages/examples.adoc @@ -304,7 +304,7 @@ signed_value / 4U = 0 include::example$math_and_random.cpp[] ---- -.Expected Output +.Example Output (values vary per run) [listing] ---- === uint128_t === diff --git a/doc/modules/ROOT/pages/file_structure.adoc b/doc/modules/ROOT/pages/file_structure.adoc index c2d645a3..84c6765f 100644 --- a/doc/modules/ROOT/pages/file_structure.adoc +++ b/doc/modules/ROOT/pages/file_structure.adoc @@ -16,22 +16,25 @@ The entire library can be consumed via ``, or by independently | Header | Description | `` -| The complete library (includes all headers below) +| Convenience header (includes most headers below; does not include `charconv.hpp`, `fmt_format.hpp`, or `random.hpp`) | xref:bit.adoc[``] | Bit manipulation functions | xref:charconv.adoc[``] -| Character conversion (`to_chars`/`from_chars`) +| Character conversion (`to_chars`/`from_chars`); requires Boost.Charconv headers | xref:api_reference.adoc#api_macro_literals[``] | C-style limit macros (`BOOST_INT128_INT128_MAX`, etc.) +| xref:config.adoc[``] +| Configuration macros + | xref:cstdlib.adoc[``] | Division with quotient and remainder (`div`) | xref:format.adoc[``] -| `pass:[{fmt}]` library support +| `pass:[{fmt}]` library support; requires the `pass:[{fmt}]` library | xref:format.adoc[``] | C++20 `std::format` support @@ -50,4 +53,10 @@ The entire library can be consumed via ``, or by independently | xref:numeric.adoc[``] | Numeric functions (`gcd`, `lcm`, saturating arithmetic) + +| `` +| Traits for usage with Boost.Random + +| xref:string.adoc[``] +| `to_string` overloads |=== diff --git a/doc/modules/ROOT/pages/format.adoc b/doc/modules/ROOT/pages/format.adoc index 40304463..c257cf58 100644 --- a/doc/modules/ROOT/pages/format.adoc +++ b/doc/modules/ROOT/pages/format.adoc @@ -37,7 +37,7 @@ Examples: | `{:*^6d}` | `"**42**"` (centered with asterisks) |=== -NOTE: When no alignment is specified but a width is given (e.g., `{:6d}`), zero-padding is applied from the left. +NOTE: When no alignment is specified but a `0` prefix and width are given (e.g., `{:06d}`), zero-padding is applied from the left. Without the `0` prefix (e.g., `{:6d}`), space-padding is applied instead, matching `std::format` behavior. == Sign diff --git a/doc/modules/ROOT/pages/i128_benchmarks.adoc b/doc/modules/ROOT/pages/i128_benchmarks.adoc index 1914394d..915e1be5 100644 --- a/doc/modules/ROOT/pages/i128_benchmarks.adoc +++ b/doc/modules/ROOT/pages/i128_benchmarks.adoc @@ -12,7 +12,7 @@ https://www.boost.org/LICENSE_1_0.txt The benchmarks below represent the time in microseconds it takes to perform 20'000'000 operations between two values of random width (e.g. 2x1 words, 1x2 words, etc.). On most platforms we use the builtin `\__int128` as the reference benchmark. -When this is unavailable (such as on 32-bit architectures) we us `boost::multiprecision::int128_t` (abbreviated as `boost::mp::int128_t`) as it is widely used, and known to be portable. +When this is unavailable (such as on 32-bit architectures) we use `boost::multiprecision::int128_t` (abbreviated as `boost::mp::int128_t`) as it is widely used, and known to be portable. On MSVC platforms we use as reference `std::_Signed128` from the header `<__msvc_int128.hpp>` since this is bundled with their compiler. [#i128_linux] @@ -56,7 +56,7 @@ image::i128_graphs/linux/x64_relative_performance.png[x64 Relative Performance, image::i128_graphs/linux/ARM64_benchmarks.png[ARM64 Benchmark Results, width=100%] //// -image::i128_graphs/linux/ARM64_relative_performance.png[x64 Relative Performance, width=100%] +image::i128_graphs/linux/ARM64_relative_performance.png[ARM64 Relative Performance, width=100%] === S390x diff --git a/doc/modules/ROOT/pages/mixed_type_ops.adoc b/doc/modules/ROOT/pages/mixed_type_ops.adoc index 961490c8..38d2e356 100644 --- a/doc/modules/ROOT/pages/mixed_type_ops.adoc +++ b/doc/modules/ROOT/pages/mixed_type_ops.adoc @@ -110,7 +110,7 @@ BOOST_INT128_HOST_DEVICE constexpr bool operator!=(uint128_t lhs, int128_t rhs); BOOST_INT128_HOST_DEVICE constexpr bool operator!=(int128_t lhs, uint128_t rhs); ---- -If the `int128_t` argument is less than 0 returns `false`. +If the `int128_t` argument is less than 0 returns `true`. Otherwise, returns the same as `static_cast(lhs) != static_cast(rhs)`. === Less Than @@ -152,7 +152,7 @@ If `lhs` is type `int128_t` returns `false` if `lhs < 0` If `rhs` is type `int128_t` returns `true` if `rhs < 0` Otherwise, returns the same as `static_cast(lhs) > static_cast(rhs)`. -=== Less Than or Equal To +=== Greater Than or Equal To [source, c++] ---- @@ -167,7 +167,7 @@ Otherwise, returns the same as `static_cast(lhs) pass:[>=] static_cas == Arithmetic -If you define xref:config.adoc#sign_compare[`BOOST_INT128_ALLOW_SIGN_CONVERSION`], the operators have the following behavior. +If you define xref:config.adoc#sign_conversion[`BOOST_INT128_ALLOW_SIGN_CONVERSION`], the operators have the following behavior. === Addition diff --git a/doc/modules/ROOT/pages/numeric.adoc b/doc/modules/ROOT/pages/numeric.adoc index af0fb9b3..432044c0 100644 --- a/doc/modules/ROOT/pages/numeric.adoc +++ b/doc/modules/ROOT/pages/numeric.adoc @@ -57,8 +57,11 @@ Should the `TargetIntegerType` not be able to represent the value of the `Librar namespace boost { namespace int128 { -constexpr -BOOST_INT128_HOST_DEVICE constexpr TargetIntegerType saturate_cast(LibraryIntegerType x) noexcept; +template +BOOST_INT128_HOST_DEVICE constexpr TargetType saturate_cast(uint128_t value) noexcept; + +template +BOOST_INT128_HOST_DEVICE constexpr TargetType saturate_cast(int128_t value) noexcept; } // namespace int128 } // namespace boost diff --git a/doc/modules/ROOT/pages/overview.adoc b/doc/modules/ROOT/pages/overview.adoc index 42d208ce..bf37e313 100644 --- a/doc/modules/ROOT/pages/overview.adoc +++ b/doc/modules/ROOT/pages/overview.adoc @@ -24,8 +24,8 @@ When using pass:[C++20] or newer, the library can be consumed as a module `impor GCC and Clang offer `__int128` as a non-standard extension on 64-bit targets, but it lacks `std::numeric_limits` specializations, `` support, and is absent entirely on MSVC. Multiprecision libraries can fill the gap, but typically at the cost of a larger `sizeof` and additional overhead (e.g., Boost.Multiprecision always has an extra word). Boost.Int128 solves this by providing types that are exactly 128-bits on every platform. -Operation implementations rely on compiler intrinsic where available for native performance, and optimized software implementations elsewhere. -The types provided by the library also have native support being running on GPU using CUDA, along with many of the functions. +Operation implementations rely on compiler intrinsics where available for native performance, and optimized software implementations elsewhere. +The types provided by the library also natively support running on GPUs using CUDA, along with many of the functions. == Use Cases diff --git a/doc/modules/ROOT/pages/u128_benchmarks.adoc b/doc/modules/ROOT/pages/u128_benchmarks.adoc index fabf1463..88f9a03b 100644 --- a/doc/modules/ROOT/pages/u128_benchmarks.adoc +++ b/doc/modules/ROOT/pages/u128_benchmarks.adoc @@ -12,7 +12,7 @@ https://www.boost.org/LICENSE_1_0.txt The benchmarks below represent the time in microseconds it takes to perform 20'000'000 operations between two values of random width (e.g. 2x1 words, 1x2 words, etc.). On most platforms we use the builtin `unsigned \__int128` as the reference benchmark. -When this is unavailable (such as on 32-bit architectures) we us `boost::multiprecision::uint128_t` (abbreviated as `boost::mp::uint128_t`) as it is widely used, and known to be portable. +When this is unavailable (such as on 32-bit architectures) we use `boost::multiprecision::uint128_t` (abbreviated as `boost::mp::uint128_t`) as it is widely used, and known to be portable. On MSVC platforms we use as reference `std::_Unsigned128` from the header `<__msvc_int128.hpp>` since this is bundled with their compiler. [#u128_linux] @@ -56,7 +56,7 @@ image::u128_graphs/linux/x64_relative_performance.png[x64 Relative Performance, image::u128_graphs/linux/ARM64_benchmarks.png[ARM64 Benchmark Results, width=100%] //// -image::u128_graphs/linux/ARM64_relative_performance.png[x64 Relative Performance, width=100%] +image::u128_graphs/linux/ARM64_relative_performance.png[ARM64 Relative Performance, width=100%] === S390x @@ -232,12 +232,12 @@ image::u128_graphs/macos/ARM64_relative_performance.png[ARM64 Relative Performan |=== | Operation | `unsigned __int128` | `uint128_t` | `boost::mp::uint128_t` -| Comparisons | 131902 | 133564 | 134182 -| Addition | 20613 | 17912 | 40176 -| Subtraction | 20484 | 18237 | 40311 -| Multiplication | 20160 | 20580 | 43285 -| Division | 686521 | 699201 | 945928 -| Modulo | 777084 | 724648 | 953117 +| Comparisons | 688225 | 712352 | 689146 +| Addition | 104921 | 124992 | 137819 +| Subtraction | 129150 | 102302 | 153484 +| Multiplication | 120363 | 119652 | 164100 +| Division | 2333812 | 1981469 | 2784139 +| Modulo | 2621949 | 2219481 | 2736682 |=== //// diff --git a/doc/modules/ROOT/pages/uint128_t.adoc b/doc/modules/ROOT/pages/uint128_t.adoc index efe7d742..88802b2c 100644 --- a/doc/modules/ROOT/pages/uint128_t.adoc +++ b/doc/modules/ROOT/pages/uint128_t.adoc @@ -405,18 +405,18 @@ This operation is subject to mixed sign limitations discussed xref:uint128_t.ado [source, c++] ---- template -BOOST_INT128_HOST_DEVICE constexpr uint128_t operator<<(const uint128_t lhs, const Integer rhs) noexcept; +BOOST_INT128_HOST_DEVICE constexpr uint128_t operator>>(const uint128_t lhs, const Integer rhs) noexcept; template ::value && (sizeof(Integer) * 8 > 16), bool> = true> -BOOST_INT128_HOST_DEVICE constexpr Integer operator<<(const Integer lhs, const uint128_t rhs) noexcept; +BOOST_INT128_HOST_DEVICE constexpr Integer operator>>(const Integer lhs, const uint128_t rhs) noexcept; template && (sizeof(SignedInteger) * 8 <= 16), bool> = true> -BOOST_INT128_HOST_DEVICE constexpr int operator<<(const SignedInteger lhs, const uint128_t rhs) noexcept; +BOOST_INT128_HOST_DEVICE constexpr int operator>>(const SignedInteger lhs, const uint128_t rhs) noexcept; template && (sizeof(UnsignedInteger) * 8 <= 16), bool> = true> -BOOST_INT128_HOST_DEVICE constexpr unsigned int operator<<(const UnsignedInteger lhs, const uint128_t rhs) noexcept; +BOOST_INT128_HOST_DEVICE constexpr unsigned int operator>>(const UnsignedInteger lhs, const uint128_t rhs) noexcept; -BOOST_INT128_HOST_DEVICE constexpr uint128_t operator<<(const uint128_t lhs, const uint128_t rhs) noexcept; +BOOST_INT128_HOST_DEVICE constexpr uint128_t operator>>(const uint128_t lhs, const uint128_t rhs) noexcept; ---- Returns the bitwise right shift of `lhs` without exception.