Design Decisions

The central design goal is that sizeof(uint128_t) and sizeof(int128_t) are exactly 16 bytes on every supported platform. The compiler’s __int128 extension is only available on some 64-bit targets and is absent on MSVC, while multiprecision types typically carry an additional word of bookkeeping. By fixing the layout at two 64-bit words, the library provides a drop-in 128-bit integer whose size and alignment match a built-in type where one exists. See Comparison to Boost.Multiprecision for the tradeoffs relative to a multiprecision number.

Where the compiler provides a native 128-bit integer or a suitable intrinsic, the operators forward to it for native performance. Elsewhere (including MSVC and 32-bit targets) the library uses optimized software implementations over the two 64-bit words. This keeps behavior and results identical across platforms while still taking advantage of hardware support when it is present.

The library targets C++14 as its minimum standard. Relaxed C++14 constexpr allows nearly all functionality to be evaluated at compile time, so the types can be used in constant expressions much like a built-in integer. Meeting the C++14 bar also satisfies the conceptual requirements of libraries such as Boost.Math and Boost.Random, which this library integrates with directly.

To behave like a built-in integer in generic code, the types provide implicit conversions to and from the built-in integer and floating-point types, and implicit conversion between int128_t and uint128_t. The single exception is operator bool, which is explicit to match the standard library convention and to avoid unintended participation in arithmetic and overload resolution.

Mixed-sign and mixed-width operations follow the usual arithmetic conversions of the language. In particular, an operation mixing a signed and an unsigned 128-bit operand produces a uint128_t, identical to the value the equivalent built-in unsigned __int128 operation would produce, with two’s-complement wrap-around. See Mixed Type Operations for the complete result-type rules.

Each type is a struct of two 64-bit words, low and high, whose declaration order depends on the endianness of the target so that the in-memory representation matches a native 128-bit integer. For int128_t the high word is signed. When a native 128-bit type is available the struct is over-aligned to match it, except on 32-bit x86 where the native alignment is not forced.

The types and many of the free functions are annotated with BOOST_INT128_HOST_DEVICE so they can be used unchanged in CUDA device code when the library is compiled with BOOST_INT128_ENABLE_CUDA. See Configuration Macros.