Int128.h File Reference

Cross-platform 128-bit integer arithmetic type. More...

#include <array>
#include <compare>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include "nfx/detail/datatypes/CompilerSupport.h"
#include "nfx/detail/datatypes/Int128.inl"

Include dependency graph for Int128.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	nfx::datatypes::Int128
	Cross-platform 128-bit signed integer type. More...

Functions
Int128	nfx::datatypes::abs (const Int128 &value) noexcept
	Get absolute value of Int128 (free function).
Int128	nfx::datatypes::isqrt (const Int128 &value)
	Calculate integer square root (free function).
Decimal	nfx::datatypes::sqrt (const Int128 &value)
	Calculate square root of Int128 value with high precision.

Detailed Description

Cross-platform 128-bit integer arithmetic type.

Provides portable 128-bit signed integer operations with native __int128 on GCC/Clang and manual implementation on MSVC

Integration with Decimal:

• Optimized for mantissa storage and manipulation in Decimal class
• Efficient conversion between 96-bit decimal mantissa and 128-bit integer

Memory Layout and Internal Representation:

1. GCC/Clang with native __int128 support (NFX_DATATYPES_HAS_NATIVE_INT128=1):

   ┌─────────────────────────────────────────────────────────────────┐
   │                     Native __int128                             │
   │                        (16 bytes)                               │
   └─────────────────────────────────────────────────────────────────┘
   Bit 127                                                       Bit 0

2. MSVC and other compilers (NFX_DATATYPES_HAS_NATIVE_INT128=0):

   ┌─────────────────────────────────┬─────────────────────────────────┐
   │          upper64bits            │          lower64bits            │
   │       (most significant)        │       (least significant)       │
   │           8 bytes               │           8 bytes               │
   └─────────────────────────────────┴─────────────────────────────────┘
   Bit 127                     Bit 64 Bit 63                       Bit 0

Bit Layout and Sign Representation:

The 128-bit signed integer uses two's complement representation:

┌─┬───────────────────────────────────────────────────────────────────┐
│S│                    Value Bits (127 bits)                          │
└─┴───────────────────────────────────────────────────────────────────┘
Bit 127                                                           Bit 0

Where:

• S (bit 127): Sign bit (0 = positive, 1 = negative)
• Bits 126-0: Magnitude in two's complement form

Value Range:

• Minimum: -2^127 = -170,141,183,460,469,231,731,687,303,715,884,105,728
• Maximum: 2^127-1 = 170,141,183,460,469,231,731,687,303,715,884,105,727

Examples with Memory Layout:

Example 1: Small positive number (42)

• Decimal: 42
• Hex: 0x0000000000000000000000000000002A
• Memory layout (little-endian on x86-64):
  • upper64bits: 0x0000000000000000
  • lower64bits: 0x000000000000002A
• Bit pattern: 0000...00101010 (127 zeros followed by 101010)

Example 2: Large positive number (12,345,678,901,234,567,890)

• Decimal: 12,345,678,901,234,567,890
• Hex: 0x00000000000000000AB54A98CEB1F0D2
• Memory layout:
  • upper64bits: 0x0000000000000000
  • lower64bits: 0x0AB54A98CEB1F0D2
• Bit breakdown:
  • Bits 127-64: All zeros (positive number, high bits unused)
  • Bits 63-0: 0x0AB54A98CEB1F0D2 = 12,345,678,901,234,567,890

Example 3: Very large number requiring full 128 bits

• Decimal: 123,456,789,012,345,678,901,234,567,890,123,456,789
• Hex: 0x0173DC35270122E8EBC2CE4F3C95D6F5
• Memory layout:
  • upper64bits: 0x0173DC35270122E8
  • lower64bits: 0xEBC2CE4F3C95D6F5
• Bit breakdown:
  • Bits 127-64: 0x0173DC35270122E8 = 1,662,554,368,463,341,288
  • Bits 63-0: 0xEBC2CE4F3C95D6F5 = 17,034,473,836,310,554,357
  • Full value: (1,662,554,368,463,341,288 << 64) + 17,034,473,836,310,554,357

Example 4: Negative number (-42)

• Decimal: -42
• Two's complement hex: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD6
• Memory layout:
  • upper64bits: 0xFFFFFFFFFFFFFFFF
  • lower64bits: 0xFFFFFFFFFFFFFFD6
• Bit pattern: 1111...11010110 (sign extension with two's complement)

Definition in file Int128.h.

Function Documentation

abs()

Int128 nfx::datatypes::abs ( const Int128 & value )

inlinenodiscardnoexcept

Get absolute value of Int128 (free function).

Parameters

value

Int128 to get absolute value of

Returns

Absolute value of the integer

Free function wrapper for generic programming and ADL (Argument-Dependent Lookup). Enables usage in generic algorithms: abs(value) works via ADL.

Note

This function is marked [[nodiscard]] - the return value should not be ignored

Definition at line 791 of file Int128.h.

isqrt()

Int128 nfx::datatypes::isqrt ( const Int128 & value )

inlinenodiscard

Calculate integer square root (free function).

Parameters

value

Int128 to compute square root of

Returns

Largest integer i such that i*i <= value

Exceptions

std::domain_error

if value is negative

Free function wrapper for generic programming and ADL (Argument-Dependent Lookup). Returns floor(sqrt(value)) - always rounds down.

Note

This function is marked [[nodiscard]] - the return value should not be ignored

Definition at line 805 of file Int128.h.

Here is the call graph for this function:

sqrt()

Decimal nfx::datatypes::sqrt ( const Int128 & value )

nodiscard

Calculate square root of Int128 value with high precision.

Parameters

value

Integer value to compute square root of

Returns

Decimal value representing the square root with up to 28 digits of precision

Exceptions

std::domain_error

if value is negative

Converts Int128 to Decimal and computes high-precision square root using Newton-Raphson method. This provides exact decimal precision (up to 28 digits) compared to isqrt() which returns floor(sqrt).

Examples:

• sqrt(Int128{4}) → Decimal{"2.0"} (exact)
• sqrt(Int128{2}) → Decimal{"1.4142135623730950488..."} (28-digit precision)
• sqrt(Int128{100}) → Decimal{"10.0"} (exact)

Note

This function is marked [[nodiscard]] - the return value should not be ignored

For integer-only results, use Int128::isqrt() or isqrt(Int128) instead

See also

Int128::isqrt() for integer square root (floor)

isqrt(Int128) for free function variant

Decimal::sqrt() for the underlying high-precision implementation