<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<html>
<style type="text/css">
  ins, ins * { text-decoration:none; font-weight:bold; background-color:#A0FFA0 }
  del, del * { text-decoration:line-through; background-color:#FFA0A0 }
  #hidedel:checked ~ * del, #hidedel:checked ~ * del * { display:none; visibility:hidden }

blockquote {
  padding: .5em;
  border: .5em;
  border-color: silver;
  border-left-style: solid;
}

blockquote.std { color: #000000; background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stdins { text-decoration: underline;
  color: #000000; background-color: #C8FFC8;
  border: 1px solid #B3EBB3; padding: 0.5em; }
blockquote.stddel { text-decoration: line-through;
  color: #000000; background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding-left: 0.5em; padding-right: 0.5em; }

p.grammarlhs { margin-bottom: 0 }
p.grammarrhs { margin-left:8em; margin-top:0; margin-bottom:0; text-indent:-4em }

div.wrapper {
    max-width: 60em;
    margin: auto;
}

a { text-decoration: none; }

a.hidden_link {
    text-decoration: none;
    color: inherit;
}

li {
    margin-top: 0.0em;
    margin-bottom: 0.0em;
}

h1 { line-height: 1; }
h2 { line-height: 1; }
h3 { line-height: 1; }
h4 { line-height: 1; }

:target { background-color: #C9FBC9; }
:target .codeblock { background-color: #C9FBC9; }
:target ul { background-color: #C9FBC9; }

.abbr_ref { float: right; }

.folded_abbr_ref { float: right; }
:target .folded_abbr_ref { display: none; }

:target .unfolded_abbr_ref { float: right; display: inherit; }
.unfolded_abbr_ref { display: none; }

.secnum { display: inline-block; min-width: 35pt; }
.annexnum { display: block; }

div.sourceLinkParent {
    float: right;
}

a.sourceLink {
    position: absolute;
    opacity: 0;
    margin-left: 10pt;
}

a.sourceLink:hover {
    opacity: 1;
}

div.marginalizedparent {
    position: relative;
    left: -5em;
}

div.footnoteNumberParent {
    position: relative;
    left: -4.7em;
}

a.marginalized {
    position: absolute;
    font-size: 75%;
    text-align: right;
    width: 5em;
}

a.enumerated_item_num {
    position: relative;
    left: -3.5em;
    display: inline-block;
    margin-right: -3em;
    text-align: right;
    width: 3em;
}

div.para { margin-bottom: 0.6em; margin-top: 0.6em; text-align: justify; }
div.section { text-align: justify; }
div.sentence { display: inline; }

span.indexparent {
    display: inline;
    position: relative;
    float: right;
    right: -1em;
}

a.index {
    position: absolute;
    display: none;
}

a.index:before { content: "Ã¢Å¸Âµ"; }
    /* this way the content is not selectable */

a.index:target {
    display: inline;
}

.indexitems {
    margin-left: 2em;
    text-indent: -2em;
}

div.itemdescr {
    margin-left: 3em;
}

.bnf {
    font-family: serif;
    margin-left: 40pt;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
}

.ncbnf {
    font-family: serif;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
    margin-left: 40pt;
}

.bnftab {
    font-family: serif;
    font-style: italic;
    margin-left: 40pt;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
}

.ncsimplebnf {
    font-family: serif;
    font-style: italic;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
    margin-left: 40pt;
}

.ncbnftab {
    font-family: serif;
    font-style: italic;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
    margin-left: 40pt;
}

.bnfkeywordtab {
    margin-top: 0.5em;
    margin-bottom: 0.5em;
    margin-left: 40pt;
}

span.textnormal {
    font-style: normal;
    font-family: serif;
    white-space: normal;
    display: inline-block;
}

span.descr { font-style: normal; font-family: serif; }
span.grammarterm { font-style: italic; }
span.term { font-style: italic; }
span.terminal { font-family: monospace; font-style: normal; }
span.nonterminal { font-style: italic; }
span.tcode { font-family: monospace; font-style: normal; }
span.textbf { font-weight: bold; }
span.textsc { font-variant: small-caps; }
a.nontermdef { font-style: italic; font-family: serif; }
span.emph { font-style: italic; }
span.techterm { font-style: italic; }
span.mathit { font-style: italic; }
span.mathsf { font-family: sans-serif; }
span.mathrm { font-family: serif; font-style: normal; }
span.textrm { font-family: serif; }
span.textsl { font-style: italic; }
span.mathtt { font-family: monospace; font-style: normal; }
span.mbox { font-family: serif; font-style: normal; }
span.ungap { display: inline-block; width: 2pt; }
span.textit { font-style: italic; }
span.texttt { font-family: monospace; }
span.tcode_in_codeblock { font-family: monospace; font-style: normal; }

span.phantom { color: white; }
span.math { }

span.mathblock {
    display: block;
    margin-left: auto;
    margin-right: auto;
    margin-top: 1.2em;
    margin-bottom: 1.2em;
    text-align: center;
}

span.mathalpha {
    font-style: italic;
}

span.synopsis {
    font-weight: bold;
    margin-top: 0.5em;
    display: block;
}

span.definition {
    font-weight: bold;
    display: block;
}

.codeblock {
    margin-left: 1.2em;
    line-height: 127%;
}

code {
    font-family: monospace;
    font-style: normal;
}

code.itemdecl {
    margin-top: 2ex;
    white-space: pre;
    display: block;
}

.comment {
    font-style: italic;
    font-family: serif;
}

span.textsuperscript {
    vertical-align: super;
    font-size: smaller;
    line-height: 0;
}

.footnotenum { vertical-align: super; font-size: smaller; line-height: 0; }

.footnote {
    font-size: small;
    margin-left: 2em;
    margin-right: 2em;
    margin-top: 0.6em;
    margin-bottom: 0.6em;
}

div.minipage {
    display: inline-block;
    margin-right: 3em;
}

div.numberedTable {
    text-align: center;
    margin: 2em;
}

div.figure {
    text-align: center;
    margin: 2em;
}

table {
    border: 1px solid black;
    border-collapse: collapse;
    margin-left: auto;
    margin-right: auto;
    margin-top: 0.8em;
    text-align: left;
    hyphens: none; /* otherwise some columns get very narrow, e.g. [tab:hash] */
}

td, th {
    padding-left: 1em;
    padding-right: 1em;
    vertical-align: top;
}

td.left {
    text-align: left;
}

td.right {
    text-align: right;
}

td.center {
    text-align: center;
}

td.justify {
    text-align: justify;
}

td.border {
    border-left: 1px solid black;
}

tr.rowsep, td.cline {
    border-top: 1px solid black;
}

tr.capsep {
    border-top: 3px solid black;
    border-top-style: double;
}

th {
    border-bottom: 1px solid black;
}

span.centry {
    font-weight: bold;
}

div.table {
    display: block;
    margin-left: auto;
    margin-right: auto;
    text-align: center;
    width: 90%;
}

span.indented {
    display: block;
    margin-left: 2em;
    margin-bottom: 1em;
    margin-top: 1em;
}
</style>

<title>P2976R0: Freestanding Library: algorithm, numeric, and random</title>
<body>
<h1>Freestanding Library: algorithm, numeric, and random</h1>
Document number: P2976R0<br/>
Date: 2023-09-17<br/>
Reply-to: Ben Craig &lt;ben dot craig at gmail dot com&gt;<br/>
Audience: Library Evolution Working Group

<h1>Changes from previous revisions</h1>
First revision!

<h1>Introduction</h1>
<p>
This proposal is part of a group of papers aimed at improving the state of freestanding.
</p><p>
At a high level, this proposal adds most of the facilities from <code>&lt;algorithm&gt;</code>, <code>&lt;numeric&gt;</code>, and <code>&lt;random&gt;</code> that don't require floating point or <code>ExecutionPolicy</code>.
</p><p>
Implementations of these often rely on facilities like <code>memcpy</code>, which is made freestanding by <a href="https://wg21.link/P2338">P2338 "Freestanding Library: Character primitives and the C library"</a>.
</p>

<h1>Motivation and Scope</h1>
<p>
On hosted implementations, the included facilities don't directly require heap allocations, don't use system calls, and don't require exceptions.
The facilities are generally useful.
This combination keeps the burden low for standard library implementations to single source these facilities as both hosted and freestanding.
</p>

<h1>Design</h1>

<h2>Parallel Algorithms</h2>
<p>
The execution policy overloads in <code>&lt;algorithm&gt;</code> and <code>&lt;numeric&gt;</code> are not required to be present in freestanding implementations.
An argument could be made to support sequential execution, but that provides very little value.
This matches precedent in <code>&lt;memory&gt;</code>, as the execution policy overloads in that header are not require to be present in freestanding implementations either.
</p><p>
The execution policy overloads are not marked as <code>// freestanding-deleted</code>.
<code>// freestanding-deleted</code> is typically useful for ensuring that overload resolution doesn't change when moving between freestanding and hosted environments.
The execution policy overloads are already constrained such that accidental selection of these overloads is highly unlikely, so an additional <code>= delete</code> would not provide much benefit.
</p>

<h2>Allocating algorithms</h2>
<p>
Some algorithms (<code>stable_sort</code>, <code>stable_partition</code>, and <code>inplace_merge</code>) attempt to allocate temporary buffers as a way to reduce the time complexity of the algorithm.
Freestanding implementations are not required to have an operational <code>::operator new</code>.  As a result, these algorithms are not required to be present in freestanding implementations.
</p><p>
In theory, we could include these algorithms with the expectation that the fall-back, worse time complexity is used instead of the complexity that we get from the temporary buffer version of the algorithm.
I did not take that approach, as I see it being a subtle performance break.
I would much rather have a loud compiler error than a subtle performance break.
</p>

<h2>Random number iostreams</h2>
<p>
This paper makes the iostreams streaming requirements optional for random number engines <a href="https://eel.is/c++draft/rand.req.eng">[rand.req.eng]</a> and random number distributions <a href="https://eel.is/c++draft/rand.req.dist">[rand.req.dist]</a> on freestanding implementations.
Freestanding doesn't require iostreams to be present, and won't require the random number iostreams operations to be present either.
Streaming these objects allows users to save and restore the state of the object in a round-trippable manner.
Common usages of the random number facilities that don't involve serialization still work without iostreams support.
</p>

<h2>Floating point randomness</h2>
<p>
In many kernel environments, loading, storing, or manipulating floating point values is not allowed in the general case.
Using floating point in these areas ends up corrupting user mode floating point state.
As a result, freestanding avoids requiring facilities that use floating point types.
</p><p>
The random number facilities in <code>&lt;random&gt;</code> are a mix of integer and floating point facilities.
All the distributions other than <code>uniform_int_distribution</code> rely on floating point math.
In addition, the <code>shuffle_order_engine</code> and its associated <code>knuth_b</code> typedef are specified and implemented in terms of floating point math.  <code>generate_canonical</code> also deals directly with floating point numbers.
</p>

<h2>OS dependent random number facilities</h2>
<p>
Implementing <code>random_device</code> in a useful way requires knowledge of the operating environment.
While a conforming implementation of <code>random_device</code> is allowed to return pseudo-random numbers, actually doing so is user hostile.
If users want <code>random_device</code> non-deterministic random numbers, and the system cannot supply them, then users would typically prefer a compiler error rather than getting incorrect, deterministic random results.
</p><p>
Due to this dependency on the operating environment, <code>random_device</code> is not required to be present in freestanding implementations.
</p><p>
<code>seed_seq</code> requires dynamic memory allocation.
Dynamic memory allocation is typically considered a facility provided by the operating environment.
As a result, <code>seed_seq</code> is not required to be present in freestanding implementations.
</p><p>
All of the standard library random engines have constructors taking a seed sequence.
Those constructors are templated on the seed sequence, and do not specifically require <code>seed_seq</code>.
</p>

<h1>Experience</h1>
<p>
These changes have been <a href="https://github.com/ben-craig/kernel_test_harness">tested</a> with the libc++ test suite in the Microsoft Windows 11 kernel with the MSVC STL.
The binaries produced were scanned for unexpected floating point usage.
Usage of exceptions, iostreams, and global <code>::operator new</code> and <code>::operator delete</code> cause linker errors on that platform.
</p><p>
The C++03 portions of the library have seen extensive field use in kernel drivers produced by NI (formerly National Instruments).
Those drivers use a modified version of STLport in kernel drivers built for Microsoft Windows, Linux, and Apple MacOS, as well as for various real time operating systems.
</p><p>
Paul Bendixen has implemented <a href="https://wg21.link/P0829">P0829</a> in a <a href="https://gitlab.com/avr-libstdcxx">libstdc++ fork</a>.  P0829 is (almost) a superset of the facilities in this paper.
</p>

<h1>Wording</h1>
This paper’s wording is based on the current working draft, [N4928], and it assumes that [P2407R5] has been applied.

<h2>Changes in <a href="https://eel.is/c++draft/freestanding.item">[freestanding.item]</a></h2>
<blockquote class="std">
<div class="para">
    <div class="marginalizedparent"><a class="marginalized">5</a></div>
    <div class="sentence">An entity, deduction guide, or <i>typedef-name</i> is a freestanding item if it is:
        <ul class="itemize">
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.1)</a></div>
                introduced by a declaration that is a freestanding item,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.2)</a></div>
                a member of a freestanding item other than a namespace<ins> where the introducing declaration is not followed by a comment that includes <i>hosted</i></ins>,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.3)</a></div>
                an enumerator of a freestanding item,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.4)</a></div>
                a deduction guide of a freestanding item,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.5)</a></div>
                an enclosing namespace of a freestanding item,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.6)</a></div>
                a friend of a freestanding item<ins> where the introducing declaration is not followed by a comment that includes <i>hosted</i></ins>,
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.7)</a></div>
                denoted by a <i>typedef-name</i> that is a freestanding item, or
            </li>
            <li><div class="marginalizedparent" style="left:-27mm"><a class="marginalized">(5.8)</a></div>
                denoted by an alias template that is a freestanding item.
            </li>
        </ul>
    </div>
