====== PHP RFC: Stochastic Rounding Mode ======
  * Version: 0.9
  * Date: 2024-07-02
  * Author: Jordan LeDoux, jordan.ledoux@gmail.com
  * Status: Draft
  * First Published at: http://wiki.php.net/rfc/stochastic_rounding_mode

===== Introduction =====
Rounding modes use some rule to determine in which direction a supplied value should be rounded. While all of the rounding modes available in PHP right now are deterministic, there are other ways that rounding can occur.

This RFC proposes adding a **stochastic rounding mode** that uses a weighted random process to determine the rounding direction.

===== Proposal =====
A **stochastic rounding mode** rounds with a probability that corresponds to the value being rounded. For instance:

<code php>
$val = round(1.8, 0 \RoundingMode::Stochastic);

echo $val; 
// 20% of the time, this will echo "1"
// 80% of the time, this will echo "2"
</code>

This mode ensures that if the same value is rounded many times, the average value of the rounded numbers will approach the original number. This is mainly used in linear algebra, particularly machine learning applications.

==== New Option For \RoundingMode Enum ====

The new rounding mode will only be available on the ''\RoundingMode'' enum.

<code php>
enum RoundingMode {
    // Existing Modes
    case HalfAwayFromZero;
    case HalfTowardsZero;
    case HalfEven;
    case HalfOdd;
    case TowardsZero;
    case AwayFromZero;
    case NegativeInfinity;
    case PositiveInfinity;
    
    // New Rounding Mode
    case Stochastic;
}
</code>

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

===== Proposed PHP Version(s) =====
Next PHP 8.x

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

==== To Existing Extensions ====
None

==== To Opcache ====
None

==== New Constants ====
Describe any new constants so they can be accurately and comprehensively explained in the PHP documentation.

===== Unaffected PHP Functionality =====
The ''Intl'' round function will be unaffected, as it does not accept the ''\RoundingMode'' enum.

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

===== Proposed Voting Choices =====
Add new stochastic rounding mode as described: yes/no. A 2/3 vote is required to pass. 

==== Vote ====
Vote will start 2024-XX-XX and will end 2024-XX-XX.

<doodle title="Add stochastic rounding mode?" auth="jordanrl" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
The patch will be completed by the RFC author after acceptance.

===== Implementation =====


===== References =====
https://nhigham.com/2020/07/07/what-is-stochastic-rounding/

===== Rejected Features =====
None