jmaths

A professional, high-performance C++23 library for arbitrary-precision arithmetic operations with comprehensive support for unlimited-size integers, rational numbers, and advanced mathematical computations.

Features

• Arbitrary-Precision Integers (N, Z) — Unlimited-size integers with complete arithmetic support
• Rational Numbers (Q) — Arbitrary-precision fractions with automatic reduction to lowest terms
• Modern C++23 — Leverages latest language features for clean, efficient, and type-safe code
• Comprehensive Testing — 510 test cases with 1,200 assertions ensuring reliability and correctness
• Constexpr Support — Compile-time evaluation for most operations
• User-Defined Literals — Natural syntax using _N, _Z, and _Q literals
• Rich Mathematical API — GCD, square root, exponentiation, bitwise operations, and more
• Production-Ready — Thoroughly tested with continuous integration and quality assurance

Quick Start

Installation

Using the build script (recommended)

./build_install_posix.sh

Manual installation

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-15
cmake --build . -j$(nproc)
sudo cmake --install .

Basic Usage

#include <jmaths/all.hpp>
using namespace jmaths;
using namespace jmaths::literals;

int main() {
    // Arbitrary-precision unsigned integers
    N large = "123456789012345678901234567890"_N;
    N result = large * large;

    // Signed integers
    Z negative = -42_Z;
    Z positive = 100_Z;
    Z sum = negative + positive;  // 58

    // Rational numbers (fractions)
    Q half("1/2");
    Q third("1/3");
    Q sum_frac = half + third;  // 5/6

    // Mathematical functions
    N base(2);
    N exponent(100);
    N power = calc::pow(base, exponent);  // 2^100

    N a(48), b(18);
    N gcd = calc::gcd(a, b);  // 6

    return 0;
}

Compilation

Since jmaths is a header-only library, no linking is required. After installation, the headers are in /usr/local/include/jmaths/ (or your CMAKE_INSTALL_PREFIX):

# If installed system-wide (to /usr/local/)
g++-15 -std=c++23 -O3 your_program.cpp -o your_program

# If installed to a custom location
g++-15 -std=c++23 -O3 -I/path/to/install/include your_program.cpp -o your_program

Alternatively, use CMake's find_package to automatically configure include paths:

find_package(jmaths REQUIRED)
target_link_libraries(your_target jmaths)

Requirements

• Compiler — GCC 15 or later with C++23 support
• CMake — 3.28.1 or later
• Boost — 1.70 or later (testing framework only)
• binutils — 2.43 or later (required for GCC 15)
• Operating System — Linux, macOS, or Windows (with appropriate toolchain)

Note: When using GCC 15, ensure binutils 2.43 or later is installed. Older versions may cause assembler errors in debug builds. The CMake configuration automatically detects your binutils version and provides appropriate guidance. See GCC15_REQUIREMENTS.md for detailed information.

Documentation

• API Reference — Complete API documentation
• Quick Reference — Common patterns and gotchas
• Algorithm Documentation — Algorithm explanations and complexity analysis
• Known Issues — Known bugs and workarounds
• Exception Reference — Exception handling guide
• GCC 15 Requirements — Toolchain compatibility
• CI/CD Workflows — Automated testing pipeline
• Contributing — Contribution guidelines
• Security — Security policy and best practices

Testing

The library includes a comprehensive test suite with 510 test cases and 1,200 assertions covering all major functionality:

cd build
ctest --output-on-failure

Test Coverage

• Arithmetic Operations — All operations for N, Z, and Q types
• Edge Cases — Boundary conditions, zero handling, and special values
• Type Conversions — String parsing, numeric conversions, and range checking
• Bitwise Operations — Complete coverage of bitwise operations for integers
• Mathematical Functions — GCD, square root, exponentiation, and modular arithmetic
• Error Handling — Exception throwing and safety guarantees

Project Structure

jmaths/
├── .github/              # GitHub integration (workflows, templates)
├── doc/                  # Documentation
├── src/
│   └── headers/          # Public header files
├── test/                 # Boost.Test unit tests
├── CMakeLists.txt        # Root CMake configuration
├── CODE_OF_CONDUCT.md    # Community guidelines
├── SECURITY.md           # Security policy
└── README.md             # This file

Configuration Options

You can customize the library by editing src/headers/constants_and_types.hpp.in before building:

• Base Integer Types — Customize underlying digit representation
• Custom Allocators — Provide specialized memory allocators
• Karatsuba Multiplication — Enable advanced multiplication algorithm (experimental)

Performance

jmaths is engineered for high performance through several optimization strategies:

• Zero-Cost Abstractions — Template-based design with no runtime overhead
• Efficient Algorithms — Binary GCD, exponentiation by squaring, Karatsuba multiplication
• Compile-Time Optimization — Extensive use of constexpr and [[nodiscard]] attributes
• Memory Efficiency — Custom allocator support and minimal overhead per operation

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• Issues — GitHub Issues for bug reports and feature requests
• Discussions — GitHub Discussions for questions
• Documentation — Complete documentation index

Acknowledgments

• Implemented in C++23 with modern language features
• Build system powered by CMake
• Testing framework provided by Boost.Test
• Continuous integration via GitHub Actions

---

jmaths — Professional arbitrary-precision arithmetic for C++23