</div>
</blockquote>

<h2>Changes in <a href="https://eel.is/c++draft/compliance">[compliance]</a></h2>
Drafting note: <code>&lt;algorithm&gt;</code> and <code>&lt;numeric&gt;</code> are already freestanding headers.<br/>

Add new rows to the "C++ headers for freestanding implementations" table:
<table style="border: 1px solid black">
<thead>
<tr style="border: 1px solid black">
<th colspan="2" style="text-align: center">Subclause</th><th style="text-align: center">Header(s)</th>
</tr>
</thead>
<tbody>
<tr style="border: 1px solid black">
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
</tr>
<tr style="border: 1px solid black">
<td style="padding: 0ex 1ex 0ex 1ex"><ins>?.? <a href="https://eel.is/c++draft/views.contiguous">[rand]</a></ins></td>
<td style="padding: 0ex 1ex 0ex 1ex"><ins>Random number generation</ins></td>
<td style="padding: 0ex 1ex 0ex 1ex"><ins><tt>&lt;random&gt;</tt></ins></td>
</tr>
<tr style="border: 1px solid black">
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
<td style="padding: 0ex 1ex 0ex 1ex">[&hellip;]</td>
</tr>
</tbody>
</table>

<h2>Changes in <a href="https://eel.is/c++draft/version.syn">[version.syn]</a></h2>
Instructions to the editor:<br/>
Add the following macros to <a href="https://eel.is/c++draft/version.syn">[version.syn]</a>:
<blockquote class="stdins">
<pre class='codeblock'>
#define __cpp_lib_freestanding_numeric 20XXXXL // freestanding, also in &lt;numeric&gt;
#define __cpp_lib_freestanding_random 20XXXXL // freestanding, also in &lt;random&gt;
</pre>
</blockquote>

