Reference-counted arbitrary precision integer library. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <limits.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <stdio.h>
#include <math.h>

Typedefs
typedef uint32_t	di_limb_t

typedef uint64_t	di_dlimb_t

typedef struct di_int_internal *	di_int
	Integer handle for arbitrary precision integers.

Functions
di_int	di_from_int32 (int32_t value)
	Create a new integer from a 32-bit signed integer.

di_int	di_from_int64 (int64_t value)
	Create a new integer from a 64-bit signed integer.

di_int	di_from_uint32 (uint32_t value)
	Create a new integer from a 32-bit unsigned integer.

di_int	di_from_uint64 (uint64_t value)
	Create a new integer from a 64-bit unsigned integer.

di_int	di_from_string (const char *str, int base)
	Create a new integer from a string representation.

di_int	di_zero (void)
	Create a new integer with value zero.

di_int	di_one (void)
	Create a new integer with value one.

di_int	di_copy (di_int big)
	Create a deep copy of an integer.

di_int	di_retain (di_int big)
	Increment reference count and return the same integer.

void	di_release (di_int *big)
	Decrement reference count and free if zero.

size_t	di_ref_count (di_int big)
	Get current reference count of an integer.

di_int	di_add (di_int a, di_int b)
	Add two integers.

di_int	di_add_i32 (di_int a, int32_t b)
	Add an integer and a 32-bit signed integer.

di_int	di_sub (di_int a, di_int b)
	Subtract two integers.

di_int	di_sub_i32 (di_int a, int32_t b)
	Subtract a 32-bit signed integer from an integer.

di_int	di_mul (di_int a, di_int b)
	Multiply two integers.

di_int	di_mul_i32 (di_int a, int32_t b)
	Multiply an integer by a 32-bit signed integer.

di_int	di_div (di_int a, di_int b)
	Divide two integers using floor division.

di_int	di_mod (di_int a, di_int b)
	Get remainder of integer division using floor modulo.

di_int	di_negate (di_int a)
	Negate an integer (change sign)

di_int	di_abs (di_int a)
	Get absolute value of an integer.

di_int	di_pow (di_int base, uint32_t exp)
	Raise integer to a power.

di_int	di_and (di_int a, di_int b)
	Bitwise AND of two integers.

di_int	di_or (di_int a, di_int b)
	Bitwise OR of two integers.

di_int	di_xor (di_int a, di_int b)
	Bitwise XOR of two integers.

di_int	di_not (di_int a)
	Bitwise NOT (complement) of an integer.

di_int	di_shift_left (di_int a, size_t bits)
	Left shift an integer by specified bits.

di_int	di_shift_right (di_int a, size_t bits)
	Right shift an integer by specified bits.

int	di_compare (di_int a, di_int b)
	Compare two integers.

bool	di_eq (di_int a, di_int b)
	Test if two integers are equal.

bool	di_lt (di_int a, di_int b)
	Test if first integer is less than second.

bool	di_le (di_int a, di_int b)
	Test if first integer is less than or equal to second.

bool	di_gt (di_int a, di_int b)
	Test if first integer is greater than second.

bool	di_ge (di_int a, di_int b)
	Test if first integer is greater than or equal to second.

bool	di_is_zero (di_int big)
	Test if integer is zero.

bool	di_is_negative (di_int big)
	Test if integer is negative.

bool	di_is_positive (di_int big)
	Test if integer is positive (> 0)

bool	di_is_one (di_int big)
	Test if integer equals one.

bool	di_to_int32 (di_int big, int32_t *result)
	Convert integer to 32-bit signed integer.

bool	di_to_int64 (di_int big, int64_t *result)
	Convert integer to 64-bit signed integer.

bool	di_to_uint32 (di_int big, uint32_t *result)
	Convert integer to 32-bit unsigned integer.

bool	di_to_uint64 (di_int big, uint64_t *result)
	Convert integer to 64-bit unsigned integer.

double	di_to_double (di_int big)
	Convert integer to double precision floating point.

