166 lines
4.3 KiB
Markdown
166 lines
4.3 KiB
Markdown
# 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
|