====== PHP RFC: Add bcdivmod to BCMath ======
  * Version: 1
  * Date: 2024-06-30
  * Author: Saki Takamachi (saki@php.net)
  * Status: Implemented
  * First Published at: https://wiki.php.net/rfc/add_bcdivmod_to_bcmath

===== Introduction =====
BCMath has <php>bcdiv()</php> and <php>bcmod()</php>, and the operation must be performed twice to obtain both the quotient and remainder. This is also true for the <php>BcMath\Number</php> class. Due to BCMath's division mechanism, the quotient and remainder can be obtained in one operation, but the current API is not designed that way.

===== Proposal =====
This RFC proposes the addition of a new function <php>bcdivmod()</php> that can obtain the quotient and remainder in one operation, and the corresponding method <php>divmod()</php> of the <php>BcMath\Number</php> class.

This is clearly faster than doing the two operations separately.

The signature is:

<PHP>
/**  @return array{string, string} */
function bcdivmod(string $num1, string $num2, ?int $scale = null): array {}

/**  @return array{Number, Number} */
public function divmod(Number|string|int $num, ?int $scale = null, int $roundingMode = PHP_ROUND_HALF_UP): array {}
</PHP>

The return value is an array containing values ​​in the order of quotient and remainder. This is something like a tuple. For reference, the equivalent function in the GMP extension returns a similar array.

https://www.php.net/manual/ja/function.gmp-div-qr.php

An example usage is:

<PHP>
[$quot, $rem] = bcdivmod('123', '2');

// $quot is '61'
// $rem is '1'
</PHP>

<PHP>
$slicesOfPizza = new BcMath\Number(8);
$mouthsToFeed = new BcMath\Number(3);
[$perMouth, $slicesLeft] = $slicesOfPizza->divmod($mouthsToFeed);

// $perMouth->value is '2'
// $slicesLeft->value is '2'
</PHP>

Naming and return values ​​are inspired by Python and Ruby. 

Regarding return values, it was proposed in the mailing list discussion to return them as objects that have these as properties instead of an array. However, since BCMath has significantly better performance in PHP8.4, the overhead of creating the object is probably more significant, and I would still suggest returning the value in an array.

There was an idea to return the value by reference, but it was not adopted because current PHP tends to avoid such implementation.

===== Backward Incompatible Changes =====
In theory, this makes it impossible to define functions with the same name in userland. However, when I searched on Github Code Search, I couldn't find any code that used the function with the same name.

===== Proposed PHP Version(s) =====
next PHP 8.x (8.4)

===== RFC Impact =====
==== To SAPIs ====
None.

==== To Existing Extensions ====
Only BCMath.

==== To Opcache ====
None.

==== New Constants ====
None.

==== php.ini Defaults ====
None.

===== Open Issues =====
None.

===== Unaffected PHP Functionality =====
Nothing other than BCMath is affected.

===== Future Scope =====
None.

===== Proposed Voting Choices =====
As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

Voting started on 2024-07-17 and will end on 2024-08-01 00:00 GMT.

<doodle title="Add bcdivmod to BCMath" auth="Saki Takamachi" voteType="single" closed="false" closeon="2024-08-01T00:00:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
Yet.

===== Implementation =====
Yet.

===== References =====
https://externals.io/message/123812

===== Rejected Features =====

None.