nfx-datatypes

A C++20 library providing cross-platform 128-bit integer and high-precision decimal arithmetic

Overview

nfx-datatypes is a modern C++20 library providing numeric types for applications requiring precise integer and decimal arithmetic. It features cross-platform 128-bit signed integers and high-precision decimal arithmetic.

Key Features

🔢 High-Precision Numeric Types

• Int128: Cross-platform 128-bit signed integer arithmetic
  • Native __int128 support on GCC/Clang for maximum performance
  • Hand-optimized implementation for MSVC using 64-bit operations
  • Full range: -2^127 to 2^127-1
  • Complete arithmetic operator support (+, -, *, /, %)
• Decimal: High-precision decimal arithmetic
  • 96-bit mantissa with configurable scale (0-28)
  • Up to 28-29 significant digits
  • Exact decimal representation (no binary floating-point errors)
  • Financial and scientific computation support

➕ Complete Operator Support

• Arithmetic: +, -, *, /, %, unary -
• Comparison: ==, !=, <, <=, >, >=
• Type conversions: int32, int64, uint64, float, double
• Cross-type operations: Int128 ↔ Decimal interoperability
• String parsing: fromString()
• String formatting: toString()

📊 Real-World Applications

• Data Analytics: Processing large datasets with exact numerical precision
• Financial Systems: Exact decimal arithmetic for banking, accounting, and trading platforms
• Scientific Computing: High-precision calculations for research and simulation
• E-commerce: Precise price calculations and tax computations

⚡ Performance Optimized

• Sub-nanosecond basic operations (construction, comparisons)
• Highly optimized arithmetic (addition, multiplication, division)
• Fast string parsing and formatting
• Zero-cost abstractions with constexpr support

🌍 Cross-Platform Support

• Platforms: Linux, Windows
• Architecture: x86-64
• Compilers: GCC 14+, Clang 18+, MSVC 2022+
• Thread-safe operations
• Consistent behavior across platforms
• CI/CD testing on multiple compilers

Quick Start

Requirements

• C++20 compatible compiler:
  • GCC 14+ (14.2.0 tested)
  • Clang 18+ (19.1.7 tested)
  • MSVC 2022+ (19.44+ tested)
• CMake 3.20 or higher

CMake Integration

# Build options
option(NFX_DATATYPES_BUILD_STATIC         "Build static library"             ON )
option(NFX_DATATYPES_BUILD_SHARED         "Build shared library"             OFF)

# Development options
option(NFX_DATATYPES_BUILD_TESTS          "Build tests"                      OFF)
option(NFX_DATATYPES_BUILD_SAMPLES        "Build samples"                    OFF)
option(NFX_DATATYPES_BUILD_BENCHMARKS     "Build benchmarks"                 OFF)
option(NFX_DATATYPES_BUILD_DOCUMENTATION  "Build Doxygen documentation"      OFF)

# Performance options
option(NFX_DATATYPES_ENABLE_SIMD          "Enable native CPU optimizations"  ON )

# Installation and packaging
option(NFX_DATATYPES_INSTALL_PROJECT      "Install project"                  OFF)
option(NFX_DATATYPES_PACKAGE_SOURCE       "Enable source package generation" OFF)

Using in Your Project

Option 1: Using FetchContent (Recommended)

include(FetchContent)
FetchContent_Declare(
  nfx-datatypes
  GIT_REPOSITORY https://github.com/nfx-libs/nfx-datatypes.git
  GIT_TAG        main  # or use specific version tag like "0.1.0"
)
FetchContent_MakeAvailable(nfx-datatypes)

# Link with static library
target_link_libraries(your_target PRIVATE nfx-datatypes::static)

Option 2: As a Git Submodule

# Add as submodule
git submodule add https://github.com/nfx-libs/nfx-datatypes.git third-party/nfx-datatypes

# In your CMakeLists.txt
add_subdirectory(third-party/nfx-datatypes)
target_link_libraries(your_target PRIVATE nfx-datatypes::static)

Option 3: Using find_package (After Installation)

