<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Issue 3168: Expects: element should be specified in one place</title>
<meta property="og:title" content="Issue 3168: Expects: element should be specified in one place">
<meta property="og:description" content="C++ library issue. Status: Resolved">
<meta property="og:url" content="https://cplusplus.github.io/LWG/issue3168.html">
<meta property="og:type" content="website">
<meta property="og:image" content="http://cplusplus.github.io/LWG/images/cpp_logo.png">
<meta property="og:image:alt" content="C++ logo">
<style>
  p {text-align:justify}
  li {text-align:justify}
  pre code.backtick::before { content: "`" }
  pre code.backtick::after { content: "`" }
  blockquote.note
  {
    background-color:#E0E0E0;
    padding-left: 15px;
    padding-right: 15px;
    padding-top: 1px;
    padding-bottom: 1px;
  }
  ins {background-color:#A0FFA0}
  del {background-color:#FFA0A0}
  table.issues-index { border: 1px solid; border-collapse: collapse; }
  table.issues-index th { text-align: center; padding: 4px; border: 1px solid; }
  table.issues-index td { padding: 4px; border: 1px solid; }
  table.issues-index td:nth-child(1) { text-align: right; }
  table.issues-index td:nth-child(2) { text-align: left; }
  table.issues-index td:nth-child(3) { text-align: left; }
  table.issues-index td:nth-child(4) { text-align: left; }
  table.issues-index td:nth-child(5) { text-align: center; }
  table.issues-index td:nth-child(6) { text-align: center; }
  table.issues-index td:nth-child(7) { text-align: left; }
  table.issues-index td:nth-child(5) span.no-pr { color: red; }
  @media (prefers-color-scheme: dark) {
     html {
        color: #ddd;
        background-color: black;
     }
     ins {
        background-color: #225522
     }
     del {
        background-color: #662222
     }
     a {
        color: #6af
     }
     a:visited {
        color: #6af
     }
     blockquote.note
     {
        background-color: rgba(255, 255, 255, .10)
     }
  }
</style>
</head>
<body>
<hr>
<p><em>This page is a snapshot from the LWG issues list, see the <a href="lwg-active.html">Library Active Issues List</a> for more information and the meaning of <a href="lwg-active.html#Resolved">Resolved</a> status.</em></p>
<h3 id="3168"><a href="lwg-defects.html#3168">3168</a>. <i>Expects:</i> element should be specified in one place</h3>
<p><b>Section:</b> 16.3.2.4 <a href="https://wg21.link/structure.specifications">[structure.specifications]</a>, 99 [res.on.required] <b>Status:</b> <a href="lwg-active.html#Resolved">Resolved</a>
 <b>Submitter:</b> Geoffrey Romer <b>Opened:</b> 2018-11-21 <b>Last modified:</b> 2020-07-17</p>
<p><b>Priority: </b>2
</p>
<p><b>View other</b> <a href="lwg-index-open.html#structure.specifications">active issues</a> in [structure.specifications].</p>
<p><b>View all other</b> <a href="lwg-index.html#structure.specifications">issues</a> in [structure.specifications].</p>
<p><b>View all issues with</b> <a href="lwg-status.html#Resolved">Resolved</a> status.</p>
<p><b>Discussion:</b></p>
<p>
16.3.2.4 <a href="https://wg21.link/structure.specifications">[structure.specifications]</a>/p3.4 specifies the <i>Expects:</i> element as "the conditions (sometimes termed preconditions) 
that the function assumes to hold whenever it is called". This is nonsensical (functions can't "assume" things because 
they're not sentient), and more to the point it says nothing about what happens if those conditions don't hold. This is 
a serious problem because the whole point of introducing <i>Expects:</i> was to correct the vagueness of <i>Requires:</i> on 
exactly that point.
<p/>
99 [res.on.required]/p2 is more explicit: "Violation of any preconditions specified in a function's <i>Expects:</i> 
element results in undefined behavior." However, I think putting the actual meaning of the <i>Expects:</i> element in a subclause 
called "Requires paragraph", 21 pages away from where <i>Expects:</i> is nominally specified, is asking too much of the reader. 
Splitting the specification of <i>Requires:</i> into two places 21 pages apart also seems needlessly obtuse, but that's less pressing 
since <i>Requires:</i> should be going away soon.
</p>

<p><i>[2018-11 Reflector prioritization]</i></p>

<p>Set Priority to 2</p>
<p><i>[2019-02; Kona Wednesday night issue processing]</i></p>

<p>Alternate wording discussed; Marshall to check with Geoffrey and vote on reflector.</p>

<p><i>[2019 Cologne Wednesday night]</i></p>

<p>Revisit once the appropriate "Mandating" paper has landed</p>

<p><i>[2020-06; telecon and reflector discussion]</i></p>

Changing <i>Expects:</i> to <i>Preconditions:</i> doesn't change the fact that
the specification is split across two subclauses.
Resolved editorially by integrating [res.on.expects] into [structure.specifications].


<p id="res-3168"><b>Proposed resolution:</b></p>
<p>This wording is relative to <a href="https://wg21.link/n4778">N4778</a>.</p>

<blockquote class="note">
[<i>Drafting Note:</i> I have prepared two mutually exclusive options, depicted below by <b>Option A</b> and <b>Option B</b>, 
respectively. In case the committee would prefer to leave "Requires" alone, <b>Option B</b> describes just the "Expects" 
edits, as an alternate P/R]
</blockquote>

<p><b>Option A</b></p>

<ol>
<li><p>Change 16.3.2.4 <a href="https://wg21.link/structure.specifications">[structure.specifications]</a> as indicated:</p>
<blockquote>
<p>
-3- Descriptions of function semantics contain the following elements (as appropriate):(footnote)
</p>
<ol style="list-style-type: none">
<li><p>(3.1) &mdash; <i>Requires:</i> <del>the preconditions for calling the function.</del><ins>the conditions that are required to hold 
when the function is called in order for the call to successfully complete. [<i>Note:</i> When these conditions are violated, 
the function's <i>Throws:</i> element may specify throwing an exception. Otherwise, the behavior is undefined. &mdash; 
<i>end note</i>]</ins></p></li>
<li><p>(3.2) &mdash; <i>Constraints:</i> [&hellip;]</p></li>
<li><p>(3.3) &mdash; <i>Mandates:</i> [&hellip;]</p></li>
<li><p>(3.4) &mdash; <i>Expects:</i> the conditions (sometimes termed preconditions) that <del>the function assumes to hold whenever
it is called</del><ins>are required to hold when the function is called in order for the call to have well-defined behavior</ins>. 
[<i>Example:</i> An implementation might express such conditions via an attribute such as <code>[[expects]]</code> 
( [dcl.attr.contract]). However, some such conditions might not lend themselves to expression via code. &mdash; 
<i>end example</i>]</p></li>
</ol>
</blockquote>
</li>

<li><p>Delete 99 [res.on.required] in it's entirety as indicated:</p>
<blockquote>
<p>
<del><b>15.5.4.11 Requires paragraph [res.on.required]</b></del>
<p/>
<del>-1- Violation of any preconditions specified in a function's <i>Requires:</i> element results in undefined behavior unless
the function's <i>Throws:</i> element specifies throwing an exception when the precondition is violated.</del>
<p/>
<del>-2- Violation of any preconditions specified in a function's <i>Expects:</i> element results in undefined behavior.</del>
</p>
</blockquote>
</li>
</ol>

<p><b>Option B</b></p>

<ol>
<li><p>Change 16.3.2.4 <a href="https://wg21.link/structure.specifications">[structure.specifications]</a> as indicated:</p>
<blockquote>
<p>
-3- Descriptions of function semantics contain the following elements (as appropriate):(footnote)
</p>
<ol style="list-style-type: none">
<li><p>(3.1) &mdash; <i>Requires:</i> the preconditions for calling the function.</p></li>
<li><p>(3.2) &mdash; <i>Constraints:</i> [&hellip;]</p></li>
<li><p>(3.3) &mdash; <i>Mandates:</i> [&hellip;]</p></li>
<li><p>(3.4) &mdash; <i>Expects:</i> the conditions (sometimes termed preconditions) that <del>the function assumes to hold whenever
it is called</del><ins>are required to hold when the function is called in order for the call to have well-defined behavior</ins>. 
[<i>Example:</i> An implementation might express such conditions via an attribute such as <code>[[expects]]</code> 
( [dcl.attr.contract]). However, some such conditions might not lend themselves to expression via code. &mdash; 
<i>end example</i>]</p></li>
</ol>
</blockquote>
</li>

<li><p>Change 99 [res.on.required] as indicated:</p>
<blockquote>
<p>
-1- Violation of any preconditions specified in a function's <i>Requires:</i> element results in undefined behavior unless
the function's <i>Throws:</i> element specifies throwing an exception when the precondition is violated.
<p/>
<del>-2- Violation of any preconditions specified in a function's <i>Expects:</i> element results in undefined behavior.</del>
</p>
</blockquote>
</li>
</ol>





</body>
</html>
