Integer Overflow Behaviors in absl::numeric for 128-Bit Types

Abseil's 128-bit integer types (absl::int128 and absl::uint128) implement deterministic wrap-around semantics using modular arithmetic on a 128-bit two's-complement representation, avoiding the undefined behavior of native signed integers.

The abseil/abseil-cpp library provides portable, high-precision integer types that behave predictably under overflow conditions. Unlike standard C++ signed integers where overflow is undefined behavior, the absl::numeric module defines explicit modular arithmetic semantics for absl::int128 and absl::uint128, making them suitable for cryptographic, financial, and systems programming applications.

Addition and Subtraction Overflow Semantics

In absl/numeric/int128.h, the operator+ and operator- implementations compute results using modular arithmetic on the underlying 128-bit representation. When the mathematically exact result exceeds the representable range of [-2¹²⁷, 2¹²⁷-1] for signed types or [0, 2¹²⁸-1] for unsigned types, the value wraps around by keeping only the low 128 bits.

This behavior matches unsigned integer arithmetic and eliminates undefined behavior. For example, adding 1 to the maximum positive int128 value produces the minimum negative value:

#include "absl/numeric/int128.h"

absl::int128 max_val = (absl::int128{1} << 127) - 1;  // INT128_MAX
absl::int128 result = max_val + 1;                    // Wraps to INT128_MIN

Multiplication and Division Behaviors

Multiplication (operator*) performs full 128-bit precision calculations in absl/numeric/int128.cc. The product is reduced modulo 2¹²⁸, causing overflow to wrap in the same manner as addition. The implementation delegates to either compiler intrinsics (__int128) or fallback logic in absl/numeric/int128_have_intrinsic.inc and absl/numeric/int128_no_intrinsic.inc, ensuring consistent semantics across platforms.

Division and remainder (operator/, operator%) follow standard Euclidean division semantics. These operations cannot overflow because the absolute value of the quotient never exceeds the absolute value of the dividend. However, division by zero triggers a SIGFPE signal, consistent with built-in integer types.

Unary Negation and INT128_MIN

The negation operator (operator-) implements two's-complement negation as (~x) + 1. A critical edge case occurs with the most-negative value (INT128_MIN = -2¹²⁷). Negating this value returns itself due to wrap-around, a well-defined behavior in the Abseil implementation:

absl::int128 min_val = -(absl::int128{1} << 127);  // INT128_MIN
absl::int128 neg = -min_val;                       // Still INT128_MIN

Shift Operation Overflow Handling

Bitwise shift operations in absl::int128 follow specific masking rules defined in absl/numeric/internal/representation.h. The implementation defines shift counts only for the range [0, 127].

• Left shifts (<<) by amounts >= 128 yield zero (bits shifted beyond position 127 are discarded).
• Right shifts (>>) by amounts >= 128 perform sign-extension for signed types or zero-fill for unsigned types.

This mirrors the behavior of underlying compiler intrinsics while ensuring portability when intrinsics are unavailable.

Explicit Overflow Detection Helpers

When overflow detection is required rather than wrap-around semantics, Abseil provides checked arithmetic functions. These include:

• absl::numeric::AddOverflow()
• absl::numeric::MulOverflow()
• absl::numeric::SubOverflow()

These functions accept output pointers and return a bool indicating whether the operation overflowed the 128-bit range. In absl/numeric/int128.cc, these helpers perform the arithmetic operation and compare the result against the expected mathematical bounds to detect wrap-around conditions.

Implementation Architecture

The overflow semantics are guaranteed by the internal implementation files:

• absl/numeric/int128.h: Declares the public API, including absl::int128 and absl::uint128 classes with arithmetic operators.
• absl/numeric/int128.cc: Implements the arithmetic logic, handling overflow through unsigned arithmetic casts before converting back to signed types.
• absl/numeric/internal/representation.h: Selects between native __int128 compiler support or the fallback implementation.
• absl/numeric/int128_have_intrinsic.inc: Optimized path using compiler intrinsics when __int128 is available.
• absl/numeric/int128_no_intrinsic.inc: Portable fallback using 64-bit limb emulation that manually implements modular arithmetic.

All implementations deliberately avoid undefined signed-overflow by performing operations in unsigned space and casting results back, ensuring portable wrap-around behavior.

Practical Examples of 128-Bit Overflow

#include "absl/numeric/int128.h"
#include <iostream>

int main() {
  // Construct boundary values
  absl::int128 max = (absl::int128{1} << 127) - 1;
  absl::int128 min = -max - 1;
  
  // Demonstrate wrap-around addition
  absl::int128 overflow = max + 1;  // Results in min value
  
  // Multiplication overflow
  absl::int128 a = absl::int128{1} << 100;
  absl::int128 b = absl::int128{1} << 30;
  absl::int128 prod = a * b;        // Wraps to 2^2 (low 128 bits kept)
  
  // Explicit overflow detection
  bool did_overflow = false;
  absl::int128 sum = absl::numeric::AddOverflow(max, absl::int128{10}, &did_overflow);
  if (did_overflow) {
    // Handle overflow case
  }
  
  // Conversion truncation
  int64_t narrow = static_cast<int64_t>(max);  // Keeps low 64 bits only
}

Summary

• Modular arithmetic: All arithmetic operations on absl::int128 and absl::uint128 wrap around on overflow, preserving only the low 128 bits.
• Defined negation: Negating INT128_MIN produces INT128_MIN without undefined behavior.
• Shift masking: Shifts >= 128 bits yield zero or sign-extended results, not undefined behavior.
• Detection API: Use absl::numeric::AddOverflow() and related functions when you need to detect rather than wrap.
• Portable implementation: Files like absl/numeric/int128.cc and absl/numeric/internal/representation.h ensure consistent semantics across compilers with or without native __int128 support.

Frequently Asked Questions

What happens when absl::int128 overflows during addition?

Addition overflow results in wrap-around using modular arithmetic. The calculation keeps only the low 128 bits of the mathematical sum, effectively operating modulo 2¹²⁸. This is well-defined behavior, unlike standard C++ signed integers where overflow is undefined.

Does absl::int128 detect overflow automatically?

No, absl::int128 does not throw exceptions or trap on overflow by default—it silently wraps. To detect overflow, you must use the explicit checking functions absl::numeric::AddOverflow() or absl::numeric::MulOverflow(), which return a boolean indicating whether the operation exceeded the representable range.

How does Abseil implement 128-bit integers on platforms without native support?

Abseil uses a fallback implementation in absl/numeric/int128_no_intrinsic.inc that represents the 128-bit value as two 64-bit limbs. Arithmetic operations are implemented using unsigned 64-bit operations with manual carry propagation, ensuring the same modular overflow semantics as the intrinsic-based implementation in absl/numeric/int128_have_intrinsic.inc.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}