puremp 0.1.8

A pure-Rust arbitrary-precision arithmetic library — integers, rationals and MPFR-class floats — with a dependency-free clean-room core (optional serde/rand bridges), plus a C ABI and a CLI.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

/*
 * puremp.h — C ABI for the `puremp` arbitrary-precision arithmetic library.
 *
 * These declarations mirror the `#[unsafe(no_mangle)] extern "C"` entry points
 * in `src/ffi.rs`, built when the crate is compiled with the `ffi` feature:
 *
 *     cargo rustc --lib --release --features ffi --crate-type staticlib
 *     cargo rustc --lib --release --features ffi --crate-type cdylib
 *
 * Conventions:
 *   - `PurempInt` is an opaque, heap-allocated arbitrary-precision signed
 *     integer. Every constructor returns a handle the caller must release with
 *     `puremp_int_free`.
 *   - Fallible calls return NULL (pointer results) or a documented sentinel.
 *   - Strings returned by the library must be released with
 *     `puremp_string_free`.
 *   - Passing NULL where a handle is expected yields NULL / a sentinel rather
 *     than crashing; every call catches Rust panics at the boundary.
 *
 * This library is MIT-licensed. See LICENSE.
 */
#ifndef PUREMP_H
#define PUREMP_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Opaque arbitrary-precision signed integer. */
typedef struct PurempInt PurempInt;

/* Library version as a static NUL-terminated string (do not free). */
const char *puremp_version(void);

/* --- construction --- */

/* From a signed 64-bit value. */
PurempInt *puremp_int_from_i64(int64_t v);

/* Parse a decimal integer (optional leading '+'/'-'). NULL on error. */
PurempInt *puremp_int_from_str(const char *s);

/* Release an integer handle. NULL is ignored. */
void puremp_int_free(PurempInt *h);

/* --- arithmetic (each returns a fresh handle, NULL on a NULL argument) --- */

PurempInt *puremp_int_add(const PurempInt *a, const PurempInt *b);
PurempInt *puremp_int_sub(const PurempInt *a, const PurempInt *b);
PurempInt *puremp_int_mul(const PurempInt *a, const PurempInt *b);
PurempInt *puremp_int_pow(const PurempInt *base, uint64_t exp);
PurempInt *puremp_int_neg(const PurempInt *a);

/* --- inspection --- */

/* Compare: -1, 0, 1; returns -2 if either argument is NULL. */
int puremp_int_cmp(const PurempInt *a, const PurempInt *b);

/* Sign: -1, 0, 1; returns -2 if the argument is NULL. */
int puremp_int_sign(const PurempInt *a);

/* Decimal string (caller frees with puremp_string_free). NULL on error. */
char *puremp_int_to_string(const PurempInt *a);

/* Release a string returned by the library. NULL is ignored. */
void puremp_string_free(char *s);

/* --- Rational: opaque exact fraction (always in lowest terms) --- */

typedef struct PurempRat PurempRat;

/* Build num/den from two integer handles (reduced). NULL if den is zero. */
PurempRat *puremp_rat_new(const PurempInt *num, const PurempInt *den);

/* Parse "3", "-3/4", or a decimal like "1.5". NULL on error. */
PurempRat *puremp_rat_from_str(const char *s);

/* Release a rational handle. NULL is ignored. */
void puremp_rat_free(PurempRat *h);

/* Arithmetic (each returns a fresh handle, NULL on a NULL argument). */
PurempRat *puremp_rat_add(const PurempRat *a, const PurempRat *b);
PurempRat *puremp_rat_sub(const PurempRat *a, const PurempRat *b);
PurempRat *puremp_rat_mul(const PurempRat *a, const PurempRat *b);
PurempRat *puremp_rat_div(const PurempRat *a, const PurempRat *b); /* NULL if b==0 */

/* Compare: -1, 0, 1; returns -2 if either argument is NULL. */
int puremp_rat_cmp(const PurempRat *a, const PurempRat *b);

/* "n" or "n/d" string (caller frees with puremp_string_free). NULL on error. */
char *puremp_rat_to_string(const PurempRat *r);

/* --- Float: opaque arbitrary-precision binary float --- */

typedef struct PurempFloat PurempFloat;

/*
 * Rounding modes for the float operations:
 *   0 = to nearest (ties to even), 1 = toward zero, 2 = toward +inf,
 *   3 = toward -inf, 4 = away from zero. Other values are treated as nearest.
 */

/* Construct from a C double / from an integer handle (rounded to `precision`). */
PurempFloat *puremp_float_from_double(double x, uint64_t precision);
PurempFloat *puremp_float_from_int(const PurempInt *n, uint64_t precision, int rounding);

/* Pi rounded to `precision` bits. */
PurempFloat *puremp_float_pi(uint64_t precision, int rounding);

/* Release a float handle. NULL is ignored. */
void puremp_float_free(PurempFloat *h);

/* Arithmetic at `precision` bits (each returns a fresh handle, NULL on NULL). */
PurempFloat *puremp_float_add(const PurempFloat *a, const PurempFloat *b, uint64_t precision, int rounding);
PurempFloat *puremp_float_sub(const PurempFloat *a, const PurempFloat *b, uint64_t precision, int rounding);
PurempFloat *puremp_float_mul(const PurempFloat *a, const PurempFloat *b, uint64_t precision, int rounding);
PurempFloat *puremp_float_div(const PurempFloat *a, const PurempFloat *b, uint64_t precision, int rounding);
PurempFloat *puremp_float_sqrt(const PurempFloat *a, uint64_t precision, int rounding);

/* Convert to a C double (NaN if the handle is NULL). */
double puremp_float_to_double(const PurempFloat *a);

/* Fixed-point decimal string (caller frees with puremp_string_free). */
char *puremp_float_to_string(const PurempFloat *a, uint32_t frac_digits);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* PUREMP_H */