<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Issue 3668: [recursive_]directory_iterator constructors refer to undefined options</title>
<meta property="og:title" content="Issue 3668: [recursive_]directory_iterator constructors refer to undefined options">
<meta property="og:description" content="C++ library issue. Status: New">
<meta property="og:url" content="https://cplusplus.github.io/LWG/issue3668.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#New">New</a> status.</em></p>
<h3 id="3668"><a href="lwg-active.html#3668">3668</a>. <code>[recursive_]directory_iterator</code> constructors refer to undefined <code>options</code></h3>
<p><b>Section:</b> 31.12.11.2 <a href="https://wg21.link/fs.dir.itr.members">[fs.dir.itr.members]</a>, 31.12.12.2 <a href="https://wg21.link/fs.rec.dir.itr.members">[fs.rec.dir.itr.members]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a>
 <b>Submitter:</b> Jonathan Wakely <b>Opened:</b> 2022-01-31 <b>Last modified:</b> 2024-01-29</p>
<p><b>Priority: </b>3
</p>
<p><b>View all other</b> <a href="lwg-index.html#fs.dir.itr.members">issues</a> in [fs.dir.itr.members].</p>
<p><b>View all issues with</b> <a href="lwg-status.html#New">New</a> status.</p>
<p><b>Discussion:</b></p>
<p>
31.12.11.2 <a href="https://wg21.link/fs.dir.itr.members">[fs.dir.itr.members]</a> p2 and 31.12.12.2 <a href="https://wg21.link/fs.rec.dir.itr.members">[fs.rec.dir.itr.members]</a> p3 refer to the <code>options</code> 
parameter, but not all overloads have a parameter of that name.
<p/>
We need some "for the overloads with &hellip;" wording.
</p>

<p><i>[2022-03-04; Reflector poll]</i></p>

<p>
Set priority to 3 after reflector poll.
</p>

<p><i>[2022-12-18; Daniel comments and provides wording]</i></p>

<p>
It seems to me that we should differentiate the problems of <code>directory_iterator</code> and 
<code>recursive_directory_iterator</code> regarding the constructors that don't provide any <code>options</code> arguments
at least from a logical point of view:
<p/>
From the existing <i>Postconditions:</i> element of <code>recursive_directory_iterator</code> we can at least
guess that the intention of the existing wording is that these suppose to reflect that the effective options within 
the <i>Effects:</i> element are also equal to <code>directory_options::none</code>. 
But for <code>directory_iterator</code> we don't have any options "getter" nor <i>Postconditions</i> from deducing 
the intent. 
<p/>
Fortunately, existing implementations (I looked at the current V2 2022 library and libstdc++ implementation) 
seem to behave already as if <code>directory_options::none</code> is set for the affected constructors for both 
iterator types.
<p/>
Note that this issue here has some wording overlap with the the proposed wording of LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup>,
I'm therefore using the exact wording form currently suggested there. If LWG would like to change this form (e.g.
by using the word "overload" instead of "signature") this should also be done in that other issue to reduce possible
merge conflicts. Note that the here suggested form using "signature" <em>has</em> existing practice in other places
of Clause 31.12 <a href="https://wg21.link/filesystems">[filesystems]</a>, so I recommend keeping that form.
</p>


<p id="res-3668"><b>Proposed resolution:</b></p>
<p>
This wording is relative to <a href="https://wg21.link/N4917" title=" Working Draft, Standard for Programming Language C++">N4917</a>.
</p>

<ol>
<li><p>Modify 31.12.11.2 <a href="https://wg21.link/fs.dir.itr.members">[fs.dir.itr.members]</a> as indicated:</p>

<blockquote class="note">
<p>
[<i>Drafting note:</i><br/>
(1) The proposed wording form takes care to use the same wording form used in LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup> 
for <code>recursive_directory_iterator</code> at the time of writing.<br/>
(2) We don't need similar wording for the default constructor because this creates
an end iterator and there exist no way for the user to observe the effects of
<code>directory_options</code> for such an iterator value.
]
</p>
</blockquote>