Update the integer literal for the following macro:
<ul>
  <li><code>__cpp_lib_freestanding_algorithm</code></li>
</ul>

<h2>Changes in <a href="https://eel.is/c++draft/algorithm.syn">[algorithm.syn]</a></h2>
Instructions to the editor:<br/>
<p>
Please insert a <code><i>// mostly freestanding</i></code> comment at the beginning of the <a href="https://eel.is/c++draft/algorithm.syn">[algorithm.syn]</a> synopsis.<br/>
</p><p>
Please append a <code><i>// hosted</i></code> comment to each function template with an <code>ExecutionPolicy</code> parameter.
</p><p>
Please append a <code><i>// hosted</i></code> comment to all overloads of the following function templates:
<ul>
  <li><code>stable_sort</code></li>
  <li><code>stable_partition</code></li>
  <li><code>inplace_merge</code></li>
</ul>
</p><p>
Please <b>remove</b> the <code><i>// freestanding</i></code> comment from the following functions.
The markings are now redundant given the <code><i>// mostly freestanding</i></code> comment at the beginning of the synopsis.
<ul>
    <li><code>fill_n(OutputIterator first, Size n, const T&amp; value)</code></li>
    <li><code>swap_ranges(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2)</code></li>
</ul>
</p>

<h2>Changes in <a href="https://eel.is/c++draft/numeric.ops.overview">[numeric.ops.overview]</a></h2>
Instructions to the editor:<br/>
<p>
Please insert a <code><i>// mostly freestanding</i></code> comment at the beginning of the <a href="https://eel.is/c++draft/numeric.ops.overview">[numeric.ops.overview]</a> synopsis.<br/>
</p><p>
Please append a <code><i>// hosted</i></code> comment to each function template with an <code>ExecutionPolicy</code> parameter.
</p><p>
Please <b>remove</b> the <code><i>// freestanding</i></code> comment from the following functions.
The markings are now redundant given the <code><i>// mostly freestanding</i></code> comment at the beginning of the synopsis.
<ul>
    <li><code>add_sat</code></li>
    <li><code>sub_sat</code></li>
    <li><code>mul_sat</code></li>
    <li><code>div_sat</code></li>
    <li><code>saturate_cast</code></li>
