api_reference.adoc

API Reference

Namespaces

Namespace	Description
boost::int128	Contains all components of the library except <charconv> functionality
boost::int128::literals	User-defined literals for 128-bit integers
boost::charconv	to_chars and from_chars overloads for 128-bit integers (requires Boost.Charconv)

Types

Type	Description
uint128_t	Unsigned 128-bit integer
int128_t	Signed 128-bit integer

Literals

Literal	Description
_u128	Unsigned 128-bit literal (lowercase)
_U128	Unsigned 128-bit literal (uppercase)
_i128	Signed 128-bit literal (lowercase)
_I128	Signed 128-bit literal (uppercase)

Structures

Structure	Description
std::numeric_limits<uint128_t>	Numeric limits specialization for uint128_t
std::numeric_limits<int128_t>	Numeric limits specialization for int128_t
std::hash<uint128_t>	Hash specialization for uint128_t
std::hash<int128_t>	Hash specialization for int128_t
u128div_t	Result type for div(uint128_t, uint128_t)
i128div_t	Result type for div(int128_t, int128_t)

Functions

Listed by analogous STL header.

<bit>

Function	Description
has_single_bit	Checks if value is a power of two
countl_zero	Counts leading zeros
countl_one	Counts leading ones
bit_width	Returns minimum bits needed to represent value
bit_ceil	Rounds up to nearest power of two
bit_floor	Rounds down to nearest power of two
countr_zero	Counts trailing zeros
countr_one	Counts trailing ones
rotl	Rotates bits left
rotr	Rotates bits right
popcount	Counts number of set bits
byteswap	Reverses byte order

<charconv>

Function	Description
to_chars	Converts integer to character sequence
from_chars	Converts character sequence to integer

<cmath>

Function	Description
abs	Absolute value

<cstdlib>

Function	Description
div	Computes quotient and remainder simultaneously

<functional>

Specialization	Description
std::hash<uint128_t>	Enables uint128_t as a key in unordered associative containers
std::hash<int128_t>	Enables int128_t as a key in unordered associative containers

Formatting

Library	Description
<format>	C++20 std::format support
{fmt}	{fmt} library support

<iostream>

Operator	Description
operator<<	Stream insertion operator
operator>>	Stream extraction operator

<ios>

Manipulator	Description
std::oct	Octal output format
std::dec	Decimal output format
std::hex	Hexadecimal output format
std::uppercase	Uppercase hex digits
std::nouppercase	Lowercase hex digits

<numeric>

Function	Description
add_sat	Saturating addition
sub_sat	Saturating subtraction
mul_sat	Saturating multiplication
div_sat	Saturating division
saturate_cast	Saturating type cast
gcd	Greatest common divisor
lcm	Least common multiple
midpoint	Midpoint between two values

<string>

Function	Description
to_string	std::string conversion of base-10 values

Utilities

Function	Description
powm	Modular exponentiation (base ^ exp) mod m
ipow	Integer power base ^ exp (wraps modulo 2^128)
isqrt	Integer square root floor(sqrt(n))
ckd_add	Checked addition (C23 <stdckdint.h> contract)
ckd_sub	Checked subtraction (C23 <stdckdint.h> contract)
ckd_mul	Checked multiplication (C23 <stdckdint.h> contract)

Macros

Constants (<boost/int128/climits.hpp>)

Macro	Description
BOOST_INT128_UINT128_MAX	Maximum value for uint128_t
BOOST_INT128_INT128_MAX	Maximum value for int128_t
BOOST_INT128_INT128_MIN	Minimum value for int128_t

Literals

Macro	Description
BOOST_INT128_UINT128_C	Unsigned 128-bit constant macro
BOOST_INT128_INT128_C	Signed 128-bit constant macro

Configuration

User Configuration

Macro	Description
BOOST_INT128_NO_BUILTIN_INT128	Disables use of compiler built-in __int128
BOOST_INT128_DISABLE_EXCEPTIONS	Disables exception throwing
BOOST_INT128_ENABLE_CUDA	Enables CUDA support allowing the library types and functions to be run on both host and device

Automatic Configuration

Macro	Description
BOOST_INT128_HAS_INT128	Defined if compiler provides __int128
BOOST_INT128_ENDIAN_LITTLE_BYTE	Defined on little-endian systems
BOOST_INT128_ENDIAN_BIG_BYTE	Defined on big-endian systems
BOOST_INT128_HOST_DEVICE	Expands to __host__ __device__ under NVCC for CUDA support

Headers

Header	Contents
<boost/int128.hpp>	Convenience header including the entire library
<boost/int128/bit.hpp>	Bit manipulation functions
<boost/int128/charconv.hpp>	Character conversion functions
<boost/int128/climits.hpp>	Min and max macros
<boost/int128/cstdlib.hpp>	Combined division and modulo function
<boost/int128/fmt_format.hpp>	Formatting integration for {fmt}
<boost/int128/format.hpp>	Formatting integration for C++20 <format>
<boost/int128/hash.hpp>	std::hash specializations for int128_t and uint128_t
<boost/int128/int128.hpp>	The uint128_t and int128_t types
<boost/int128/iostream.hpp>	Iostream overloads for int128_t and uint128_t
<boost/int128/limits.hpp>	Overloads for std::numeric_limits for int128_t and uint128_t
<boost/int128/literals.hpp>	User-defined literals for int128_t and uint128_t
<boost/int128/numeric.hpp>	Numeric algorithms (gcd, lcm, midpoint)
<boost/int128/string.hpp>	to_string overloads
<boost/int128/random.hpp>	Required for usage of Boost.Random
<boost/int128/utilities.hpp>	Modular exponentiation and other library-specific utilities