TsnTables2/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"/>
  <a href="./LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-blue.svg"/>
  </a>
</p>

<p align="center">
Low-level base primitives for building fast parsers in MQL5: SWAR byte-scanning tricks, string hashing (FNV-1a, xxHash64),
 lookup tables for hex decoding and float parsing without <code>pow()</code>, and fast integer-to-string helpers.<br/> 
 No external dependencies — pure MQL5, meant to be included directly by higher-level parsers (JSON, YAML, SetFile, etc.).
</p>

---

## Main Features

- **SWAR byte-scanning (`Swar.mqh`)**: bit-trick macros (`TSNTABLES_SWAR_HAS`) to check 8 packed bytes at once against a delimiter mask (`"`, `\`, `,`, `:`, `\n`, etc.), plus a De Bruijn lookup table (`g_table_i64`) to find which byte matched — the base technique for scanning structured-text formats a full machine word at a time instead of byte by byte.
- **String hashing (`PHash/`)**: FNV-1a 64-bit (`FNV1a_64`, plus inlineable `FNV1a_64_AsM_*` macros) and a full xxHash64 implementation (`XSTR::XXH64` for `string`, `XU::XXH64` for `uchar[]`) — same algorithm, two entry points depending on the buffer type.
- **Fast float parsing tables (`Exp.mqh` / `Pow.mqh`)**: precomputed `1e-308`..`1e308` tables (`g_Exp10`, `g_Pow10`) to convert exponents during string→double conversion without calling `MathPow()`.
- **Hex decoding table (`Hex.mqh`)**: 256-entry lookup (`g_arr_valid_hex_chars`) mapping ASCII to its hex nibble (or `0xFF` if invalid), for decoding `\xXX` / `\uXXXX` escapes.
- **Fast digit-pair table (`DPairs.mqh`)**: 200-entry table (`g_tsn_digit_pairs`) with pre-built two-digit strings `"00"`..`"99"`, for writing integers two digits at a time instead of one.
- **Escape/unescape sentinels (`EscapeUnescape.mqh`)**: shared sentinel codes (`0xFD` hex, `0xFE` unicode, `0xFF` invalid/passthrough) that define the contract consumers use when building their own escape tables.

### Usage examples

**Scan 8 bytes for a delimiter (SWAR):**

```mql5
#include <TsnTables\\Src\\Swar\\Swar.mqh>

ulong word;   // 8 packed bytes read from the buffer
ulong flags = TSNTABLES_SWAR_HAS(word ^ TSNTABLES_SWAR_MASK_COMILLA); // busca '"'
if(flags != 0)
 {
  int byte_index = int(TSNTABLES_SWAR_64_GET_BYTE(flags & (~flags + 1)));
  Print("Comilla encontrada en el byte ", byte_index);
 }
```

**Hash a string (xxHash64):**

```mql5
#include <TsnTables\\Src\\PHash\\XXHash\\Main.mqh>

string s = "hola mundo";
ulong h = TSN::XSTR::XXH64(s, StringLen(s), 5105151ULL);
Print("Hash: ", h);
```

**Convert an exponent without MathPow:**

```mql5
#include <TsnTables\\Src\\Exp.mqh>

double value = 1.5 * TSN::g_Pow10[3]; // 1.5 * 1000.0 = 1500.0
```

---

## Repository Structure

```
TsnTables/
├── Src/
│   ├── Swar/                 # SWAR byte-scanning macros + De Bruijn tables
│   │   ├── Swar.mqh
│   │   └── TableConstant.mq5 # script that regenerates the De Bruijn table
│   ├── PHash/                # String hashing algorithms
│   │   ├── AllHash.mqh       # includes both hashers
│   │   ├── FNV1-1A/Main.mqh
│   │   ├── XXHash/           # Def, Main, XString (string), XU (uchar[])
│   │   └── Test.mq5
│   ├── DPairs.mqh            # Digit-pair table for fast int-to-string
│   ├── EscapeUnescape.mqh    # Escape/unescape sentinel codes
│   ├── Exp.mqh               # 1e-308..1e308 table
│   ├── Hex.mqh               # ASCII-to-hex-nibble table
│   ├── Pow.mqh               # 1e0..1e308 table
│   └── Tables.mqh            # true/false byte arrays + misc constants
└── LICENSE
```

---

## Requirements

- MetaTrader 5
- No external dependencies (base repository, no `dependencies.json`)

---

## Installation

```bash
cd "C:\Users\YOUR_USER\AppData\Roaming\MetaQuotes\Terminal\YOUR_ID\MQL5\Shared Projects"
tsndep install "https://forge.mql5.io/nique_372/TsnTables.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 module you need:**

```mql5
#include <TsnTables\\Src\\PHash\\AllHash.mqh>
```

**2. Use it:**

```mql5
ulong h = TSN::FNV1a_64("clave", 5);
```

---

## 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