</ul>
</p>

<h2>Changes in <a href="https://eel.is/c++draft/rand.synopsis">[rand.synopsis]</a></h2>
Instructions to the editor:<br/>
Please append a <code><i>// freestanding</i></code> comment to the following declarations:<br/>
<ul>
  <li><code>uniform_random_bit_generator </code></li>
  <li><code>minstd_rand0</code></li>
  <li><code>minstd_rand</code></li>
  <li><code>mt19937</code></li>
  <li><code>mt19937_64</code></li>
  <li><code>ranlux24_base</code></li>
  <li><code>ranlux48_base</code></li>
  <li><code>ranlux24</code></li>
  <li><code>ranlux48</code></li>
</ul>

Drafting note: The omission of <code>knuth_b</code> is intentional.<br/>

Please append a <code><i>// partially freestanding</i></code> comment to the following declarations:<br/>
<ul>
  <li><code>linear_congruential_engine</code></li>
  <li><code>mersenne_twister_engine</code></li>
  <li><code>subtract_with_carry_engine</code></li>
  <li><code>discard_block_engine</code></li>
  <li><code>independent_bits_engine</code></li>
  <li><code>uniform_int_distribution</code></li>
</ul>
Drafting note: The omission of <code>shuffle_order_engine</code> is intentional.<br/>


<h2>Changes in <a href="https://eel.is/c++draft/rand.req.eng">[rand.req.eng]</a></h2>

<blockquote class="std">
<div class="texpara"><div class="numberedTable" id="tab:rand.req.eng">Table <a href="#tab:rand.req.eng">96</a>: Random number engine requirements <a href="./tab:rand.req.eng">[tab:rand.req.eng]</a><br><table><tbody>

