Feature Numbers

🔢 Числа (Num)

← Возможности · Главная · Сравнение

CloudCastle\Support\Num — числовые хелперы: форматирование с разделителями разрядов, проценты, человекочитаемые размеры данных и сокращения больших чисел, ограничение диапазоном, порядковые формы. Суперсет Illuminate\Support\Number, но без обязательного ext-intl и на порядок быстрее (см. Сравнение).

Принцип работы

• format($number, $decimals, $decimalSeparator, $thousandsSeparator) — число с разделителями групп разрядов; дефолты — русская типографика (пробел и запятая).
• fileSize($bytes, $precision, $locale) — размер данных по двоичной шкале (1024) с русскими («Б»…«ПБ») или английскими («B»…«PB») единицами; целые значения выводятся без хвоста «,0».
• abbreviate($number, $precision) — сокращённая запись: 1.3M, 2B, 3.5T.
• clamp($number, $min, $max) / between($number, $min, $max) — ограничение диапазоном и проверка принадлежности (границы включительно).
• percentOf($part, $total) — сколько процентов составляет часть (fail-safe: нулевое целое даёт 0.0, а не деление на ноль); percentage($percent, $total) — значение процента от числа.
• ordinal($number, $language) — порядковая форма через cloudcastle/inflector: 1st/2nd (en), 2-й (ru) — без ext-intl.
• pad($number, $length) — дополнение нулями слева: 007.

use CloudCastle\Support\Num;
use CloudCastle\Inflector\Language;

Num::format(1234567.891, 2);        // '1 234 567,89'  (русская типографика)
Num::format(1234567.891, 2, '.', ','); // '1,234,567.89'

Num::fileSize(1536);                // '1,5 КБ'
Num::fileSize(1073741824, 1, 'en'); // '1 GB'

Num::abbreviate(1250000);           // '1.3M'
Num::clamp(15, 1, 10);              // 10
Num::between(5, 1, 10);             // true

Num::percentOf(25, 200);            // 12.5
Num::percentOf(5, 0);               // 0.0 — fail-safe при пустой выборке

Num::ordinal(2);                    // '2nd'
Num::ordinal(2, Language::Russian); // '2-й'
Num::pad(7, 3);                     // '007'

Отличия от аналогов

Аспект	Num	illuminate Number
Зависимость от ext-intl	❌ не нужна	✅ обязательна
Русская шкала размеров («КБ», «МБ»)	✅	❌
Скорость format	~2.6M ops/s	~54K ops/s
Порядковые формы ru	✅ 2-й	❌ только en
fail-safe деление на ноль	✅ 0.0	исключение

Безопасность

• percentOf с нулевым целым возвращает 0.0 — метрики пустой выборки не роняют обработчик.
• fileSize нормализует отрицательный размер к нулю, неизвестная локаль откатывается на английскую шкалу — вывод стабилен на любом вводе.

См. также

• 🧮 Объекты (Obj)
• 📅 Дата и время (Dates)
• Сравнение производительности