BigNumberByLeo/README.md

<p align="center">
  <img src="https://img.shields.io/badge/Language-MQL5-1B6CA8?style=flat-square"/>
  <img src="https://img.shields.io/badge/Platform-MetaTrader%205-0D1B2A?style=flat-square"/>
  <img src="https://img.shields.io/badge/Author-nique__372-C9D6DF?style=flat-square&logoColor=white"/>
  <img src="https://img.shields.io/badge/MQL5.com-nique__372-1B6CA8?style=flat-square"/>
</p>

<p align="center">
Arbitrary-precision unsigned integer library for MQL5.<br/> Limb-based (<code>ulong[]</code>) arithmetic, ~90% complete.
</p>

---

## Main Features

- **Arbitrary-precision `BigUInteger`**: base type backed by a `ulong[]` limb array, construct from a `long`, a decimal `string`, raw bytes, or an existing limb array
- **Full arithmetic**: `+`, `-`, `*`, `/`, `%` — each with both `BigUInteger` and `long` operands, plus in-place (`+=`, `-=`, etc.) variants
- **Bitwise operators**: `&`, `|`, `^`, `~`, `<<`, `>>`, both in-place and returning a new value
- **Comparisons**: `>`, `>=`, `==`, `!=`, `<`, `<=`, plus `IsZero()` / `IsNotZero()`
- **Fast multiplication**: schoolbook multiplication (working), with **Karatsuba** for large operands **in progress**
- **Modular exponentiation**: `PowMod(exp, mod)` — **pending implementation**
- **Primality testing**: `IsProbablePrime(rounds)` (Miller-Rabin style) — **pending implementation**
- **GCD**: standard `Gdc()` (working) and **extended GCD** (`GdcExtendedRetX`, for modular inverse) — **pending implementation**
- **Byte/string conversion**: `FromBytesLE/BE`, `ToBytesLE/BE`, `ToString`
- **Random generation**: `InitRandom<TRandom>(limbs)`, pluggable with any RNG source
- **Low-level numeric utilities** (`CNumberUtils`): 64x64→128 multiply, 128/64-bit division, hex string conversion

### Usage examples

**Basic arithmetic:**

```mql5
#include "Src\\Base\\Main.mqh"

ulong v[];
ArrayResize(v, 1);
v[0] = 64;
TSN::BigUInteger integer(v, 1);

integer /= 8;      // 8
integer %= 6;      // 2
```

**Standard GCD:**

```mql5
TSN::BigUInteger a("123456789", 10);
ulong gcd = a.Gdc(987654321);
```

> `PowMod`, `IsProbablePrime` and `GdcExtendedRetX` are declared in the API but not yet implemented — see [Roadmap](#roadmap).

---

## Repository Structure

```
BigNumberByLeo/
├── Src/
│   ├── Base/    # BigUInteger core (arithmetic, bitwise, comparisons, primality, GCD)
│   └── Utils/   # Low-level numeric helpers (CNumberUtils)
└── Test/        # Scripts covering ops, division, multiplication, misc
```

---

## Requirements

See [dependencies.json](./dependencies.json) for the full list.

- MetaTrader 5, build 5430+
- Depends on `TsnTables` (public, installed automatically via `tsndep`)

---

## Installation

```bash
cd "C:\Users\YOUR_USER\AppData\Roaming\MetaQuotes\Terminal\YOUR_ID\MQL5\Shared Projects"
tsndep install "https://forge.mql5.io/nique_372/BigNumberByLeo.git"
```

Requires the `tsndep` package, available on [PyPI](https://pypi.org/project/tsndep). It automatically downloads and installs all declared dependencies.

---

## Quick Start

**1. Include the library:**

```mql5
#include "..\\BigNumberByLeo\\Src\\Base\\Main.mqh"
```

**2. Use it:**

```mql5
TSN::BigUInteger a("340282366920938463463374607431768211456", 10);
TSN::BigUInteger b(2);

TSN::BigUInteger c = a * b;
```

---

## License

**[Read Full License](./LICENSE)**
By downloading or using this repository, you accept the license terms.

---

## Contact

- **Platform:** [MQL5 Community](https://www.mql5.com/es/users/nique_372)
- **Profile:** https://www.mql5.com/es/users/nique_372
- **Articles:** https://www.mql5.com/es/users/nique_372/publications

---

## Roadmap

- Core arithmetic, bitwise ops, comparisons, schoolbook multiplication, standard GCD, byte/string conversion [Complete]
- Karatsuba multiplication for large operands [In progress]
- `PowMod` (modular exponentiation) [Pending]
- `IsProbablePrime` (Miller-Rabin) [Pending]
- `GdcExtendedRetX` (extended GCD / modular inverse) [Pending]

<p align="center"><sub>Copyright © 2026 Niquel & Leo — TSN Ecosystem</sub></p>