Getting Started with BigFloat

Learn how to install and start using BigFloat in your C# projects

On This Page

Requirements

📦

.NET 9 or later

BigFloat uses modern C# features that require .NET 9+

⚙️

C# 11 or later

Language features from C# 11 are utilized throughout the library

💾

System.Numerics

BigInteger support is required (included in .NET)

Installation

Method 1: NuGet Package (Recommended)

The easiest way to add BigFloat to your project is via NuGet:

Using Package Manager Console:

Install-Package BigFloatLibrary

Using .NET CLI:

dotnet add package BigFloatLibrary

Using PackageReference in .csproj:

<PackageReference Include="BigFloatLibrary" Version="*" />

Method 2: Source Code

For maximum control or to contribute to development:

Clone the repository:

git clone https://github.com/SunsetQuest/BigFloat.git

Add to your project:

  1. Copy the BigFloatLibrary folder to your solution
  2. Add a project reference in your .csproj file
  3. Optional: Include Constants.cs for mathematical constants

Your First BigFloat Program

Let's create a simple program that demonstrates BigFloat's precision advantages:

Program.cs
using System;
using BigFloatLibrary;

class Program
{
    static void Main()
    {
        // Problem: 0.1 + 0.2 != 0.3 in standard floating point
        double d1 = 0.1;
        double d2 = 0.2;
        double d3 = d1 + d2;
        Console.WriteLine($"Double: {d1} + {d2} = {d3}");
        Console.WriteLine($"Is 0.1 + 0.2 == 0.3? {d3 == 0.3}"); // False!
        
        // Solution: BigFloat maintains precision
        BigFloat b1 = new("0.1");
        BigFloat b2 = new("0.2");
        BigFloat b3 = b1 + b2;
        Console.WriteLine($"\nBigFloat: {b1} + {b2} = {b3}");
        Console.WriteLine($"Is 0.1 + 0.2 == 0.3? {b3 == new BigFloat("0.3")}"); // True!
        
        // High precision calculation
        BigFloat pi = Constants.Fundamental.Pi;
        BigFloat radius = new("10.123456789");
        BigFloat area = pi * radius * radius;
        Console.WriteLine($"\nCircle area with radius {radius}:");
        Console.WriteLine($"Area = {area}");
    }
}

Expected Output:

Double: 0.1 + 0.2 = 0.30000000000000004
Is 0.1 + 0.2 == 0.3? False

BigFloat: 0.1 + 0.2 = 0.3
Is 0.1 + 0.2 == 0.3? True

Circle area with radius 10.123456789:
Area = 321.7526058894951

Basic Operations

Creating BigFloat Values

// From string (most precise)
BigFloat a = new("123.456789012345678901234567890");

// From double
BigFloat b = new(3.14159265358979323846);

// From integer
BigFloat c = new(42);

// From BigInteger
BigInteger bigInt = BigInteger.Parse("123456789012345678901234567890");
BigFloat d = new(bigInt);

// With specific precision
BigFloat e = BigFloat.IntWithAccuracy(10, 100); // 10 with 100 bits precision

Arithmetic Operations

BigFloat x = new("100.5");
BigFloat y = new("25.25");

// Basic arithmetic
BigFloat sum = x + y;        // 125.75
BigFloat diff = x - y;       // 75.25
BigFloat prod = x * y;       // 2537.625
BigFloat quot = x / y;       // 3.98...
BigFloat rem = x % y;        // 0.5

// Unary operations
BigFloat neg = -x;           // -100.5
BigFloat abs = BigFloat.Abs(x);  // 100.5

Comparisons

BigFloat a = new("100.1");
BigFloat b = new("100.2");

// Comparison operators
bool isEqual = a == b;       // false
bool isNotEqual = a != b;    // true
bool isLess = a < b;         // true
bool isGreater = a > b;      // false
bool isLessOrEqual = a <= b; // true
bool isGreaterOrEqual = a >= b; // false

// CompareTo method
int comparison = a.CompareTo(b); // -1 (a < b)

Type Conversions

BigFloat bf = new("123.456");

// Check if fits in standard type
if (bf.FitsInADouble())
{
    double d = (double)bf;
}

// Explicit conversions
int intValue = (int)bf;      // 123 (truncates)
long longValue = (long)bf;   // 123
decimal decValue = (decimal)bf; // 123.456

// To string with format
string str1 = bf.ToString();      // "123.456"
string str2 = bf.ToString("E");   // "1.23456E+2"
string str3 = bf.ToString("X");   // Hexadecimal

Understanding Precision

🔍 Key Concept: Guard Bits

BigFloat maintains 32 "guard bits" as hidden extra precision. These bits help maintain accuracy through chains of operations, preventing cumulative rounding errors.

Precision in Action

Precision Examples
// When you see output like "232XXXXXXXX", the X's indicate out-of-precision digits
BigFloat large = new("232000000000");
Console.WriteLine(large); // May display as "232XXXXXXXX" or "2.32e+11"

// Parsing with precision separator
// Format: "precise_part|guard_bits"
BigFloat precise = BigFloat.Parse("123.456|789");
Console.WriteLine($"Value: {precise}");

// Setting specific precision
BigFloat original = new("3.14159265358979323846264338327950288");
BigFloat rounded = BigFloat.SetPrecisionWithRound(original, 100); // 100 bits

// Extending precision (adds zeros, doesn't add information)
BigFloat extended = BigFloat.ExtendPrecision(original, 50);

⚠️ Important: Base-2 vs Base-10

BigFloat uses binary (base-2) internally. Most decimal numbers cannot be represented exactly in binary, leading to small precision differences:

  • 0.1 in decimal = 0.00011001100110011... (repeating) in binary
  • 0.25 in decimal = 0.01 (exact) in binary

Next Steps

📚

API Documentation

Explore the complete API reference with all methods, properties, and advanced features.
💡

Code Examples

See practical examples including financial calculations, scientific computing, and more.
🏗️

Architecture Deep Dive

Understand how BigFloat works internally, including the scale system and optimizations.

Need Help?

If you run into issues or have questions: