Utility library for numerics. Float versions of ceil(), floor() and rand() with precision. An open minded numeric parser, formatter, plus some additional functions.

Current version supports PHP ^7.1.

Installation

Install with Composer;

composer require phrity/util-numerics

The Numerics class

Class synopsis

Phrity\Util\Numerics {

    /* Methods */
    public __construct(int $precision = 0)
    public ceil(number $number, int $precision = null) : float
    public floor(number $number, int $precision = null) : float
    public round(number $number, int $precision = null) : float
    public parse(mixed $numeric) : float
    public format(number $number, int $precision = null) : string
    public rand(number $min = 0, number $max = 0, int $precision = null) : float
    public precision(number $number) : int
    public setLocale(string $locale) : void
}

Constructor

The constructor accepts default precision. Precision can also be negative to achive integer rounding.

$numerics = new Numerics(); // Default precision is 0
$numerics = new Numerics(3); // Default precision is 3

Ceil method

Round fractions up, according to precision specifier. A precision of 0 corresponds to PHP ceil() function. Precision can also be negative.

// Precison specified on each call
$numerics = new Numerics();
$numerics->ceil(1234.5678,  2) // 1234.57
$numerics->ceil(1234.5678,  1) // 1234.60
$numerics->ceil(1234.5678,  0) // 1235.00
$numerics->ceil(1234.5678, -1) // 1240.00
$numerics->ceil(1234.5678, -2) // 1300.00

// Precison specified as default, override is possible
$numerics = new Numerics(2);
$numerics->ceil(1234.5678) // 1234.57
$numerics->ceil(1234.5678, 0) // 1235.00

Floor method

Round fractions down, according to precision specifier. A precision of 0 corresponds to PHP floor() function. Precision can also be negative.

// Precison specified on each call
$numerics = new Numerics();
$numerics->floor(1234.5678,  2) // 1234.56
$numerics->floor(1234.5678,  1) // 1234.50
$numerics->floor(1234.5678,  0) // 1234.00
$numerics->floor(1234.5678, -1) // 1230.00
$numerics->floor(1234.5678, -2) // 1200.00

// Precison specified as default, override is possible
$numerics = new Numerics(2);
$numerics->floor(1234.5678) // 1234.56
$numerics->floor(1234.5678, 0) // 1234.00

Round method

Standard round, according to precision specifier. Precision can also be negative.

// Precison specified on each call
$numerics = new Numerics();
$numerics->round(1234.5678,  2) // 1234.57
$numerics->round(1234.5678,  1) // 1234.60
$numerics->round(1234.5678,  0) // 1235.00
$numerics->round(1234.5678, -1) // 1230.00
$numerics->round(1234.5678, -2) // 1200.00

// Precison specified as default, override is possible
$numerics = new Numerics(2);
$numerics->round(1234.5678) // 1234.57
$numerics->round(1234.5678, 0) // 1235.00

Parse method

Numeric parser. Parses number by evaluating input rather than using locale or making explicit assumtions. Returns float, or null if provided input can not be parsed.

$numerics = new Numerics();

// Integer and float input
$numerics->parse(1234.56) // 1234.56
$numerics->parse(1234) // 1234.00

// String input
$numerics->parse('1234.56') // 1234.56
$numerics->parse('1234,56') // 1234.56
$numerics->parse('1 234.56') // 1234.56
$numerics->parse('1 234,56') // 1234.56
$numerics->parse('1,234.56') // 1234.56
$numerics->parse('1.234,56') // 1234.56

// Evaluated string input
$numerics->parse(' 1 234.56 ') // 1234.56
$numerics->parse('-1,234.56') // -1234.56
$numerics->parse('+1.234,56') // 1234.56
$numerics->parse('.56') // 0.56
$numerics->parse(',56') // 0.56
$numerics->parse('12.') // 12.0
$numerics->parse('12,') // 12.0

// Locale support for fringe cases
$numerics->setLocale('sv_SE');
$numerics->parse('123,456') // 123.456
$numerics->setLocale('en_US');
$numerics->parse('123,456') // 123456.0

Format method

Numeric formatter. Formats numbers according to precision (rounding and padding) and locale.

$numerics = new Numerics();

$numerics->setLocale('sv_SE');
$numerics->format(1234.5678, 2) // "1 234,56"
$numerics->format(1234, 2) // "1 234,00"
$numerics->format(1234.5678, 0) // "1 234"

$numerics->setLocale('en_US');
$numerics->format(1234.5678, 2) // "1,234.56"
$numerics->format(1234, 2) // "1,234.00"
$numerics->format(1234.5678, 0) // "1,234"

Rand method

Float random number with precision. Precision can also be negative. Returns float, or null if impossible to generate result.

// Precison specified on each call
$numerics = new Numerics();
$numerics->rand(0, 10) // 0.0 … 10.0
$numerics->rand(0, 100, 2) // 0.00 … 100.00
$numerics->rand(-100, 100, 4) // -100.0000 … 100.0000
$numerics->rand(0.01, 0.97, 4) // 0.0100 … 0.9700
$numerics->rand(9, 11, -1) // 10.0
$numerics->rand(90, 110, -2) // 100.0

// Precison specified as default, override is possible
$numerics = new Numerics(2);
$numerics->rand(0, 100) // 0.00 … 100.00

Precision method

Count number of relevant decimals in a number.

$numerics = new Numerics();
$numerics->precision(12) // 0
$numerics->precision(12.0) // 0
$numerics->precision(12.34) // 2

setLocale method

Affects the format() method and fringe case in parse() method. If not set, current locale will be used in these methods.

$numerics = new Numerics();
$numerics->setLocale('sv_SE'); // Set to Swedish

Versions

• 2.0 - Instanceable, format() method, ability to specify locale (PHP ^7.1)
• 1.2 - rand() and precision() methods (PHP 5.6|^7.0)
• 1.1 - parse() method (PHP 5.6|^7.0)
• 1.0 - ceil() and floor() methods (PHP 5.6|^7.0)