romainnorberg/residue

Divide a float into several parts, with distribution of any remainder

Residue ⚖️

Divide a float into several parts, with distribution of any remainder.

Introduction

This dependency-free package provides a split method to help you split float into parts, with the possible distribution of any remainder.

It is also possible to specify a rounding of the divided amount, for example rounding by 0.05.

🕹 Try out Residue on the online tester! »

Installation

You can install the package via composer:

composer req romainnorberg/residue

Requirements

This package require >= PHP 7.4

Residue VS Brick\Money

This package does not deal with the notion of currency and being more basic, it is up to 40 times faster on basic operations than the brick/money package

Benchmarks: residue-vs-brick-money

Usage / examples

Basic split

Residue::create(100)->divideBy(3)->split(); // -> \Generator[33.34, 33.33, 33.33]

// or

Residue::create(100)->divideBy(3)->toArray(); // -> [33.34, 33.33, 33.33]

Split with rounding (and remainder)

Residue::create(100)
            ->divideBy(3)
            ->step(0.05)
            ->split(); // -> \Generator[33.35, 33.35, 33.30]

With remainder:

$r = Residue::create(7.315)
                ->divideBy(3)
                ->step(0.05);

$r->split(); // -> \Generator[2.45, 2.45, 2.40]
$r->getRemainder(); // -> 0.015

Split mode

SPLIT_MODE_ALLOCATE is default mode and try to allocate the maximum of the value according to step.

$r = Residue::create(100)
            ->divideBy(3)
            ->decimal(0);

$r->split(); // -> \Generator[34, 33, 33]
$r->getRemainder(); // 0

//

$r = Residue::create(101)
            ->divideBy(3)
            ->decimal(0);

$r->split(); // -> \Generator[34, 34, 33]
$r->getRemainder(); // 0

SPLIT_MODE_EQUITY mode try to allocate equally the maximum of the value according to step.

$r = Residue::create(100)
            ->divideBy(3)
            ->decimal(0);

$r->split(Residue::SPLIT_MODE_EQUITY); // -> \Generator[33, 33, 33]
$r->getRemainder(); // 1

//

$r = Residue::create(101)
            ->divideBy(3)
            ->decimal(0);

$r->split(Residue::SPLIT_MODE_EQUITY); // -> \Generator[33, 33, 33]
$r->getRemainder(); // 2

Generator

This package uses generator to reduce the memory used

With foreach statement (using generator):

$r = Residue::create(100)->divideBy(3);
foreach ($r->split() as $part) {
    var_dump($part);
}

float(33.34)
float(33.33)
float(33.33)

To array:

$r = Residue::create(100)->divideBy(3);
var_dump($r->toArray());

array(3) {
  [0]=>
  float(33.34)
  [1]=>
  float(33.33)
  [2]=>
  float(33.33)
}

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Romain Norberg
• All Contributors
• Illustration from Refactoring.Guru https://refactoring.guru/

License

The MIT License (MIT). Please see License File for more information.