Feature/allocate

[sagikazarmark]

allocate now supports the following form: $m->allocate(1, 1, 1) (array can be ommited)

Adds allocateTo: Divides the amount to N equal values (the remainder is shared between the first K results)

Example:

$m = new Money::EUR(15);

// Returns [8, 7]
$m->allocateTo(2);

Please merge #55 before, so I can rebase this if needed

[mathiasverraes]

I really dislike supporting two styles of methods. It creates confusion and bugs. Array is the best choice because it reflects the fact that it is a list of variable length.

[sagikazarmark]

It does not mean you cannot use arrays. If it is mentioned in the docs you just go with it and don't use any other way. However, IMO using array is the same as using many parameters. At the end, they also become an array.

[mathiasverraes]

I understand why it appeals, but it is really bad practice in php. If we had method overloading, there'd be a case for it. It also has no cognitive overload as allocate([1, 2]) is just as easy to read and understand as allocate(1, 2).
Unless you have a problem that is better solved with a variadic definition, I'm sticking with arrays.

[sagikazarmark]

Reverting it then.

[mathiasverraes]

• Adapt documentation

[sagikazarmark]

Is it possible to merge this PR and collect all documentation in one PR?

[sagikazarmark]

Reverted functionality