Float — Arbitrary-Precision Floating Point

Overview

Float is the arbitrary-precision floating-point type in calx. Internally, a value is represented as a triple of (sign, mantissa Int, exponent int64_t), encoding a value $x$ as:

where $s$ is the sign bit, $m$ is the multiple-precision integer (Int) mantissa, and $e$ is a 64-bit integer exponent.

Precision is specified in decimal digits and internally converted to bit precision. IEEE 754-compatible rounding modes (RoundingMode) are supported, and NaN and Infinity propagate safely through all operations.

• Arbitrary precision — No limit on the number of digits. Calculations with hundreds of thousands of digits are possible
• NaN/Infinity safe — Special values propagate with IEEE 754-like semantics
• thread_local constant cache — Mathematical constants such as $\pi, e, \log 2$ are cached per thread, avoiding recomputation at the same precision
• Precision tracking — Effective bits (effectiveBits) and requested bits (requestedBits) are automatically managed

Build

Required Headers

#include <math/core/mp/Float.hpp>          // Float class
#include <math/core/mp/Float/FloatMath.hpp> // cbrt, nthRoot, fma, fmma, sqr, logUi, etc.

Link library: calx_float (depends on calx_int).

Constructors

Copy/move constructors and assignment operators are all provided as default. Assignment operators from int64_t and double are also available.

Special Value Factory

All are static member functions.

If precision is omitted, defaultPrecision() (thread-local) is used.

Mathematical Constants

All are static member functions. A thread_local cache avoids recomputation at the same precision.

Trigonometric / Circle Constants

Square Root Constants

Logarithmic Constants

Notable Constants

Rare Mathematical Constants

Code Example

Float::setDefaultPrecision(100);
Float pi = Float::pi();       // pi = 3.14159265...
Float e  = Float::e();        // e = 2.71828182...
Float g  = Float::euler();    // gamma = 0.57721566... (Euler-Mascheroni)
Float s2 = Float::sqrt2();    // sqrt(2) = 1.41421356...

Precision Control

Rounding Modes

enum class RoundingMode {
    ToNearest,      // Round to nearest (default)
    TowardZero,     // Round toward zero (truncation)
    TowardPositive, // Round toward positive infinity (ceiling)
    TowardNegative, // Round toward negative infinity (floor)
    AwayFromZero    // Round away from zero
};

State Inspection

Arithmetic Operators

Based on the precision propagation policy (default: MAX_PROPAGATION), the result's requestedBits is max(lhs, rhs) and effectiveBits is min(lhs, rhs).

Comparison Operators

The three-way comparison operator automatically generates !=, <, >, <=, >=. Any comparison involving NaN returns std::partial_ordering::unordered (IEEE 754 compliant).

Basic Mathematical Functions

All are free functions in the calx namespace. The precision argument specifies the working precision in decimal digits. Move overloads are also provided but omitted from the tables.

Exponential / Logarithmic

Trigonometric Functions

Code Example

int prec = 50;
Float x("0.5", prec);
Float s = sin(x, prec);   // sin(0.5)
Float c = cos(x, prec);   // cos(0.5)
Float t = tan(x, prec);   // tan(0.5)

Inverse Trigonometric Functions

Code Example

int prec = 50;
Float x("0.5", prec);
Float a = asin(x, prec);  // arcsin(0.5) = pi/6
Float b = acos(x, prec);  // arccos(0.5) = pi/3
Float c = atan(x, prec);  // arctan(0.5) = 0.4636...

Hyperbolic Functions

Code Example

int prec = 50;
Float x("1.0", prec);
Float s = sinh(x, prec);  // sinh(1) = 1.1752...
Float c = cosh(x, prec);  // cosh(1) = 1.5430...
Float t = tanh(x, prec);  // tanh(1) = 0.7615...

Inverse Hyperbolic Functions

Powers / Roots

Code Example

int prec = 50;
Float x("2.0", prec);
Float s = sqrt(x, prec);                  // sqrt(2) = 1.41421356...
Float c = cbrt(x, prec);                  // cbrt(2) = 1.25992104...
Float p = pow(x, Float("0.5", prec), prec); // 2^0.5 = sqrt(2)

Miscellaneous

Error Functions / Gamma Functions

Code Example

int prec = 50;
Float x("1.0", prec);
Float e = erf(x, prec);                     // erf(1) = 0.84270079...
Float g = gamma(x, prec);                   // Gamma(1) = 1
Float lg = lnGamma(Float("10", prec), prec); // ln(9!) = 12.8018...

Rounding / Integer Part

All are free functions in the calx namespace. Move overloads are also provided.

Utilities

String Conversion

Internal Access

Usage Examples

Computing Pi

#include <math/core/mp/Float.hpp>
using namespace calx;

// Compute pi to 1000 digits (Chudnovsky algorithm)
Float::setDefaultPrecision(1000);
Float pi = Float::pi(1000);
std::cout << pi.toDecimalString(1000) << std::endl;
// 3.14159265358979323846264338327950288419716939937510...

Multi-Precision exp / log

#include <math/core/mp/Float.hpp>
using namespace calx;

int prec = 30;
Float::setDefaultPrecision(prec);
Float x("1.5");

Float ex = exp(x, prec);       // e^1.5
Float lx = log(ex, prec);      // ln(e^1.5) = 1.5
std::cout << "exp(1.5) = " << ex.toDecimalString(prec) << std::endl;
std::cout << "log(exp(1.5)) = " << lx.toDecimalString(prec) << std::endl;
// Matches 1.5 exactly at 30-digit precision

Safe NaN / Infinity Propagation

Float inf = Float::positiveInfinity();
Float nan = Float::nan();
Float z   = Float::zero();

Float r1 = inf + Float(1);     // +Inf
Float r2 = inf - inf;          // NaN
Float r3 = nan + Float(42);   // NaN
Float r4 = Float(1) / z;      // +Inf

std::cout << r1.isInfinity()  // true
          << r2.isNaN()       // true
          << r3.isNaN()       // true
          << r4.isInfinity(); // true

Precision Control and Constant Cache

// thread_local cache makes repeated calls at the same precision fast
Float pi1 = Float::pi(500);   // First call: computed
Float pi2 = Float::pi(500);   // Second call: returned from cache instantly
Float pi3 = Float::pi(1000);  // Different precision: recomputed

// Changing the rounding mode
Float::setRoundingMode(RoundingMode::TowardZero);
Float x("1.999");
x.setPrecision(3);  // Rounded with TowardZero