<tr id="tab:rand.req.eng-row-1" class="rowsep"><td class="center"><div class="texpara"><div id="tab:rand.req.eng-row-1-column-1-sentence-1" class="sentence"><b>Expression</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.eng-row-1-column-2-sentence-1" class="sentence"><b>Return type</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.eng-row-1-column-3-sentence-1" class="sentence"><b>Pre/post-condition</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.eng-row-1-column-4-sentence-1" class="sentence"><b>Complexity</b></div></div></td></tr>

<tr id="tab:rand.req.eng-row-2" class="capsep"><td class="left" style="width:22%">...</td><td class="left" style="width:22%">...</td><td class="left" style="width:30%">...</td><td class="left" style="width:15%">...</td></tr>

    <tr id="tab:rand.req.eng-row-13" class="rowsep"><td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.eng-row-13-column-1-sentence-1" class="sentence"><span class="texttt">os &lt;&lt; x</span></div></div></del></td><td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.eng-row-13-column-2-sentence-1" class="sentence">reference to the type of <span class="texttt">os</span></div></div></del></td><td class="left" style="width:30%"><del>
    
    <div class="texpara"><div id="tab:rand.req.eng-row-13-column-3-sentence-1" class="sentence">With <span class="texttt">os.</span><i>fmtflags</i> set to
    <span class="texttt">ios_base::dec|ios_base::left</span>
    and the fill character set to the space character,
    writes to <span class="texttt">os</span>
    the textual representation
    of <span class="texttt">x</span>'s current state<a class="hidden_link" href="#tab:rand.req.eng-row-13-column-3-sentence-1">.</a></div> <div id="tab:rand.req.eng-row-13-column-3-sentence-2" class="sentence">In the output,
    adjacent numbers are separated
    by one or more space characters<a class="hidden_link" href="#tab:rand.req.eng-row-13-column-3-sentence-2">.</a></div></div>
    
    <div class="texpara"><div id="tab:rand.req.eng-row-13-column-3-sentence-3" class="sentence"><i>Postconditions</i>: The <span class="texttt">os.</span><i>fmtflags</i> and fill character are unchanged<a class="hidden_link" href="#tab:rand.req.eng-row-13-column-3-sentence-3">.</a></div></div>
    
    </del></td><td class="left" style="width:15%"><del><div class="texpara"><span class="mjx-chtml"><span class="mjx-math"><span class="mjx-mrow" aria-hidden="true"><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mi"><span class="mjx-char MJXc-TeX-script-R" style="padding-top: 0.519em; padding-bottom: 0.225em; padding-right: 0.067em;">O</span></span></span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">(</span></span><span class="mjx-mtext"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.372em;">size of state</span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">)</span></span></span></span></span></div></del></td></tr>
    <tr id="tab:rand.req.eng-row-14" class="rowsep"><td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.eng-row-14-column-1-sentence-1" class="sentence"><span class="texttt">is &gt;&gt; v</span></div></div></del></td><td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.eng-row-14-column-2-sentence-1" class="sentence">reference to the type of <span class="texttt">is</span></div></div></del></td><td class="left" style="width:30%"><del><div class="texpara"><div id="tab:rand.req.eng-row-14-column-3-sentence-1" class="sentence">With <span class="texttt">is.fmtflags</span>
    set to <span class="texttt">ios_base::dec</span>,
    sets <span class="texttt">v</span>'s state
    as determined by reading its textual representation from <span class="texttt">is</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-1">.</a></div> <div id="tab:rand.req.eng-row-14-column-3-sentence-2" class="sentence">If bad input is encountered,
    ensures that <span class="texttt">v</span>'s state is unchanged by the operation
    and
    calls <span class="texttt">is.setstate(ios_base::failbit)</span>
    (which may throw <span class="texttt">ios_base::failure</span> (<a href="iostate.flags" title="31.5.4.4 Flags functions">[iostate.flags]</a>))<a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-2">.</a></div> <div id="tab:rand.req.eng-row-14-column-3-sentence-3" class="sentence">If a textual representation written via <span class="texttt">os &lt;&lt; x</span>
    was subsequently read via <span class="texttt">is &gt;&gt; v</span>,
    then <span class="texttt">x == v</span>
    provided that there have been no intervening invocations
    of <span class="texttt">x</span> or of <span class="texttt">v</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-3">.</a></div></div><div class="texpara"><div id="tab:rand.req.eng-row-14-column-3-sentence-4" class="sentence"><i>Preconditions</i>: <span class="texttt">is</span> provides a textual representation
    that was previously written
    using an output stream
    whose imbued locale
    was the same as that of <span class="texttt">is</span>,
    and whose type's template specialization arguments
    <span class="texttt">charT</span> and <span class="texttt">traits</span>
    were respectively the same as those of <span class="texttt">is</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-4">.</a></div></div><div class="texpara"><div id="tab:rand.req.eng-row-14-column-3-sentence-5" class="sentence"><i>Postconditions</i>: The <span class="texttt">is.</span><i>fmtflags</i> are unchanged<a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-5">.</a></div></div></del></td><td class="left" style="width:15%"><del><div class="texpara"><span class="mjx-chtml"><span class="mjx-math"><span class="mjx-mrow" aria-hidden="true"><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mi"><span class="mjx-char MJXc-TeX-script-R" style="padding-top: 0.519em; padding-bottom: 0.225em; padding-right: 0.067em;">O</span></span></span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">(</span></span><span class="mjx-mtext"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.372em;">size of state</span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">)</span></span></span></span></span></div></del></td></tr>

    
    </tbody></table></div></div></div>

<div class="para" id="5"><div class="marginalizedparent"><a class="marginalized" href="#5">5</a></div><div class="texpara"><div id="5.sentence-1" class="sentence">...</div></div></div>
<ins>
<div class="para" id="6"><div class="marginalizedparent"><a class="marginalized" href="#6">6</a></div><div class="texpara"><div id="6.sentence-1" class="sentence">On hosted implementations, the following expressions are well-formed and have the specified semantics.</div></div></div>

<div class="texpara"><span class="texttt">os &lt;&lt; x</span></div>

<div class="para" id="#7">
    <div class="marginalizedparent"><a class="marginalized" href="#7">7</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Result</i>: reference to the type of <span class="texttt">os</span>.</div></div></div>
</div>
<div class="para" id="#8">
    <div class="marginalizedparent"><a class="marginalized" href="#8">8</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Effects</i>: <div id="tab:rand.req.eng-row-13-column-3-sentence-1" class="sentence">With <span class="texttt">os.</span><i>fmtflags</i> set to
    <span class="texttt">ios_base::dec|ios_base::left</span>
    and the fill character set to the space character,
    writes to <span class="texttt">os</span>
    the textual representation
    of <span class="texttt">x</span>'s current state<a class="hidden_link" href="#tab:rand.req.eng-row-13-column-3-sentence-1">.</a></div> <div id="tab:rand.req.eng-row-13-column-3-sentence-2" class="sentence">In the output,
    adjacent numbers are separated
    by one or more space characters<a class="hidden_link" href="#tab:rand.req.eng-row-13-column-3-sentence-2">.</a></div>
    </div></div></div>
</div>
<div class="para" id="#9">
    <div class="marginalizedparent"><a class="marginalized" href="#9">9</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Postconditions</i>: The <span class="texttt">os.</span><i>fmtflags</i> and fill character are unchanged.</div></div></div>
</div>
<div class="para" id="#10">
    <div class="marginalizedparent"><a class="marginalized" href="#10">10</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Complexity</i>: <span class="mjx-chtml"><span class="mjx-math"><span class="mjx-mrow" aria-hidden="true"><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mi"><span class="mjx-char MJXc-TeX-script-R" style="padding-top: 0.519em; padding-bottom: 0.225em; padding-right: 0.067em;">O</span></span></span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">(</span></span><span class="mjx-mtext"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.372em;">size of state</span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">)</span></span></span></span></span>
    
    
    </div></div></div>
</div>


<div class="texpara"><span class="texttt">is &gt;&gt; v</span></div>

<div class="para" id="#11">
    <div class="marginalizedparent"><a class="marginalized" href="#11">11</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Result</i>: reference to the type of <span class="texttt">is</span>.</div></div></div>
</div>
<div class="para" id="#12">
    <div class="marginalizedparent"><a class="marginalized" href="#12">12</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Effects</i>: 
    <div id="tab:rand.req.eng-row-14-column-3-sentence-1" class="sentence">With <span class="texttt">is.<i>fmtflags</i></span>
    set to <span class="texttt">ios_base::dec</span>,
    sets <span class="texttt">v</span>'s state
    as determined by reading its textual representation from <span class="texttt">is</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-1">.</a></div> <div id="tab:rand.req.eng-row-14-column-3-sentence-2" class="sentence">If bad input is encountered,
    ensures that <span class="texttt">v</span>'s state is unchanged by the operation
    and
    calls <span class="texttt">is.setstate(ios_base::failbit)</span>
    (which may throw <span class="texttt">ios_base::failure</span> (<a href="iostate.flags" title="31.5.4.4 Flags functions">[iostate.flags]</a>))<a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-2">.</a></div> <div id="tab:rand.req.eng-row-14-column-3-sentence-3" class="sentence">If a textual representation written via <span class="texttt">os &lt;&lt; x</span>
    was subsequently read via <span class="texttt">is &gt;&gt; v</span>,
    then <span class="texttt">x == v</span>
    provided that there have been no intervening invocations
    of <span class="texttt">x</span> or of <span class="texttt">v</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-3">.</a></div>
    </div></div></div>
</div>
<div class="para" id="#13">
    <div class="marginalizedparent"><a class="marginalized" href="#13">13</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Preconditions</i>: 
    <span class="texttt">is</span> provides a textual representation
    that was previously written using an output stream whose imbued locale
    was the same as that of <span class="texttt">is</span>, and whose type's template specialization arguments
    <span class="texttt">charT</span> and <span class="texttt">traits</span>
    were respectively the same as those of <span class="texttt">is</span><a class="hidden_link" href="#tab:rand.req.eng-row-14-column-3-sentence-4">.</a>
    </div></div></div>