<blockquote>
<pre>
directory_iterator() noexcept;
</pre>
<blockquote>
<p>
-1- <i>Effects</i>: Constructs the end iterator.
</p>
</blockquote>
<pre>
explicit directory_iterator(const path&amp; p);
directory_iterator(const path&amp; p, directory_options options);
directory_iterator(const path&amp; p, error_code&amp; ec);
directory_iterator(const path&amp; p, directory_options options, error_code&amp; ec);
</pre>
<blockquote>
<p>
<ins>-?- For the signatures with no parameter <code>options</code>, let <code>options</code> be
<code>directory_options::none</code>.</ins>
<p/>
-2- <i>Effects</i>: For the directory that <code>p</code> resolves to, constructs an iterator for the first element in a sequence of
<code>directory_entry</code> elements representing the files in the directory, if any; otherwise the end iterator.
However, if
</p>
<blockquote><pre>
(options &amp; directory_options::skip_permission_denied) != directory_options::none
</pre></blockquote>
<p>
and construction encounters an error indicating that permission to access <code>p</code> is denied, constructs the
end iterator and does not report an error.
<p/>
[&hellip;]
</p>
</blockquote>
</blockquote>
</li>

<li><p>Modify 31.12.12.2 <a href="https://wg21.link/fs.rec.dir.itr.members">[fs.rec.dir.itr.members]</a> as indicated:</p>

<blockquote class="note">
<p>
[<i>Drafting note:</i><br/>
(1) The proposed wording form takes care to be in sync with the wording form
used in LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup> at the time of writing. This issue here doesn't
touch the wording for the <code>options</code> function though, and leaves any changes 
to LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup>, because these changes don't seem essential to solve
the issue here.<br/>
(2) We don't need similar wording for the default constructor because this creates
an end iterator and from 31.12.12.1 <a href="https://wg21.link/fs.class.rec.dir.itr.general">[fs.class.rec.dir.itr.general]</a> p2 we can
conclude that user code has no way to determine the effective <code>directory_options</code> value
of this iterator value (interestingly p15 quoted below can be read to apply here as well,
but 31.12.12.1 <a href="https://wg21.link/fs.class.rec.dir.itr.general">[fs.class.rec.dir.itr.general]</a> p2 seems to be very prohibitive and
LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup> is going to solve this special case as well).<br/>
(3) We easily simplify the wording of p3 as shown below, because the "scope" of the
introductory new paragraph includes the <i>Postconditions:</i> element. But similar to
the arguments provided in (1) we don't wish to introduce merge conflicts with the 
LWG <a href="lwg-active.html#2708" title="recursive_directory_iterator::recursion_pending() is incorrectly specified (Status: Open)">2708</a><sup><a href="https://cplusplus.github.io/LWG/issue2708" title="Latest snapshot">(i)</a></sup> wording and therefore intentionally leave any changes of p3 to
that issue.
]
</p>
</blockquote>

<blockquote>
<pre>
recursive_directory_iterator() noexcept;
</pre>
<blockquote>
<p>
-1- <i>Effects</i>: Constructs the end iterator.
</p>
</blockquote>
<pre>
explicit recursive_directory_iterator(const path&amp; p);
recursive_directory_iterator(const path&amp; p, directory_options options);
recursive_directory_iterator(const path&amp; p, directory_options options, error_code&amp; ec);
recursive_directory_iterator(const path&amp; p, error_code&amp; ec);
</pre>
<blockquote>
<p>
<ins>-?- For the signatures with no parameter <code>options</code>, let <code>options</code> be
<code>directory_options::none</code>.</ins>
<p/>
-2- <i>Effects</i>: Constructs an iterator representing the first entry in the directory to which 
<code>p</code> resolves, if any; otherwise, the end iterator.
However, if
</p>
<blockquote><pre>
(options &amp; directory_options::skip_permission_denied) != directory_options::none
</pre></blockquote>
<p>
and construction encounters an error indicating that permission to access <code>p</code> is denied, constructs the
end iterator and does not report an error.
<p/>
-3- <i>Postconditions</i>: <code>options() == options</code> for the signatures with a <code>directory_options</code> argument,
otherwise <code>options() == directory_options::none</code>.
<p/>
[&hellip;]
</p>
</blockquote>
[&hellip;]
<pre>
directory_options options() const;
</pre>
<blockquote>
<p>
-15- <i>Returns</i>: The value of the argument passed to the constructor for the <code>options</code> parameter, if present,
otherwise <code>directory_options::none</code>.
<p/>
-16- <i>Throws</i>: Nothing.
</p>
</blockquote>
</blockquote>
</li>
</ol>





</body>
</html>
