nfx-datatypes

A high-performance 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.

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

⚡ 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

➕ Complete Operator Support

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

🌍 Cross-Platform Support

• Linux, Windows
• GCC 14+, Clang 18+, MSVC 2022+
• Thread-safe operations
• Consistent behavior and precision across platforms
• Comprehensive test coverage on all platforms

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 optimization
option(NFX_DATATYPES_USE_CACHE            "Enable compiler cache"              ON  )

# 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 )

# Installation and packaging
option(NFX_DATATYPES_INSTALL_PROJECT      "Install project"                    OFF )
option(NFX_DATATYPES_PACKAGE_SOURCE       "Enable source package generation"   OFF )
option(NFX_DATATYPES_PACKAGE_ARCHIVE      "Enable TGZ/ZIP package generation"  OFF )
option(NFX_DATATYPES_PACKAGE_DEB          "Enable DEB package generation"      OFF )
option(NFX_DATATYPES_PACKAGE_RPM          "Enable RPM package generation"      OFF )
option(NFX_DATATYPES_PACKAGE_WIX          "Enable WiX MSI installer"           OFF )

Using in Your Project

Option 1: Using FetchContent (Recommended)

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

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

# Or link with shared library
# target_link_libraries(your_target PRIVATE nfx-datatypes::nfx-datatypes)

Option 2: As a Git Submodule

# Add as submodule
git submodule add https://github.com/ronan-fdev/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

# Clone the repository
git clone https://github.com/ronan-fdev/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)
./build/bin/benchmarks/BM_Int128
./build/bin/benchmarks/BM_Decimal

Documentation

nfx-datatypes includes comprehensive API documentation generated with Doxygen.

📚 Online Documentation

The complete API documentation is available online at: https://ronan-fdev.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 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 = Int128::parse("123456789012345678901234567890");
Int128 e;
if (Int128::tryParse("-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}.isNegative();  // true
bool isZero = Int128{0}.isZero();       // 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 = Decimal::parse( "123.456789012345678901234567890" );
Decimal e;
if ( Decimal::tryParse( "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 }.truncate(); // 42
Decimal floor = Decimal{ 42.789 }.floor();		  // 42
Decimal ceiling = Decimal{ 42.123 }.ceiling();	  // 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 isZero = Decimal{ 0 }.isZero();
bool isNeg = Decimal{ -10.5 }.isNegative();

// Constants
Decimal zero = Decimal::zero();
Decimal one = Decimal::one();
Decimal min = Decimal::minValue();
Decimal max = Decimal::maxValue();

// 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 = Int128::parse("123456789012345678901234567890");
	Int128 large2 = Int128::parse("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

Installation & Packaging

nfx-datatypes provides comprehensive packaging options for distribution.

Package Generation

# Configure with packaging options
cmake .. -DCMAKE_BUILD_TYPE=Release \
		 -DNFX_DATATYPES_BUILD_STATIC=ON \
		 -DNFX_DATATYPES_BUILD_SHARED=ON \
		 -DNFX_DATATYPES_PACKAGE_ARCHIVE=ON \
		 -DNFX_DATATYPES_PACKAGE_DEB=ON \
		 -DNFX_DATATYPES_PACKAGE_RPM=ON

# Generate binary packages
cmake --build . --target package
# or
cd build && cpack

# Generate source packages
cd build && cpack --config CPackSourceConfig.cmake

Supported Package Formats

Format	Platform	Description	Requirements
TGZ/ZIP	Cross-platform	Compressed archive packages	None
DEB	Debian/Ubuntu	Native Debian packages	dpkg-dev
RPM	RedHat/SUSE	Native RPM packages	rpm-build
WiX	Windows	Professional MSI installer	WiX 3.11+
Source	Cross-platform	Source code distribution (TGZ+ZIP)	None

Installation

# Linux (DEB-based systems)
sudo dpkg -i nfx-datatypes_*_amd64.deb

# Linux (RPM-based systems)
sudo rpm -ivh nfx-datatypes-*-Linux.rpm

# Windows
# Run the .exe installer with administrator privileges
nfx-datatypes-*-win64.exe

# Manual installation (extract archive)
tar -xzf nfx-datatypes-*-Linux.tar.gz -C /usr/local/

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 across all compilers (GCC, Clang, MSVC, MinGW) and platforms, see the benchmark documentation.

Roadmap

See TODO.md for upcoming features and project roadmap.

Changelog

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

License

This project is licensed under the MIT License.

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 tests or benchmarks.

---

Updated on November 8, 2025

This site is open source. Improve this page.