</div>
<div class="para" id="#14">
    <div class="marginalizedparent"><a class="marginalized" href="#14">14</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Postconditions</i>: The <span class="texttt">is.<i>fmtflags</i></span> are unchanged.</div></div></div>
</div>
<div class="para" id="#15">
    <div class="marginalizedparent"><a class="marginalized" href="#15">15</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Complexity</i>: <span class="mjx-chtml"><span class="mjx-math"><span class="mjx-mrow" aria-hidden="true"><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mi"><span class="mjx-char MJXc-TeX-script-R" style="padding-top: 0.519em; padding-bottom: 0.225em; padding-right: 0.067em;">O</span></span></span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">(</span></span><span class="mjx-mtext"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.372em;">size of state</span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">)</span></span></span></span></span>
    
    
    </div></div></div>
</div>
</ins>
</blockquote>
    
<h2>Changes in <a href="https://eel.is/c++draft/rand.req.dist">[rand.req.dist]</a></h2>
    


<blockquote class="std">
<div class="texpara"><div class="numberedTable" id="tab:rand.req.dist">Table <a href="#tab:rand.req.dist">97</a>: Random number distribution requirements <a href="./tab:rand.req.dist">[tab:rand.req.dist]</a><br><table><tbody><tr id="tab:rand.req.dist-row-1" class="rowsep"><td class="center"><div class="texpara"><div id="tab:rand.req.dist-row-1-column-1-sentence-1" class="sentence"><b>Expression</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.dist-row-1-column-2-sentence-1" class="sentence"><b>Return type</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.dist-row-1-column-3-sentence-1" class="sentence"><b>Pre/post-condition</b></div></div></td><td class="center"><div class="texpara"><div id="tab:rand.req.dist-row-1-column-4-sentence-1" class="sentence"><b>Complexity</b></div></div></td></tr>

<tr id="tab:rand.req.dist-row-2" class="capsep"><td class="left" style="width:22%">...</td><td class="left" style="width:22%">...</td><td class="left" style="width:30%">...</td><td class="left" style="width:15%">...</td></tr>

<tr id="tab:rand.req.dist-row-15" class="rowsep">
    <td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.dist-row-15-column-1-sentence-1" class="sentence"><span class="texttt">os <span class="anglebracket">&lt;</span><span class="anglebracket">&lt;</span> x</span></div></div></del></td>
    <td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.dist-row-15-column-2-sentence-1" class="sentence">reference to the type of <span class="texttt">os</span></div></div></del></td>
    <td class="left" style="width:30%"><del><div class="texpara"><div id="tab:rand.req.dist-row-15-column-3-sentence-1" class="sentence">Writes to <span class="texttt">os</span> a textual representation
    for the parameters and the additional internal data of <span class="texttt">x</span><a class="hidden_link" href="#tab:rand.req.dist-row-15-column-3-sentence-1">.</a></div></div><div class="texpara"><div id="tab:rand.req.dist-row-15-column-3-sentence-2" class="sentence"><i>Postconditions</i>: The <span class="texttt">os.</span><i>fmtflags</i> and fill character are unchanged<a class="hidden_link" href="#tab:rand.req.dist-row-15-column-3-sentence-2">.</a></div></div></del></td>
    <td class="empty left" style="width:15%"></td>
</tr>

<tr id="tab:rand.req.dist-row-16" class="rowsep">
    <td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.dist-row-16-column-1-sentence-1" class="sentence"><span class="texttt">is <span class="anglebracket">&gt;</span><span class="anglebracket">&gt;</span> d</span></div></div></del></td>
    <td class="left" style="width:22%"><del><div class="texpara"><div id="tab:rand.req.dist-row-16-column-2-sentence-1" class="sentence">reference to the type of <span class="texttt">is</span></div></div></del></td>
    <td class="left" style="width:30%"><del><div class="texpara"><div id="tab:rand.req.dist-row-16-column-3-sentence-1" class="sentence">Restores from <span class="texttt">is</span>
    the parameters and additional internal data of the lvalue <span class="texttt">d</span><a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-1">.</a></div> <div id="tab:rand.req.dist-row-16-column-3-sentence-2" class="sentence">If bad input is encountered,
    ensures that <span class="texttt">d</span> is unchanged by the operation
    and
    calls <span class="texttt">is.setstate(ios_base::failbit)</span>
    (which may throw <span class="texttt">ios_base::failure</span> (<a href="iostate.flags" title="31.5.4.4 Flags functions">[iostate.flags]</a>))<a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-2">.</a></div></div><div class="texpara"><div id="tab:rand.req.dist-row-16-column-3-sentence-3" class="sentence"><i>Preconditions</i>: <span class="texttt">is</span> provides a textual representation
    that was previously written
    using an <span class="texttt">os</span> whose imbued locale
    and whose type's template specialization arguments
    <span class="texttt">charT</span> and <span class="texttt">traits</span>
    were the same as those of <span class="texttt">is</span><a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-3">.</a></div></div><div class="texpara"><div id="tab:rand.req.dist-row-16-column-3-sentence-4" class="sentence"><i>Postconditions</i>: The <span class="texttt">is.</span><i>fmtflags</i> are unchanged<a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-4">.</a></div></div></del></td>
    <td class="empty left" style="width:15%"></td>
