boostorg/optional
1
0
Fork 1
mirror of https://github.com/boostorg/optional.git synced 2025-07-21 08:12:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: described optional reference binding issues

Browse Source
This commit is contained in:
Andrzej Krzemienski
2014-05-08 21:50:41 +02:00
parent f94846ccc5
commit 1c9775a9d9
9 changed files with 181 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/dependencies.qbk
View File

@ -14,4 +14,54 @@
The implementation uses `type_traits/alignment_of.hpp` and
`type_traits/type_with_alignment.hpp`
[section Optional Reference Binding]
On compilers that do not conform to Standard C++ rules of reference binding, operations on optional references might give adverse results: rather than binding a reference to a designated object they may create an unexpected temporary and bind to it. Compilers known to have these deficiencies include GCC versions 4.2, 4.3, 4.4, 4.5; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, 11.0, 12.0. On these compilers prefer using direct-initialization and copy assignment of optional references to copy-initialization and assignment from `T&`:
const int i = 0;
optional<const int&> or1;
optional<const int&> or2 = i; // not portable
or1 = i; // not portable
optional<const int&> or3(i); // portable
or1 = optional<const int&>(i); // portable
In order to check if your compiler correctly implements reference binding use this test program.
#include <cassert>
const int global_i = 0;
struct TestingReferenceBinding
{
TestingReferenceBinding(const int& ii)
{
assert(&ii == &global_i);
}
void operator=(const int& ii)
{
assert(&ii == &global_i);
}
void operator=(int&&) // remove this if your compiler doesn't have rvalue refs
{
assert(false);
}
};
int main()
{
const int& iref = global_i;
assert(&iref == &global_i);
TestingReferenceBinding ttt = global_i;
ttt = global_i;
TestingReferenceBinding ttt2 = iref;
ttt2 = iref;
}
[endsect]
[endsect]

34
doc/html/boost_optional/a_note_about_optional_bool_.html
View File