char *	di_to_string (di_int big, int base)
	Convert integer to string representation.

size_t	di_bit_length (di_int big)
	Get bit length of integer (number of bits needed to represent)

size_t	di_limb_count (di_int big)
	Get number of limbs used by integer.

bool	di_reserve (di_int big, size_t capacity)
	Reserve capacity for an integer (performance optimization)

di_int	di_mod_pow (di_int base, di_int exp, di_int mod)
	Modular exponentiation: (base^exp) mod mod.

di_int	di_gcd (di_int a, di_int b)
	Greatest Common Divisor using Euclidean algorithm.

di_int	di_lcm (di_int a, di_int b)
	Least Common Multiple.

di_int	di_extended_gcd (di_int a, di_int b, di_int x, di_int y)
	Extended Euclidean Algorithm.

di_int	di_sqrt (di_int n)
	Integer square root using Newton's method.

di_int	di_factorial (uint32_t n)
	Calculate factorial.

bool	di_is_prime (di_int n, int certainty)
	Test if integer is prime (Miller-Rabin test)

di_int	di_next_prime (di_int n)
	Find next prime number >= n.

di_int	di_random (size_t bits)
	Generate random integer with specified bit length.

di_int	di_random_range (di_int min, di_int max)
	Generate random integer in range [min, max)

bool	di_add_overflow_int32 (int32_t a, int32_t b, int32_t *result)
	Add two int32_t values with overflow detection.

bool	di_subtract_overflow_int32 (int32_t a, int32_t b, int32_t *result)
	Subtract two int32_t values with overflow detection.

bool	di_multiply_overflow_int32 (int32_t a, int32_t b, int32_t *result)
	Multiply two int32_t values with overflow detection.

bool	di_add_overflow_int64 (int64_t a, int64_t b, int64_t *result)
	Add two int64_t values with overflow detection.

bool	di_subtract_overflow_int64 (int64_t a, int64_t b, int64_t *result)
	Subtract two int64_t values with overflow detection.

bool	di_multiply_overflow_int64 (int64_t a, int64_t b, int64_t *result)
	Multiply two int64_t values with overflow detection.

Detailed Description

Reference-counted arbitrary precision integer library.

Version: 1.1.0

Date: September 2025

Single header library for arbitrary precision integers with reference counting. Designed for seamless integration with MCU projects that need automatic promotion from fixed-size integers to arbitrary precision on overflow.

Configuration

Customize the library by defining these macros before including:

#define DI_MALLOC malloc         // custom allocator
#define DI_REALLOC realloc       // custom reallocator
#define DI_FREE free             // custom deallocator
#define DI_ASSERT assert         // custom assert macro
#define DI_LIMB_BITS 32          // bits per limb (default: 32)
 
#define DI_IMPLEMENTATION
#include "dynamic_int.h"

Basic Usage

di_int a = di_from_int32(42);
di_int b = di_from_int32(100);
di_int sum = di_add(a, b);
 
int32_t result;
if (di_to_int32(sum, &result)) {
    printf("Sum: %d\n", result);
} else {
    char* str = di_to_string(sum, 10);
    printf("Sum (too large): %s\n", str);
    free(str);
}
 
di_release(&a);
di_release(&b);
di_release(&sum);

Definition in file dynamic_int.h.

Typedef Documentation

◆ di_dlimb_t

typedef uint64_t di_dlimb_t

Definition at line 88 of file dynamic_int.h.

◆ di_int

typedef struct di_int_internal* di_int

Integer handle for arbitrary precision integers.

This is a handle (pointer) to an arbitrary precision integer with reference counting. The actual data is stored in a struct di_int_internal which contains the limb array, reference count, and sign flag.

Note: NULL represents an invalid integer handle; All integers are immutable - operations return new integers; Reference counting prevents memory leaks

Definition at line 113 of file dynamic_int.h.

◆ di_limb_t

typedef uint32_t di_limb_t

Definition at line 87 of file dynamic_int.h.

Typedefs