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.

residue's Issues

Talk about division and visibility

Hello Romain

I open this issue to discuss two points:

• Can a division really be negative? Is there any sense in doing Residue::create(100)->divideBy(-3)? I sincerely ask myself this question and have no idea in either direction.

• All methods are public, but I think that many of them don't make sense to be public.

Waiting for your feedback

About edge case

Hi @romainnorberg,

Sorry for a so soon come back of myself to discuss about a new edge case :

Consider this test :

yield [
    100, // value
     5, // divide
     null, // decimal value
     45, // step
     [
         45,
         45,
         0,
         0,
         0,
     ], // expected result
     10, // remainder
];

Of course, it pass perfectly, but maybe it should not... nothing to distribute to 3, 4, and 5 part seems strange in a way...

What do you think ?

According to the set of equation, we can quickly determine if everyone will have something distributed.

The only check to do, it's to check if Divder is greater than Ns. If it is, we can throw an error...Of course, if we consider that this is the expected behaviour.

In the same way, this is a fully valid test :

yield [
    100, // value
     5, // divide
     null, // decimal value
     150, // step
     [
         0,
         0,
         0,
         0,
         0,
     ], // expected result
     100, // remainder
];