@ -32,7 +32,7 @@
be used with special caution and consideration.
</p>
<p>
First, it is functionally similar to a tristate boolean (false,maybe,true)
First, it is functionally similar to a tristate boolean (false, maybe, true)
&#8212;such as <a href="../../../../../doc/html/tribool.html" target="_top">boost::tribool</a>&#8212;
except that in a tristate boolean, the maybe state <span class="underline">represents
a valid value</span>, unlike the corresponding state of an uninitialized
@ -42,10 +42,11 @@
needed.
</p>
<p>
Second, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>
provides an implicit conversion to <code class="computeroutput"><span class="keyword">bool</span></code>.
This conversion refers to the initialization state and not to the contained
value. Using <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code> can
Second, although <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>
provides a contextual conversion to <code class="computeroutput"><span class="keyword">bool</span></code>
in C++11, this falls back to an implicit conversion on older compilers. This
conversion refers to the initialization state and not to the contained value.
Using <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code> can
lead to subtle errors due to the implicit <code class="computeroutput"><span class="keyword">bool</span></code>
conversion:
</p>
@ -67,6 +68,29 @@
takes an <code class="computeroutput"><span class="keyword">int</span></code> instead, it won't
compile).
</p>
<p>
Third, mixed comparisons with <code class="computeroutput"><span class="keyword">bool</span></code>
work differently than similar mixed comparisons between pointers and <code class="computeroutput"><span class="keyword">bool</span></code>, so the results might surprise you:
</p>
<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">oEmpty</span><span class="special">(</span><span class="identifier">none</span><span class="special">),</span> <span class="identifier">oTrue</span><span class="special">(</span><span class="keyword">true</span><span class="special">),</span> <span class="identifier">oFalse</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span> <span class="comment">// renders true</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// renders false!</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span> <span class="comment">// renders false!</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span> <span class="comment">// renders false</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// renders true!</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span> <span class="comment">// renders false</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span> <span class="comment">// renders false</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// renders false</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span> <span class="comment">// renders true</span>
</pre>
<p>
In other words, for <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>, the following assertion does not hold:
</p>
<pre class="programlisting"><span class="identifier">assert</span><span class="special">((</span><span class="identifier">opt</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">)</span> <span class="special">==</span> <span class="special">(!</span><span class="identifier">opt</span><span class="special">));</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>

64
doc/html/boost_optional/dependencies_and_portability.html
View File

@ -27,10 +27,74 @@
<a name="boost_optional.dependencies_and_portability"></a><a class="link" href="dependencies_and_portability.html" title="Dependencies and Portability">Dependencies
and Portability</a>
</h2></div></div></div>
<div class="toc"><dl class="toc"><dt><span class="section"><a href="dependencies_and_portability.html#boost_optional.dependencies_and_portability.optional_reference_binding">Optional
Reference Binding</a></span></dt></dl></div>
<p>
The implementation uses <code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">alignment_of</span><span class="special">.</span><span class="identifier">hpp</span></code> and
<code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">type_with_alignment</span><span class="special">.</span><span class="identifier">hpp</span></code>
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.dependencies_and_portability.optional_reference_binding"></a><a class="link" href="dependencies_and_portability.html#boost_optional.dependencies_and_portability.optional_reference_binding" title="Optional Reference Binding">Optional
Reference Binding</a>
</h3></div></div></div>
<p>
On compilers that do not conform to Standard C++ rules of reference binding,
operations on optional references might give adverse results: rather than
binding a reference to a designated object they may create an unexpected
temporary and bind to it. Compilers known to have these deficiencies include
GCC versions 4.2, 4.3, 4.4, 4.5; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0,
11.0, 12.0. On these compilers prefer using direct-initialization and copy
assignment of optional references to copy-initialization and assignment from
<code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>:
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">or1</span><span class="special">;</span>
<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">or2</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span> <span class="comment">// not portable</span>
<span class="identifier">or1</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span> <span class="comment">// not portable</span>
<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">or3</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// portable</span>
<span class="identifier">or1</span> <span class="special">=</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// portable</span>
</pre>
<p>
In order to check if your compiler correctly implements reference binding
use this test program.
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">global_i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">struct</span> <span class="identifier">TestingReferenceBinding</span>
<span class="special">{</span>
<span class="identifier">TestingReferenceBinding</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">ii</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(&amp;</span><span class="identifier">ii</span> <span class="special">==</span> <span class="special">&amp;</span><span class="identifier">global_i</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">=(</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">ii</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(&amp;</span><span class="identifier">ii</span> <span class="special">==</span> <span class="special">&amp;</span><span class="identifier">global_i</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">=(</span><span class="keyword">int</span><span class="special">&amp;&amp;)</span> <span class="comment">// remove this if your compiler doesn't have rvalue refs</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">iref</span> <span class="special">=</span> <span class="identifier">global_i</span><span class="special">;</span>
<span class="identifier">assert</span><span class="special">(&amp;</span><span class="identifier">iref</span> <span class="special">==</span> <span class="special">&amp;</span><span class="identifier">global_i</span><span class="special">);</span>
<span class="identifier">TestingReferenceBinding</span> <span class="identifier">ttt</span> <span class="special">=</span> <span class="identifier">global_i</span><span class="special">;</span>
<span class="identifier">ttt</span> <span class="special">=</span> <span class="identifier">global_i</span><span class="special">;</span>
<span class="identifier">TestingReferenceBinding</span> <span class="identifier">ttt2</span> <span class="special">=</span> <span class="identifier">iref</span><span class="special">;</span>
<span class="identifier">ttt2</span> <span class="special">=</span> <span class="identifier">iref</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>

6
doc/html/boost_optional/detailed_semantics.html
View File

@ -1446,9 +1446,9 @@
<span class="keyword">const</span> <span class="special">;</span></code>
</p></blockquote></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<span class="bold"><strong>Deprecated:</strong></span> Same as <code class="computeroutput"><span class="keyword">operator</span>
</code><span class="emphasis"><em>unspecified-bool-type</em></span><code class="computeroutput"><span class="special">()</span>
<span class="special">;</span></code>
<span class="bold"><strong>Deprecated:</strong></span> Same as <code class="computeroutput"><span class="keyword">explicit</span>
<span class="keyword">operator</span> <span class="keyword">bool</span>
<span class="special">()</span> <span class="special">;</span></code>
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span>

8
doc/html/boost_optional/optional_references.html
View File

@ -76,11 +76,9 @@
<tr><td align="left" valign="top"><p>
On compilers that do not conform to Standard C++ rules of reference binding,
operations on optional references might give adverse results: rather than
binding a reference to a designated object they may create a temporary and
bind to it. Compilers known to have these deficiencies include GCC versions
4.2, 4.3, 4.4, 4.5; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, 11.0, 12.0.
On these compilers prefer using direct-initialization and copy assignment
of optional references to copy-initialization and assignment from <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>.
binding a reference to a designated object they may create an unexpected
temporary and bind to it. For more details see <a class="link" href="dependencies_and_portability.html#boost_optional.dependencies_and_portability.optional_reference_binding" title="Optional Reference Binding">Dependencies
and Portability section</a>.
</p></td></tr>
</table></div>
<h4>

8
doc/html/index.html
View File

@ -69,6 +69,8 @@
<dt><span class="section"><a href="boost_optional/type_requirements.html">Type requirements</a></span></dt>
<dt><span class="section"><a href="boost_optional/dependencies_and_portability.html">Dependencies
and Portability</a></span></dt>
<dd><dl><dt><span class="section"><a href="boost_optional/dependencies_and_portability.html#boost_optional.dependencies_and_portability.optional_reference_binding">Optional
Reference Binding</a></span></dt></dl></dd>
<dt><span class="section"><a href="boost_optional/acknowledgments.html">Acknowledgments</a></span></dt>
</dl>
</div>
@ -77,8 +79,8 @@
<a name="optional.introduction"></a><a class="link" href="index.html#optional.introduction" title="Introduction">Introduction</a>
</h2></div></div></div>
<p>
This library can be used to represent 'optional' (or 'nullable') objects and
safely pass them by value:
This library can be used to represent 'optional' (or 'nullable') objects that
can be safely passed by value:
</p>
<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">readInt</span><span class="special">();</span> <span class="comment">// this function may return either an int or a not-an-int</span>
@ -90,7 +92,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: May 07, 2014 at 15:05:52 GMT</small></p></td>
<td align="left"><p><small>Last revised: May 08, 2014 at 12:05:10 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

2
doc/optional.qbk
View File

@ -46,7 +46,7 @@ Distributed under the Boost Software License, Version 1.0.
[section Introduction]
This library can be used to represent 'optional' (or 'nullable') objects and safely pass them by value:
This library can be used to represent 'optional' (or 'nullable') objects that can be safely passed by value:
optional<int> readInt(); // this function may return either an int or a not-an-int

2
doc/reference.qbk
View File

@ -939,7 +939,7 @@ __SPACE__
[: `bool optional<T>::is_initialized() const ;`]
* [*Deprecated:] Same as `operator `['unspecified-bool-type]`() ;`
* [*Deprecated:] Same as `explicit operator bool () ;`
__SPACE__

31
doc/special_cases.qbk
View File

@ -21,7 +21,7 @@ will nonetheless refer to the same object.
* Value-access will actually provide access to the referenced object
rather than the reference itself.
[warning On compilers that do not conform to Standard C++ rules of reference binding, operations on optional references might give adverse results: rather than binding a reference to a designated object they may create a temporary and bind to it. Compilers known to have these deficiencies include GCC versions 4.2, 4.3, 4.4, 4.5; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, 11.0, 12.0. On these compilers prefer using direct-initialization and copy assignment of optional references to copy-initialization and assignment from `T&`.]
[warning On compilers that do not conform to Standard C++ rules of reference binding, operations on optional references might give adverse results: rather than binding a reference to a designated object they may create an unexpected temporary and bind to it. For more details see [link boost_optional.dependencies_and_portability.optional_reference_binding Dependencies and Portability section].]
[heading Rvalue references]
@ -262,17 +262,17 @@ The factories are implemented in the headers: __IN_PLACE_FACTORY_HPP__ and __TYP
`optional<bool>` should be used with special caution and consideration.
First, it is functionally similar to a tristate boolean (false,maybe,true)
First, it is functionally similar to a tristate boolean (false, maybe, true)
—such as __BOOST_TRIBOOL__— except that in a tristate boolean, the maybe state
[_represents a valid value], unlike the corresponding state of an uninitialized
`optional<bool>`.
It should be carefully considered if an `optional<bool>` instead of a `tribool`
is really needed.
Second, `optional<>` provides an implicit conversion to `bool`. This
conversion refers to the initialization state and not to the contained value.
Using `optional<bool>` can lead to subtle errors due to the implicit `bool`
conversion:
Second, although `optional<>` provides a contextual conversion to `bool` in C++11,
this falls back to an implicit conversion on older compilers. This conversion refers
to the initialization state and not to the contained value. Using `optional<bool>`
can lead to subtle errors due to the implicit `bool` conversion:
void foo ( bool v ) ;
void bar()
@ -289,6 +289,25 @@ The only implicit conversion is to `bool`, and it is safe in the sense that
typical integral promotions don't apply (i.e. if `foo()` takes an `int`
instead, it won't compile).
Third, mixed comparisons with `bool` work differently than similar mixed comparisons between pointers and `bool`, so the results might surprise you:
optional<bool> oEmpty(none), oTrue(true), oFalse(false);
if (oEmpty == none); // renders true
if (oEmpty == false); // renders false!
if (oEmpty == true); // renders false!
if (oFalse == none); // renders false
if (oFalse == false); // renders true!
if (oFalse == true); // renders false
if (oTrue == none); // renders false
if (oTrue == false); // renders false
if (oTrue == true); // renders true
In other words, for `optional<>`, the following assertion does not hold:
assert((opt == false) == (!opt));
[endsect]
[section Exception Safety Guarantees]