fast_json/README.md

# fast_json v3.7.0 — High-Performance MQL5 JSON Library

> "If your JSON parser needs recursion, you're doing it wrong."

## Overview

**fast_json** is a production-grade, high-performance JSON library for MQL5, engineered for scenarios where **I/O throughput** and **memory efficiency** are paramount.

Unlike standard libraries that fragment the heap with thousands of small object allocations, **fast_json** employs a **tape-based zero-allocation memory model**. It parses JSON directly into a contiguous integer array (the "tape"), enabling it to process gigabytes of data with minimal overhead and zero garbage collection pressure.

## Key Features

- **🚀 Zero-Alloc Tape Architecture**: Parses the entire JSON into a single contiguous integer array. No objects are created during parsing. 
- **⚡ SWAR Acceleration**: Uses Simulated 64-bit SWAR (SIMD within a Register) to scan 8 bytes at a time for structural characters and backslash detection.
- **🔢 Decomposed Number Parser**: XOR-first pattern with single-pass integer accumulation (fxsaber architecture). Extended Pow10 tables cover full `DBL_MAX_10_EXP` — zero `MathPow` calls at runtime.
- **🛡️ Stack-Safe Iterative Parser**: Finite state machine. Zero recursion. Immune to stack overflow.
- **🔧 Handle-Based Navigation**: Lightweight `CJsonNode` structs that point to the tape. Copying nodes is free.
- **📡 Direct Buffer Parsing**: `ParseBuffer(uchar&[])` accepts raw byte arrays — zero `StringToCharArray` overhead for WebSocket/WebRequest data.
- **⚙️ Branchless Internals**: HexToDec lookup table, packed key format with embedded length, direct byte serialization for literals.

## Performance

| Metric | fast_json | Standard Libs |
|--------|-----------|---------------|
| **Allocation Strategy** | 1 contiguous block (Tape) | N objects per node |
| **Recursion Depth** | Unlimited (Heap stack) | Limited (Call stack) |
| **Read/Write Speed** | **EXTREME** (300MB/s+ Est.) | LOW |
| **Memory Fragmentation**| Near Zero | High |
| **Number Parsing** | XOR-first + Pow10 tables | `StringToDouble` |
| **Key Lookup** | FNV-1a hash (24-bit + length) | O(N) linear scan |

## Usage

### Parsing from string
```cpp
#include <fast_json.mqh>

CJson toolkit;
string json = "{\"price\": 1.2345, \"currency\": \"EURUSD\"}";

if (toolkit.Parse(json)) {
    double price = toolkit["price"].ToDouble();
    string curr  = toolkit["currency"].ToString();
    Print(curr, ": ", price);
} 
```

### Parsing from uchar buffer (WebSocket/WebRequest)
```cpp
uchar data[];
int data_len = /* receive from WebSocket */;

CJson toolkit;
if (toolkit.ParseBuffer(data, data_len)) {
    double bid = toolkit["bid"].ToDouble();
}
```

### Building & Serializing
```cpp
CJsonBuilder builder;
builder.Obj()
       .Key("signal").Val("buy")
       .Key("volume").Val(0.1)
       .EndObj();

string payload = builder.Build();
// Result: {"signal":"buy","volume":0.1}
```

## Why fast_json?

Because typical MQL5 libraries were designed for configuration files, not high-throughput data streams. **fast_json** bridges that gap.

## Credits

- **fxsaber** — XOR-first decomposed number parser architecture
- **Sunriser** — Bug reports #1 (boolean encoding) and #2 (ToString type safety)

## License

MIT.