</tr></tbody></table></div></div>
...

<ins>
<div class="para" id="11"><div class="marginalizedparent"><a class="marginalized" href="#11">11</a></div><div class="texpara"><div id="6.sentence-1" class="sentence">On hosted implementations, the following expressions are well-formed and have the specified semantics.</div></div></div>

<div class="texpara"><span class="texttt">os &lt;&lt; x</span></div>

<div class="para" id="#12">
    <div class="marginalizedparent"><a class="marginalized" href="#12">12</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Result</i>: reference to the type of <span class="texttt">os</span>.</div></div></div>
</div>
<div class="para" id="#13">
    <div class="marginalizedparent"><a class="marginalized" href="#13">13</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Effects</i>: <div id="tab:rand.req.dist-row-15-column-3-sentence-1" class="sentence">Writes to <span class="texttt">os</span> a textual representation
    for the parameters and the additional internal data of <span class="texttt">x</span>.</div>
    </div></div></div>
</div>
<div class="para" id="#14">
    <div class="marginalizedparent"><a class="marginalized" href="#14">14</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Postconditions</i>: The <span class="texttt">os.</span><i>fmtflags</i> and fill character are unchanged.</div></div></div>
</div>

<div class="texpara"><span class="texttt">is &gt;&gt; d</span></div>

<div class="para" id="#15">
    <div class="marginalizedparent"><a class="marginalized" href="#15">15</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Result</i>: reference to the type of <span class="texttt">is</span>.</div></div></div>
</div>
<div class="para" id="#16">
    <div class="marginalizedparent"><a class="marginalized" href="#16">16</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Effects</i>: 
    <div id="tab:rand.req.dist-row-16-column-3-sentence-1" class="sentence">Restores from <span class="texttt">is</span>
    the parameters and additional internal data of the lvalue <span class="texttt">d</span><a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-1">.</a></div> <div id="tab:rand.req.dist-row-16-column-3-sentence-2" class="sentence">If bad input is encountered,
    ensures that <span class="texttt">d</span> is unchanged by the operation
    and
    calls <span class="texttt">is.setstate(ios_base::failbit)</span>
    (which may throw <span class="texttt">ios_base::failure</span> (<a href="iostate.flags" title="31.5.4.4 Flags functions">[iostate.flags]</a>))<a class="hidden_link" href="#tab:rand.req.dist-row-16-column-3-sentence-2">.</a></div>
    </div></div></div>
</div>
<div class="para" id="#17">
    <div class="marginalizedparent"><a class="marginalized" href="#17">17</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Preconditions</i>: 
    <span class="texttt">is</span> provides a textual representation
    that was previously written
    using an <span class="texttt">os</span> whose imbued locale
    and whose type's template specialization arguments
    <span class="texttt">charT</span> and <span class="texttt">traits</span>
    were the same as those of <span class="texttt">is</span>.
    </div></div></div>
</div>
<div class="para" id="#18">
    <div class="marginalizedparent"><a class="marginalized" href="#18">18</a></div>
    <div class="itemdescr"><div class="texpara"><div class="sentence">
    <i>Postconditions</i>: The <span class="texttt">is.<i>fmtflags</i></span> are unchanged.</div></div></div>
</div>
</ins>

</blockquote>

<h2>Changes in <a href="https://eel.is/c++draft/rand.eng.lcong">[rand.eng.lcong]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>linear_congruential_engine</code> synopsis.<br/>

<h2>Changes in <a href="https://eel.is/c++draft/rand.eng.mers">[rand.eng.mers]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>mersenne_twister_engine</code> synopsis.<br/>

<h2>Changes in <a href="https://eel.is/c++draft/rand.eng.sub">[rand.eng.sub]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>subtract_with_carry_engine</code> synopsis.<br/>

<h2>Changes in <a href="https://eel.is/c++draft/rand.adapt.disc">[rand.adapt.disc]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>discard_block_engine</code> synopsis.<br/>

<h2>Changes in <a href="https://eel.is/c++draft/rand.adapt.ibits">[rand.adapt.ibits]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>independent_bits_engine</code> synopsis.<br/>

<h2>Changes in <a href="https://eel.is/c++draft/rand.dist.uni.int">[rand.dist.uni.int]</a></h2>
Instructions to the editor:<br/>
Please append a <i>// hosted</i> comment to each <code>operator&lt;&lt;</code> and <code>operator&gt;&gt;</code> overload in the <code>uniform_int_distribution</code> synopsis.<br/>

</body>
</html>
