====== PHP RFC: intdiv() ======
  * Version: 0.2
  * Date: 2014-07-15 (Last updated 2014-07-16)
  * Author: Andrea Faulds, ajf@ajf.me
  * Status: Accepted (Fallback proposal; operator rejected), merged into master
  * First Published at: http://wiki.php.net/rfc/intdiv


===== Introduction =====

PHP currently lacks a way to do integer division. While ''(int)(3 / 2)'', which does a floating-point division then casts to integer, does work most of the time, it does not return the correct result for integers beyond 53 bits as floats cannot represent integers beyond that point without loss of information. Furthermore, doing a floating-point division then casting seems hackish; it is a workaround for a lack of integer division, not a proper way to do it. Integer division can be quite useful in some contexts, for example when splitting a value into rows and columns, or converting seconds to hours and minutes. Having this also makes the language more complete; we have integer remainder (the modulo operator, //%//) yet not integer division at present.

===== Proposal =====

A new infix operator is added:

<code php>
var_dump(3 %% 2); // int(1)
</code>

It returns the integer division of the first operand by the second. If the divisor (the second operand) is zero, it throws an E_WARNING and returns FALSE, just as the division operator does. If the first operator is ''LONG_MIN'' (''-PHP_INT_MAX - 1'') and the second is ''-1'', it returns zero, much like the ''%'' operator.

Assignment is also supported:

<code php>
$foobar = 3;
$foobar %%= 2;
var_dump($foobar); // int(1)
</code>

==== Fallback proposal ====

The original proposal was just to add a function. Should the operator fail to get in, I instead propose a new function is added to ext/standard's math functions:

<code php>
intdiv(int $numerator, int $divisor)
</code>

It returns the integer division of //$numerator// by //$divisor//. If //$divisor// is zero, it throws an E_WARNING and returns FALSE, just as the division operator does. If the first operator is ''LONG_MIN'' (''-PHP_INT_MAX - 1'') and the second is ''-1'', it returns zero, much like the ''%'' operator.

===== Backward Incompatible Changes =====

The ''%''''%'' operator wouldn't conflict with anything.

The fallback proposal, ''intdiv'', would conflict with any existing userland functions called intdiv, but that's unlikely.

===== Proposed PHP Version(s) =====

Next PHP 5.x (i.e. PHP 5.7).

===== Future Scope =====

None I can see.

===== Vote =====

Two votes are being held simultaneously:

  - Merge the intdiv operator (''%''''%'') patch into master? Yes/No (requires 2/3 majority, language change)
  - If the ''%''''%'' operator vote fails to achieve a 2/3 majority, should the intdiv() function patch be merged into master? Yes/No (requires 50%+1 majority, non-language change)

As the ext/standard function is to be considered a fallback option only, it would not be merged if the proper operator gets in.

Voting opened 2014-07-30 and ended 2014-08-06.

<doodle title="Merge the intdiv operator patch into master?" auth="ajf" voteType="single" closed="true">
   * Yes
   * No
</doodle>

----

<doodle title="If the operator vote fails to achieve a 2/3 majority, should the intdiv() function patch be merged into master?" auth="ajf" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

A fully-working patch against master with tests has been made. The pull request is here: https://github.com/php/php-src/pull/724

The pull request for the fallback (and original proposal) of just the //ext/standard// function is here: https://github.com/php/php-src/pull/722

===== Implementation =====

It was merged into master here: https://github.com/php/php-src/commit/8e964fe665b6a4fbdc59639dad2efb4cd43d1c05

It will be in PHP 7. Since there is no 5.7 branch, it is doubtful it will actually be in 5.7.

PHP Manual - http://php.net/manual/en/function.intdiv.php

===== References =====

Somewhat inspired by Python's ''/''''/'' operator, and the equivalent //div// operator in Pascal and Game Maker Language (a somewhat obscure C-like partially object-oriented scripting language, which probably inherited this from Pascal). The choice of the ''%''''%'' syntax is thanks to Bishop Bettini's suggestion on internals.

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

None yet.

===== Changelog =====

  * 0.2 - Propose ''%''''%'' operator instead
  * 0.1 - Created, intdiv() function