find_package(nfx-datatypes REQUIRED)
target_link_libraries(your_target PRIVATE nfx-datatypes::static)

Building

Build Commands:

# Clone the repository
git clone https://github.com/nfx-libs/nfx-datatypes.git
cd nfx-datatypes

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release

# Build the library
cmake --build . --config Release --parallel

# Run tests (optional)
ctest -C Release --output-on-failure

# Run benchmarks (optional)
./bin/benchmarks/BM_Decimal
./bin/benchmarks/BM_Int128

Documentation

nfx-datatypes includes API documentation generated with Doxygen.

📚 Online Documentation

The complete API documentation is available online at: https://nfx-libs.github.io/nfx-datatypes

Building Documentation Locally

# Configure with documentation enabled
cmake .. -DCMAKE_BUILD_TYPE=Release -DNFX_DATATYPES_BUILD_DOCUMENTATION=ON

# Build the documentation
cmake --build . --target nfx-datatypes-documentation

Requirements

• Doxygen - Documentation generation tool
• Graphviz Dot (optional) - For generating class diagrams

Accessing Local Documentation

After building, open ./build/doc/html/index.html in your web browser.

Usage Examples

Int128 - 128-bit Integer Arithmetic

#include <nfx/datatypes/Int128.h>

using namespace nfx::datatypes;

// Construction from various types
Int128 a{42};                                            // From int32
Int128 b{1234567890123456789LL};                         // From int64
Int128 c{0xFEDCBA0987654321ULL, 0x0123456789ABCDEFULL};  // From two 64-bit words

// String parsing
Int128 d{"123456789012345678901234567890"};
Int128 e;
if (Int128::fromString("-987654321098765432109876543210", e))
{
	// Successfully parsed
}

// Arithmetic operations
Int128 sum = a + b;
Int128 diff = b - a;
Int128 product = a * Int128{100};
Int128 quotient = b / Int128{10};
Int128 remainder = b % Int128{7};

// Comparison operations
bool equal = (a == Int128{42});
bool less = (a < b);
bool greater = (b > a);

// Cross-type comparisons
bool eqInt64 = (b == 1234567890123456789LL);
bool eqDouble = (a == 42.0);

// String conversion
std::string str = c.toString();  // "-1311768464867721559164238360763045071"

// Access high/low words
std::uint64_t low = c.toLow();
std::uint64_t high = c.toHigh();

// Mathematical operations
Int128 absValue = Int128{-42}.abs();    // 42
bool isNeg = Int128{-42}<0;  // true

Decimal - High-Precision Decimal Arithmetic

#include <nfx/datatypes/Decimal.h>

using namespace nfx::datatypes;

// Construction from various types
Decimal a{ 42 };		   // Integer
Decimal b{ 123.456 };	   // From double
Decimal c{ 9876543210LL }; // From int64

// String parsing with exact precision
Decimal d{"123.456789012345678901234567890"};
Decimal e;
if ( Decimal::fromString( "99.99", e ) )
{
	// Successfully parsed
}

// Arithmetic operations (exact decimal arithmetic)
Decimal sum = Decimal{ 10.5 } + Decimal{ 20.3 };	 // 30.8
Decimal diff = Decimal{ 50.0 } - Decimal{ 12.5 };	 // 37.5
Decimal product = Decimal{ 3.5 } * Decimal{ 2.0 };	 // 7.0
Decimal quotient = Decimal{ 10.0 } / Decimal{ 4.0 }; // 2.5

// Financial calculations (no rounding errors)
Decimal price{ 19.99 };
Decimal quantity{ 100 };
Decimal total = price * quantity; // Exactly 1999.00

// Comparison operations
bool equal = ( Decimal{ 10.5 } == Decimal{ 10.5 } );
bool less = ( Decimal{ 5.0 } < Decimal{ 10.0 } );

// Mathematical operations
Decimal abs = Decimal{ -42.5 }.abs();			  // 42.5
Decimal truncated = Decimal{ 42.789 }.trunc( );   // 42
Decimal floor = Decimal{ 42.789 }.floor();		  // 42
Decimal ceiling = Decimal{ 42.123 }.ceil( );	  // 43
Decimal rounded = Decimal{ 42.567 }.round();	  // 43

