Inital commit after splitting from main project

README.md

@@ -0,0 +1,165 @@
+# tez-utils-num
+
+PHP number utilities: formatting, byte sizes, percentage, clamping, and rounding helpers (`Num`), plus arbitrary-precision decimal arithmetic via bcmath (`Bc`). PHP 8.3+, requires `ext-bcmath`.
+
+## Installation
+
+```bash
+composer require tez/utils-num
+```
+
+## Components
+
+| Class | Purpose |
+|-------|---------|
+| `Num` | Formatting, byte sizes, percentages, clamping, rounding |
+| `Bc` | Arbitrary-precision decimal arithmetic wrapping `ext-bcmath` |
+
+---
+
+## Num
+
+Formatting and rounding helpers for everyday number display.
+
+### format()
+
+```php
+use Tez\Utils\Num\Num;
+
+Num::format(1234567.891);                              // '1,234,567.89'
+Num::format(1234567.891, dec: ',', thousands: '.');    // '1.234.567,89'
+Num::format(1234.5, decimals: 0);                      // '1,235'
+Num::format(-1000.0);                                  // '-1,000.00'
+```
+
+### bytes()
+
+Converts a byte count to a human-readable string using binary units (1 KB = 1 024 B).
+
+```php
+Num::bytes(0);           // '0 B'
+Num::bytes(1023);        // '1,023 B'
+Num::bytes(1024);        // '1.00 KB'
+Num::bytes(1048576);     // '1.00 MB'
+Num::bytes(1073741824);  // '1.00 GB'
+Num::bytes(1024 ** 4);   // '1.00 TB'
+Num::bytes(1500, precision: 0); // '1 KB'
+```
+
+### percent()
+
+Formats a ratio (`0.0`–`1.0`) as a percentage string.
+
+```php
+Num::percent(0.1234);              // '12.3%'
+Num::percent(1.0);                 // '100.0%'
+Num::percent(0.0056, decimals: 2); // '0.56%'
+```
+
+### clamp()
+
+Constrains a value to the inclusive range `[$min, $max]`.
+
+```php
+Num::clamp(105, 0, 100);   // 100
+Num::clamp(-5,  0, 100);   // 0
+Num::clamp(50,  0, 100);   // 50
+Num::clamp(1.5, 0.0, 0.5); // 0.5
+```
+
+### roundTo()
+
+Rounds a value to the nearest multiple of `$multiple`.
+
+```php
+Num::roundTo(17, 5);   // 15
+Num::roundTo(18, 5);   // 20
+Num::roundTo(1.7, 0.5); // 1.5
+```
+
+---
+
+## Bc
+
+Arbitrary-precision decimal arithmetic wrapping PHP's `bcmath` extension. Designed for financial calculations where floating-point imprecision is not acceptable.
+
+**All inputs must be numeric strings** (e.g. `'1.50000000'`). Passing a non-numeric string throws `\InvalidArgumentException`. Division by zero throws `\DivisionByZeroError`.
+
+The default scale is **8 decimal places** for all methods.
+
+### Arithmetic
+
+```php
+use Tez\Utils\Num\Bc;
+
+Bc::add('10.5', '20.3');          // '30.80000000'
+Bc::sub('20.3', '11.1');          // '9.20000000'
+Bc::mul('4', '5');                 // '20.00000000'
+Bc::div('1', '3');                 // '0.33333333'
+Bc::div('1', '3', scale: 2);      // '0.33'
+
+// Array operations
+Bc::sum(['1', '2', '3']);          // '6.00000000'
+Bc::sum([]);                       // '0.00000000'
+Bc::product(['2', '3', '4']);      // '24.00000000'
+Bc::product([]);                   // '1.00000000'
+Bc::subAll(['10', '3', '2']);      // '5.00000000'  (10 - 3 - 2)
+Bc::divAll(['100', '5', '4']);     // '5.00000000'  (100 / 5 / 4)
+```
+
+### Utilities
+
+```php
+Bc::abs('-5');                     // '5.00000000'
+Bc::negate('3.14');                // '-3.14000000'
+Bc::negate('-5');                  // '5.00000000'
+Bc::max('10', '5');                // '10.00000000'
+Bc::min('10', '3');                // '3.00000000'
+Bc::scale('1.5');                  // '1.50000000'  — normalize to 8 decimal places
+Bc::scale('1.123456789');          // '1.12345678'  — truncates, does not round
+Bc::percent('200', '15');          // '30.00000000' — 15% of 200
+```
+
+### Comparisons
+
+```php
+Bc::compare('10', '5');    // 1   (greater)
+Bc::compare('5', '10');    // -1  (less)
+Bc::compare('5.00', '5'); // 0   (equal)
+
+Bc::eq('5.00', '5.000');   // true
+Bc::gt('10', '5');          // true
+Bc::lt('3', '7');           // true
+Bc::gte('5', '5');          // true
+Bc::lte('3', '7');          // true
+
+Bc::isZero('0.00000000');   // true
+Bc::isZero('0.00000001');   // false
+Bc::isPositive('0.00000001'); // true
+Bc::isNegative('-0.00000001'); // true
+```
+
+### Scale behaviour
+
+`Bc::scale()` truncates (does not round). All arithmetic methods default to scale 8 and accept an explicit `scale` parameter:
+
+```php
+Bc::add('10.5', '20.3', scale: 2); // '30.80'
+Bc::div('1', '3', scale: 4);       // '0.3333'
+
+// Equal at scale 2, different at scale 8
+Bc::eq('5.001', '5.009', scale: 2); // true
+Bc::eq('5.001', '5.009');           // false
+```
+
+---
+
+## Requirements
+
+- PHP 8.3+
+- `ext-bcmath`
+- `tez/utils-validate` ^1.0
+
+## License
+
+MIT