<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
<html xml:lang='en' xmlns:svg='http://www.w3.org/2000/svg' xmlns='http://www.w3.org/1999/xhtml'>
<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>std::rand replacement</title></head>
<body><!-- maruku -o randint.html randint.md --><style type='text/css'>
pre code { display: block; margin-left: 2em; }
div { display: block; margin-left: 2em; }
ins { text-decoration: none; font-weight: bold; background-color: #A0FFA0 }
del { text-decoration: line-through; background-color: #FFA0A0 }
</style><table><tbody>
<tr><th>Doc. no.:</th>	<td>N3796</td></tr>
<tr><th>Date:</th>	<td>2013-10-02</td></tr>
<tr><th>Project:</th>	<td>Programming Language C++, Library Evolution Working Group</td></tr>
<tr><th>Reply-to:</th>	<td>Zhihao Yuan &lt;zy at miator dot net&gt;</td></tr>
</tbody></table>
<h1 id='stdrand_replacement'>std::rand replacement</h1>

<h2 id='motivation'>Motivation</h2>

<p>We want to deprecate <code>std::rand</code> friends, while &#8220;deprecation without a replacement&#8221; is a valid concern. This paper</p>

<ol>
<li>
<p>Propose replacement to the <code>std::rand</code> friends. As a global uniform random number generator, <code>std::rand</code> is considered both handy and useful.</p>
</li>

<li>
<p>Expose the most widely-used combos from C++11 <code>&lt;random&gt;</code> without pushing the users to learn the whole design of <code>&lt;random&gt;</code>. Smoothing the learning curve can usually optimize the acceptance.</p>
</li>
</ol>

<h2 id='design_decisions'>Design Decisions</h2>

<p><code>std::rand</code> is a single interface, and its &#8220;replacement&#8221; should be able to be used as a single interface as well. In addition, I expect the interface to correctly expose the functionalities of <code>&lt;random&gt;</code> and lead to more robust and secure programs. The proposed replacement is</p>

<ul>
<li>
<p>Distribution based. RNG must be used with a distribution; <code>std::rand</code> is just a wrong design.</p>
</li>

<li>
<p>Randomly seeded before being used. Improper seeding results in vulnerability, like <code>rand(time(0))</code>.</p>
</li>

<li>
<p>Thread-safe. Minimal interface should minimize astonishment.</p>
</li>

<li>
<p>Templated. No type promotion; inputs and result have the same types.</p>
</li>
</ul>

<p>Seeding a pseudo random number generator with a determined value will result in a determined random number sequence (repeatability), which is useful for debugging. However, a global seeding utility is incompatible with the proposed minimal interface, and causes numerous confusions in a multi-thread environment. Instead, an implementation may want to allow user to deploy a determined seed for debugging purpose.</p>

<p>Different from the initial draft of this paper, only the utility using <code>uniform_int_distribution</code> is proposed; the one using <code>uniform_real_distribution</code> is dropped. This is because the former forms a &#8220;selection&#8221; model, which covers the major use cases, while the later is merely a simulation of data input.</p>

<h2 id='example'>Example</h2>

<pre><code>std::randint(0, 6);  // randomly seeded</code></pre>

<h2 id='wording'>Wording</h2>

<p>Change 26.5.2 rand.synopsis:</p>

<pre><code>namespace std {</code></pre>

<blockquote>
<p>&#8230;</p>
</blockquote>

<pre><code> // 26.5.7.2, function template generate_canonical
 template&lt;class RealType, size_t bits, class URNG&gt;
 RealType generate_canonical(URNG&amp; g);</code></pre>
<div><ins>
<tt>// 26.5.7.3, function template randint</tt><br />
<tt>template&lt;class IntType&gt;</tt><br />
<tt>&nbsp;&nbsp;IntType randint(IntType a, IntType b);</tt><br />
</ins></div>
<pre><code> // 26.5.8.2.1, class template uniform_int_distribution
 template&lt;class IntType = int&gt;
 class uniform_int_distribution;</code></pre>

<blockquote>
<p>&#8230;</p>
</blockquote>

<pre><code>} // namespace std</code></pre>

<p>New section 26.5.7.3 rand.util.randint:</p>

<blockquote>
<h4 id='26573_function_template_'>26.5.7.3 function template <code>randint</code></h4>
</blockquote>

<blockquote>
<p>All functions instantiated from the template described in this section 26.5.7.3 share the same <code>default_random_engine</code> for a given execution of a thread; the random engine is non-deterministically seeded during the initialization. Such a random engine shall be maintained separately for each thread. <em>[Note: The call expressions from different threads shall not be able to observe the same pseudo random number sequence in a deterministic way. &#8211;end note]</em></p>
</blockquote>

<pre><code>template&lt;class IntType&gt;
  IntType randint(IntType a, IntType b);</code></pre>

<blockquote>
<p><em>Requires:</em> <code>a</code> <em>&#8804;</em> <code>b</code></p>

<p><em>Effects:</em> Produce a random integer <em>i</em>, <em>a &#8804; i &#8804; b</em>, from a <code>uniform_int_distribution&lt;IntType&gt;</code> (26.5.8.2.1).</p>

<p><em>Returns:</em> <em>i</em>.</p>
</blockquote>

<h2 id='sample_implementation'>Sample Implementation</h2>

<p>A sample implementation is available at <a href='https://github.com/lichray/randint'>https://github.com/lichray/randint</a> &#8230;You really need this?</p>

<h2 id='bikeshed'>Bikeshed</h2>

<p>First of all, overloading <code>std::rand</code> is not an option. User may regard <code>std::rand()</code> as a &#8220;safe&#8221; variant to the new interface.</p>

<p>Collected so far:</p>

<ul>
<li><code>randint</code>, from Python<code>[2]</code></li>

<li><code>random_int</code>, by STL</li>

<li><code>pick_int</code>, by me, inspired by WEB<code>[1]</code></li>

<li><code>randi</code>, by Howard</li>
</ul>

<h2 id='acknowledgments'>Acknowledgments</h2>

<p>Hans Boehm, who emphasized the importance of an enforced per-thread random engine more than once.</p>

<p>Stephan T. Lavavej, who carefully reviewed this paper and provided many corrections.</p>

<p>Walter E. Brown, who drafted the paper<code>[1]</code> which contains basically the same thought.</p>

<p>And many others who joined the <code>std::rand</code> related discussions on <em>c++std-lib</em> and <em>c++std-lib-ext</em> mailing lists.</p>

<h2 id='references'>References</h2>

<p><code>[1]</code> Brown, Walter E. N3742 <em>Three <code>&lt;random&gt;</code>-related Proposals, v2</em>. <a href='http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3742.pdf'>http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3742.pdf</a></p>

<p><code>[2]</code> <em><code>random</code> &#8211; Generate pseudo-random numbers</em>. &#8220;The Python Standard Library&#8221;. <a href='http://docs.python.org/2/library/random.html'>http://docs.python.org/2/library/random.html</a></p>
</body></html>