// Property access
std::uint8_t scale = Decimal{ 123.456 }.scale(); // Number of decimal places
int places = Decimal{ 123.456 }.decimalPlacesCount();

// State checking
bool isNeg = Decimal{ -10.5 }<0;

// Numeric limits (use std::numeric_limits)
Decimal min = std::numeric_limits<Decimal>::min();
Decimal max = std::numeric_limits<Decimal>::max();

// String conversion
std::string str = Decimal{ 123.456 }.toString(); // "123.456"

Int128 ↔ Decimal Interoperability

#include <nfx/datatypes/Int128.h>
#include <nfx/datatypes/Decimal.h>

using namespace nfx::datatypes;

// Convert Int128 to Decimal
Int128 bigInt{1234567890123456789LL};
Decimal dec{bigInt};  // Exact conversion

// Convert Decimal to Int128 (truncates fractional part)
Decimal price{99.95};
Int128 wholeDollars{price};  // 99 (fractional part truncated)

// Mixed arithmetic comparisons
Int128 intVal{100};
Decimal decVal{100.0};
bool equal = (intVal == decVal);  // true

Decimal withFraction{100.5};
bool notEqual = (intVal == withFraction);  // false (Decimal has fractional part)

// Use in calculations
Int128 count{1000};
Decimal pricePerUnit{19.99};
Decimal totalCost = Decimal{count} * pricePerUnit;

Complete Example

#include <iostream>
#include <nfx/datatypes/Int128.h>
#include <nfx/datatypes/Decimal.h>

int main()
{
	using namespace nfx::datatypes;

	// Financial calculation example
	std::cout << "=== Financial Calculation ===" << std::endl;
	Decimal price{ "19.99" };
	Int128 quantity{ 1000 };
	Decimal total = price * Decimal{quantity};
	std::cout << "Price: " << price.toString() << std::endl;
	std::cout << "Quantity: " << quantity.toString() << std::endl;
	std::cout << "Total: " << total.toString() << std::endl;

	// Large number arithmetic
	std::cout << "\n=== Large Number Arithmetic ===" << std::endl;
	Int128 large1{"123456789012345678901234567890"};
	Int128 large2{"987654321098765432109876543210"};
	Int128 sum = large1 + large2;
	std::cout << "Sum: " << sum.toString() << std::endl;

	// Decimal precision
	std::cout << "\n=== Decimal Precision ===" << std::endl;
	Decimal a{0.1};
	Decimal b{0.2};
	Decimal result = a + b;
	std::cout << "0.1 + 0.2 = " << result.toString() << std::endl;
	std::cout << "Equals 0.3? " << (result == Decimal{0.3} ? "Yes" : "No") << std::endl;

	return 0;
}

Sample Output:

=== Financial Calculation ===
Price: 19.99
Quantity: 1000
Total: 19990

=== Large Number Arithmetic ===
Sum: 1111111110111111111011111111100

=== Decimal Precision ===
0.1 + 0.2 = 0.3
Equals 0.3? Yes

Project Structure

nfx-datatypes/
├── benchmark/             # Performance benchmarks with Google Benchmark
├── cmake/                 # CMake modules and configuration
├── include/nfx/           # Public headers: Int128, Decimal
├── samples/               # Example usage and demonstrations
├── src/                   # Implementation files
└── test/                  # Comprehensive unit tests with GoogleTest

Performance

For detailed performance metrics and benchmarks, see the benchmark documentation.

Roadmap

See TODO.md for upcoming features and project roadmap.

Changelog

See the CHANGELOG.md for a detailed history of changes, new features, and bug fixes.

License

This project is licensed under the MIT License.

Dependencies

Development Dependencies

• GoogleTest: Testing framework (BSD 3-Clause License) - Development only
• Google Benchmark: Performance benchmarking framework (Apache 2.0 License) - Development only

All dependencies are automatically fetched via CMake FetchContent when building the library, tests, or benchmarks.

---

Updated on February 15, 2026

This site is open source. Improve this page.