nfx-hashing

A modern C++20 header-only library providing high-performance hashing algorithms

Overview

nfx-hashing is a modern C++20 header-only library that provides a collection of efficient hashing algorithms and utilities optimized for use in hash-based containers. The library includes hardware-accelerated implementations where available, with automatic fallback to software implementations.

Key Features

🎲 High-Performance Hashing Algorithms

• Hardware Acceleration: SSE4.2 CRC32-C intrinsics for faster hashing
• Software Fallback: CRC32-C software implementation for systems without SSE4.2
• Multiple Algorithms: CRC32-C (Castagnoli), FNV-1a, Larson, integer hashing (32/64-bit)
• Hash Combining: Boost-style + MurmurHash3 finalizer for composite keys
• Seed Mixing: Utilities for hash table probing and collision resolution
• Constexpr Support: Compile-time hash computation where possible
• Hardware Acceleration: Automatic use of SSE4.2 CRC32-C instructions when available, with software fallback

📊 Real-World Applications

• Hash Tables: Foundation for custom hash table implementations
• Data Structures: High-performance key hashing for maps and sets
• Checksums: Fast data integrity verification
• Fingerprinting: Quick data fingerprint generation

🎯 Algorithm Selection

• Manual Selection: Choose between CRC32-C (default) or FNV-1a algorithms
• Type-Safe: Template-based integer hashing with compile-time type checking
• Optimized: Knuth's multiplicative hashing (32-bit), Wang's avalanche (64-bit)
• Avalanche: Excellent bit distribution for uniform hash values

⚡ Performance Optimized

• Header-only library with zero runtime dependencies
• Hardware-accelerated hashing with SSE4.2 intrinsics when available
• Software fallback for older CPUs
• Efficient hash combining with excellent avalanche properties
• Zero-cost abstractions with constexpr support
• Compiler-optimized inline implementations
• Runtime CPU feature detection with cached results

🌍 Cross-Platform Support

• Platforms: Linux, Windows
• Architecture: x86-64 (x86 SIMD features: SSE4.2, AVX, AVX2)
• Compilers: GCC 14+, Clang 19+, 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

# Development options
option(NFX_HASHING_BUILD_TESTS          "Build tests"                        OFF )
option(NFX_HASHING_BUILD_SAMPLES        "Build samples"                      OFF )
option(NFX_HASHING_BUILD_BENCHMARKS     "Build benchmarks"                   OFF )
option(NFX_HASHING_BUILD_DOCUMENTATION  "Build Doxygen documentation"        OFF )
 
# Installation
option(NFX_HASHING_INSTALL_PROJECT      "Install project"                    OFF )
 
# Packaging
option(NFX_HASHING_PACKAGE_SOURCE       "Enable source package generation"   OFF )

Using in Your Project

Option 1: Using FetchContent (Recommended)

include(FetchContent)
FetchContent_Declare(
  nfx-hashing
  GIT_REPOSITORY https://github.com/nfx-libs/nfx-hashing.git
  GIT_TAG        main  # or use specific version tag like "0.1.0"
)
FetchContent_MakeAvailable(nfx-hashing)
 
# Link with header-only interface library
target_link_libraries(your_target PRIVATE nfx-hashing::nfx-hashing)

Option 2: As a Git Submodule

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

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

Option 3: Using find_package (After Installation)

find_package(nfx-hashing REQUIRED)
target_link_libraries(your_target PRIVATE nfx-hashing::nfx-hashing)

Building

✅ Automatic SIMD Optimization: The library automatically enables SSE4.2 hardware acceleration in Release builds (since v0.2.0). No manual compiler flags needed!

SIMD Optimizations

nfx-hashing uses hardware-accelerated instructions when available:

• SSE4.2 CRC32-C: Automatically used when compiled with SSE4.2 support
• Software fallback: Pure C++ implementation when SIMD unavailable
• Compile-time detection: Uses #ifdef __SSE4_2__ preprocessor checks

To enable SIMD optimizations, compile your project with appropriate flags:

# GCC/Clang: Enable native CPU optimizations
target_compile_options(your_target PRIVATE -march=native)
 
# Or explicit SSE4.2
target_compile_options(your_target PRIVATE -msse4.2)
 
# MSVC: Enable AVX (includes SSE4.2)
target_compile_options(your_target PRIVATE /arch:AVX)

For portable binaries (no SIMD), simply don't add SIMD flags. The library will automatically use software fallback.

Build Commands:

# Clone the repository
git clone https://github.com/nfx-libs/nfx-hashing.git
cd nfx-hashing
 
# Create build directory
mkdir build && cd build
 
# Configure with CMake (SIMD automatically enabled in Release)
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_Hashing

Documentation

nfx-hashing includes API documentation generated with Doxygen.

📚 Online Documentation

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

Building Documentation Locally

# Configure with documentation enabled
cmake .. -DCMAKE_BUILD_TYPE=Release -DNFX_HASHING_BUILD_DOCUMENTATION=ON
 
# Build the documentation
cmake --build . --target nfx-hashing-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 Example

#include <nfx/Hashing.h>
 
using namespace nfx::hashing;
 
// Hash a string with the unified hash<T> API
// Uses CRC32-C (hardware-accelerated when available) with default FNV seed
uint32_t hash_value = hash<std::string>("example_key");
 
// Hash with 64-bit output
uint64_t hash64 = hash<std::string, uint64_t>("example_key");
 
// Hash with custom seed (compile-time)
uint32_t custom_hash = hash<std::string, uint32_t, 0xDEADBEEF>("example_key");
 
// Hash integers
uint32_t int_hash = hash<int>(42);
 
// Hash complex types (pairs, tuples, vectors, etc.)
std::pair<int, std::string> p = {42, "answer"};
uint32_t pair_hash = hash<std::pair<int, std::string>>(p);
 
// Low-level: Manual algorithm use (for advanced users)
uint32_t fnvHash = constants::FNV_OFFSET_BASIS_32;
for (char ch : std::string_view("example_key"))
{
    fnvHash = fnv1a(fnvHash, static_cast<uint8_t>(ch));
}

Project Structure

nfx-hashing/
├── benchmark/             # Benchmarks with Google Benchmark
├── cmake/                 # CMake modules and configuration
├── include/nfx/           # Public headers: hashing algorithms
├── samples/               # Example usage and demonstrations
└── test/                  # Unit tests with GoogleTest

Performance

nfx-hashing is optimized for high performance with:

• Hardware-accelerated hashing - SSE4.2 CRC32-C intrinsics
• Software fallback - Pure C++ CRC32-C implementation when SSE4.2 unavailable
• Constexpr support - Compile-time hash computation where possible
• Zero-cost abstractions - No runtime overhead for type safety
• Optimized avalanche - Excellent bit distribution for uniform hash values
• Runtime detection with static caching - CPU feature detection at startup, cached for zero overhead thereafter
• Cache-friendly - Optimized memory access patterns for large datasets

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.

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