Update of /cvsroot/boost/boost/libs/optional/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv16836/libs/optional/doc
Modified Files:
Tag: RC_1_34_0
optional.html
Log Message:
none_t/none reimplemented to avoid precompiled header issues (thanks to Joe
Gottam)
optional<T> now has direct relational operator
optional<T>::operator-> fixed for reference types
Index: optional.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/optional/doc/optional.html,v
retrieving revision 1.17.4.1
retrieving revision 1.17.4.2
diff -u -d -r1.17.4.1 -r1.17.4.2
--- optional.html 4 Nov 2006 02:13:53 -0000 1.17.4.1
+++ optional.html 1 Mar 2007 23:08:33 -0000 1.17.4.2
@@ -24,6 +24,7 @@
<DT><A HREF="#examples">Examples</A></DT>
<DT><A HREF="#ref">Optional references</A></DT>
<DT><A HREF="#refassign">Rebinding semantics for assignment of optional
references</A></DT>
+ <DT><A HREF="#none">none_t</A></DT>
<DT><A HREF="#inplace">In-Place Factories</A></DT>
<DT><A HREF="#bool">A note about optional<bool></A></DT>
<DT><A HREF="#exsafety">Exception Safety Guarantees</A></DT>
@@ -139,7 +140,7 @@
<u>purpose</u> of optional<T> suggests
an alternative model: a <i>container</i> that either has a value of T or
nothing.
</p>
-<p>As of this writing I don't know of any precedence for a variable-size
fixed-capacity (of 1)
+<p>As of this writing I don't know of any precedent for a variable-size
fixed-capacity (of 1)
stack-based container model for optional values, yet I believe this is the
consequence of
the lack of practical implementations of such a container rather than an
inherent shortcoming
of the container model.</p>
@@ -324,6 +325,8 @@
optional ( T const& v ) ;
+ optional ( bool condition, T const& v ) ; <u><i>[new in 1.34]</u></i>
+
optional ( optional const& rhs ) ;
template<class U> explicit optional ( optional<U> const&
rhs ) ;
@@ -347,6 +350,8 @@
T const& get() const ;
T& get() ;
+ T const& get_value_or( T const& default ) const ; <u><i>[new in
1.34]</u></i>
+
T const* operator ->() const ;
T* operator ->() ;
@@ -380,6 +385,36 @@
template<class T> inline bool operator >= ( optional<T> const& x,
optional<T> const& y ) ;
+template<class T> inline bool operator == ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator != ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator < ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator > ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator <= ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator >= ( optional<T> const& x,
none_t n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator == ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator != ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator < ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator > ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator <= ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator >= ( none_t n, optional<T>
const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline optional<T> make_optional ( T const& v )
; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline optional<T> make_optional ( bool
condition, T const& v ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline T const& get_optional_value_or (
optional<T> const& opt, T const& default ) ; <u><i>[new in 1.34]</u></i>
+
template<class T> inline T const& get ( optional<T> const& opt ) ;
template<class T> inline T& get ( optional<T> & opt ) ;
@@ -436,7 +471,7 @@
<pre>optional<T>::optional( none_t );</pre>
<blockquote>
-<p><b>Effect:</b> Constructs an <b>optional </b>uninitialized.</p>
+<p><b>Effect:</b> Constructs an <b>optional</b> uninitialized.</p>
<p><b>Postconditions:</b> <b>*this</b> is <u>uninitialized</u>.</p>
<p><b>Throws:</b> Nothing.</p>
<p><b>Notes:</b></p>
@@ -448,9 +483,11 @@
</blockquote>
<p><b>Example:</b></p>
<blockquote>
- <pre>#include <boost/none.hpp></pre>
- <pre>optional<T> n(none) ;
-assert ( !n ) ;</pre>
+<pre>
+#include <boost/none.hpp>
+optional<int> n(boost::none) ;
+assert ( !n ) ;
+</pre>
</blockquote>
</blockquote>
@@ -459,7 +496,6 @@
<pre>optional<T <i>(not a ref)</i>>::optional( T const& v )</pre>
<blockquote>
<p><b>Effect:</b> Directly-Constructs an <b>optional</b>.</p>
-<!-- TemplateName: general/sy_footer_inc.isml -->
<p><b>Postconditions:</b> <b>*this</b> is <u>initialized</u> and its value is
a <i>copy</i> of 'v'.</p>
<p><b>Throws:</b> Whatever T::T( T const& ) throws.</p>
<p><b>Notes: </b> T::T( T const& ) is called.</p>
@@ -468,9 +504,11 @@
</p>
<p><b>Example:</b></p>
<blockquote>
-<pre>T v;
+<pre>
+T v;
optional<T> opt(v);
-assert ( *opt == v ) ;</pre>
+assert ( *opt == v ) ;
+</pre>
</blockquote>
</blockquote>
@@ -484,13 +522,33 @@
<p><b>Throws:</b> Nothing.</p>
<p><b>Example:</b></p>
<blockquote>
-<pre>T v;
+<pre>
+T v;
T& vref = v ;
optional<T&> opt(vref);
assert ( *opt == v ) ;
++ v ; // mutate referee
-assert (*opt == v); </pre>
+assert (*opt == v);
+</pre>
+</blockquote>
</blockquote>
+
+<HR>
+
+<pre>optional<T <i>(not a ref)</i>>::optional( bool condition, T
const& v ) ;
+optional<T&> ::optional( bool condition, T& v ) ;
+</pre>
+
+<blockquote>
+<p>If <i>condition</i> is <code>true</code>, same as:</p>
+<pre>optional<T <i>(not a ref)</i>>::optional( T const& v )
+optional<T&> ::optional( T& v )
+</pre>
+<p>otherwise, same as:</p>
+<pre>
+optional<T <i>(not a ref)</i>>::optional()
+optional<T&> ::optional()
+</pre>
</blockquote>
<HR>
@@ -508,7 +566,8 @@
</p>
<p><b>Example:</b></p>
<blockquote>
- <pre>optional<T> uninit ;
+<pre>
+optional<T> uninit ;
assert (!uninit);
optional<T> uinit2 ( uninit ) ;
@@ -537,7 +596,8 @@
reefer to the same object<b> </b>(they alias).</p>
<p><b>Example:</b></p>
<blockquote>
- <pre>optional<T&> uninit ;
+<pre>
+optional<T&> uninit ;
assert (!uninit);
optional<T&> uinit2 ( uninit ) ;
@@ -580,7 +640,8 @@
<p><b>Example:</b></p>
<blockquote>
-<pre>optional<double> x(123.4);
+<pre>
+optional<double> x(123.4);
assert ( *x == 123.4 ) ;
optional<int> y(x) ;
@@ -608,7 +669,8 @@
<p><b>Example:</b></p>
<blockquote>
-<pre>class C { C ( char, double, std::string ) ; } ;
+<pre>
+class C { C ( char, double, std::string ) ; } ;
C v('A',123.4,"hello");
@@ -624,6 +686,27 @@
<HR>
+<pre>optional& optional<T</i>>::operator= ( none_t n ) ;</pre>
+<blockquote>
+<p><b>Effect:</b> Same as opeator=(optional const& rhs), when rhs is
default-constructed (uninitialized).</p>
+<p><b>Postconditions:</b> <b>*this</b> is uninitialized</p>
+<p><b>Example:</b></p>
+<blockquote>
+<pre>
+#include <boost/none.hpp>
+
+optional<int> def ;
+optional<int> opt(123) ;
+
+opt = boost::none ;
+
+assert ( opt == def ) ;
+</pre>
+</blockquote>
+</blockquote>
+
+<HR>
+
<pre>optional& optional<T <i>(not a ref)</i>>::operator= ( T
const& rhs ) ;</pre>
<blockquote>
<p><b>Effect:</b> Assigns the value 'rhs' to an <b>optional</b>.</p>
@@ -639,7 +722,8 @@
properly uninitialized]</p>
<p><b>Example:</b></p>
<blockquote>
- <pre>T x;
+<pre>
+T x;
optional<T> def ;
optional<T> opt(x) ;
@@ -662,7 +746,8 @@
new object. See <A HREF="#refassign">here</a> for details on this behavior.</p>
<p><b>Example:</b></p>
<blockquote>
- <pre>int a = 1 ;
+<pre>
+int a = 1 ;
int b = 2 ;
T& ra = a ;
T& rb = b ;
@@ -792,12 +877,11 @@
<HR>
<pre>void optional<T>::reset() ;</pre>
<blockquote>
-<p><b>Deprecated: </b>Same as operator=( detail::none_t );</p>
+<p><b>Deprecated: </b>Same as operator=( none_t n);</p>
</blockquote>
<HR>
-
<pre>T const& optional<T <i>(not a ref)</i>>::operator*() const ;
T& optional<T<i> (not a ref)</i>>::operator*();</pre>
@@ -828,6 +912,32 @@
<HR>
+<pre>T const& optional<T <i>(not a ref)</i>>::get_value_or( T
const& default) const ;
+T& optional<T <i>(not a ref)</i>>::get_value_or( T&
default ) ;
+
+inline T const& get_optional_value_or ( optional<T<i> (not a
ref)</i>> const& o, T const& default ) ;
+inline T& get_optional_value_or ( optional<T <i>(not a
ref)</i>>& o, T& default ) ;
+</pre>
+<blockquote>
+<p><b>Returns:</b> A reference to the contained value, if any, or
<code>default</code></p>
+<p><b>Throws:</b> Nothing.</p>
+<p><b>Example:</b></p>
+<blockquote>
+ <pre>T v, z ;
+optional<T> def;
+T const& y = def.get_value_or(z);
+assert ( y == z ) ;
+
+optional<T> opt ( v );
+T const& u = get_optional_value_or(opt,z);
+assert ( u == v ) ;
+assert ( u != z ) ;
+</pre>
+ </blockquote>
+ <pre></pre>
+</blockquote>
+<HR>
+
<pre>T const& optional<T&>::operator*() const ;
T & optional<T<i>&</i>>::operator*();</pre>
@@ -857,29 +967,39 @@
<HR>
-<pre>T const* optional<T <i>(not a ref)</i>>::get_ptr() const ;
-T* optional<T <i>(not a ref)</i>>::get_ptr() ;
+<pre>T const* optional<T>::get_ptr() const ;
+T* optional<T>::get_ptr() ;
-inline T const* get_pointer ( optional<T <i>(not a ref)</i>> const&
) ;
-inline T* get_pointer ( optional<T <i>(not a ref)</i>> &) ;
+inline T const* get_pointer ( optional<T> const& ) ;
+inline T* get_pointer ( optional<T> &) ;
</pre>
<blockquote>
<p><b>Returns:</b> If <b>*this</b> is initialized, a pointer to the contained
value; else 0 (<i>null</i>).
</p>
<p><b>Throws:</b> Nothing.</p>
+<p><b>Notes:</b> If T is a reference type, the pointer is to the referenced
object</p>
<p><b>Notes:</b> The contained value is permanently stored within *this, so
-you should not hold nor delete this pointer
+you should not hold nor delete this pointer.
</p>
<p><b>Example:</b></p>
<blockquote>
- <pre>T v;
-optional<T> opt(v);
-optional<T> const copt(v);
-T* p = opt.get_ptr() ;
-T const* cp = copt.get_ptr();
+ <pre>int v=123;
+optional<int> opt(v);
+optional<int> const copt(v);
+int* p = opt.get_ptr() ;
+int const* cp = copt.get_ptr();
assert ( p == get_pointer(opt) );
assert ( cp == get_pointer(copt) ) ;
+
+int& rv = v ;
+optional<int&> optr(rv);
+
+*(optr.get_ptr()) = 456 ;
+
+assert ( v == 456 );
+
+
</pre>
</blockquote>
</blockquote>
@@ -888,13 +1008,14 @@
<HR>
-<pre>T const* optional<T <i>(not a ref)</i>>::operator ->() const ;
-T* optional<T <i>(not a ref)</i>>::operator ->() ;
+<pre>T const* optional<T>::operator ->() const ;
+T* optional<T>::operator ->() ;
</pre>
<blockquote>
<p><b>Requirements: *this</b> is initialized.</p>
<p><b>Returns:</b> A pointer to the contained value.</p>
<p><b>Throws:</b> Nothing.</p>
+<p><b>Notes:</b> If T is a reference type, the pointer is to the referenced
object</p>
<p><b>Notes:</b> The requirement is asserted via BOOST_ASSERT().</p>
<p><b>Example:</b></p>
<blockquote>
@@ -902,6 +1023,14 @@
X x ;
optional<X> opt (x);
opt->mdata = 2 ;
+
+X& rx = x ;
+
+optional<X&> optr (rx);
+optr->mdata = 4 ;
+
+assert ( x.mdata = 4 )
+
</pre>
</blockquote>
</blockquote>
@@ -965,18 +1094,47 @@
<HR>
+<pre>optional<T <i>(not a ref)</i>> make_optional( T const& v )</pre>
+<blockquote>
+<p><b>Returns:</b> optional<T>(v) for the <i>deduced</i> type
<code>T</code> of <code>v</code>.</p>
+<p><b>Example:</b></p>
+<blockquote>
+<pre>template<class T> void foo ( optional<T> const& opt ) ;
+
+foo ( make_optional(1+1) ) ; // Creates an optional<int>
+</blockquote>
+</blockquote>
+<HR>
+
+<pre>optional<T <i>(not a ref)</i>> make_optional( bool condition, T
const& v )</pre>
+<blockquote>
+<p><b>Returns:</b> optional<T>(condition,v) for the <i>deduced</i> type
<code>T</code> of <code>v</code>.</p>
+<p><b>Example:</b></p>
+<blockquote>
+<pre>optional<double> calculate_foo()
+{
+ double val = compute_foo();
+ return make_optional(is_not_nan_and_finite(val),val);
+}
+
+optional<double> v = calculate_foo();
+if ( !v )
+ error("foo wasn't computed");
+</blockquote>
+</blockquote>
+
+<HR>
+
<pre>bool operator == ( optional<T> const& x, optional<T>
const& y );</pre>
<blockquote>
<p><b>Returns:</b> If both <b>x</b> and <b>y</b> are initialied, <code>(*x ==
*y)</code>.
-If only x or y is initialized, <code>false</code>. If both are uninitialized,
<code>true</code>.
-</p>
+If only x or y is initialized, <code>false</code>. If both are uninitialized,
<code>true</code>. </p>
<p><b>Throws:</b> Nothing.</p>
<p><b>Notes:</b> Pointers have shallow relational operators while
<b>optional</b> has
deep relational operators. Do not use operator == directly in generic code
which expect to be given either an optional<T> or a pointer;
-use <a href="../../utility/OptionalPointee.html#equal">equal_pointees()</a>
instead
-</p>
+use <a href="../../utility/OptionalPointee.html#equal">equal_pointees()</a>
instead </p>
<p><b>Example:</b></p>
<blockquote>
<pre>T x(12);
@@ -1012,14 +1170,12 @@
<blockquote>
<p><b>Returns:</b> If <b>y</b> is not initialized, <code>false</code>.
If <b>y</b> is initialized and <b>x</b> is not initialized, <code>true</code>.
-If both <b>x</b> and <b>y</b> are initialized, <code>(*x < *y)</code>.
-</p>
+If both <b>x</b> and <b>y</b> are initialized, <code>(*x < *y)</code>. </p>
<p><b>Throws:</b> Nothing.</p>
<p><b>Notes:</b> Pointers have shallow relational operators while
<b>optional</b> has
deep relational operators. Do not use operator < directly in generic code
which expect to be given either an optional<T> or a pointer;
-use <a href="../../utility/OptionalPointee.html#less">less_pointees()</a>
instead
-</p>
+use <a href="../../utility/OptionalPointee.html#less">less_pointees()</a>
instead </p>
<p><b>Example:</b></p>
<blockquote>
<pre>T x(12);
@@ -1078,27 +1234,39 @@
</blockquote>
<HR>
+<pre>
+bool operator == ( optional<T> const& x, none_t n );
+bool operator != ( optional<T> const& x, none_t n );
+bool operator < ( optional<T> const& x, none_t n );
+bool operator > ( optional<T> const& x, none_t n );
+bool operator <= ( optional<T> const& x, none_t n );
+bool operator >= ( optional<T> const& x, none_t n );
+bool operator == ( none_t n, optional<T> const& y );
+bool operator != ( none_t n, optional<T> const& y );
+bool operator < ( none_t n, optional<T> const& y );
+bool operator > ( none_t n, optional<T> const& y );
+bool operator <= ( none_t n, optional<T> const& y );
+bool operator >= ( none_t n, optional<T> const& y );
+</pre>
+<blockquote>
+ <p><b>Returns:</b> The result obtained by replacing the argument 'n' by
optional<T>().</p>
+</blockquote>
+<HR>
<pre>void swap ( optional<T>& x, optional<T>& y );</pre>
<blockquote>
-<p><b>Effect:</b> If both <b>x</b> and <b>y</b> are initialized, calls
<code>swap(*x,*y)</code>
-using std::swap.<br>
-If only one is initialized, say x, calls: <code>y.reset(*x);
x.reset();</code><br>
-If none is initialized, does nothing.
-</p>
+<p><b>Effect:</b> If both <b>x</b> and <b>y</b> are initialized, calls
<code>swap(*x,*y)</code> using std::swap.<br>
+If only one is initialized, say x, calls: <code>y = *x; x =
boost:none;</code><br>
+If none is initialized, does nothing. </p>
<p><b>Postconditions:</b> The states of x and y interchanged.</p>
<p><b>Throws:</b> If both are initialized, whatever swap(T&,T&) throws.
-If only one is initialized, whatever T::T ( T const& ) throws.
-</p>
-<p><b>Notes:</b> If both are initialized, swap(T&,T&) is used
<i>unqualified</i>
-but with std::swap introduced in scope.<br>
-If only one is initialized, T::~T() and T::T( T const& ) is called.
-</p>
+If only one is initialized, whatever T::T ( T const& ) throws. </p>
+<p><b>Notes:</b> If both are initialized, swap(T&,T&) is used
<i>unqualified</i> but with std::swap introduced in scope.<br>
+If only one is initialized, T::~T() and T::T( T const& ) is called. </p>
<p><b>Exception Safety:</b> If both are initialized, this operation has the
exception
safety guarantees of swap(T&,T&).<br>
-If only one is initialized, it has the same <b>basic</b> guarantee as
optional<T>::reset( T const& ).
-</p>
+If only one is initialized, it has the same <b>basic</b> guarantee as
optional<T>::operator=( T const& ). </p>
<p><b>Example:</b></p>
<blockquote>
<pre>T x(12);
@@ -1148,12 +1316,12 @@
<pre>optional<string> name ;
if ( database.open() )
{
- name.reset ( database.lookup(employer_name) ) ;
+ name = database.lookup(employer_name) ;
}
else
{
if ( can_ask_user )
- name.reset ( user.ask(employer_name) ) ;
+ name = user.ask(employer_name) ;
}
if ( name )
@@ -1174,7 +1342,7 @@
void clip_in_rect ( rect const& rect )
{
....
- m_clipping_rect.reset ( rect
) ; // initialized here.
+ m_clipping_rect = rect ; //
initialized here.
}
void draw ( canvas& cvs )
@@ -1218,15 +1386,16 @@
<li>Converting assignment</li>
<li>InPlace construction</li>
<li>InPlace assignment</li>
- <li>Value-access via pointer</li>
</ul>
<p>Also, even though optional<T&> treats it wrapped pseudo-object
much as a real
value, a true real reference is stored so aliasing will ocurr: </p>
<ul>
- <li>Copies of optional<T&> will copy the references but all these
references
+ <li>Copies of optional<T&> copies the reference, but all copied
references
will nonetheless reefer to the same object.</li>
- <li>Value-access will actually provide access to the referenced object rather
+ <li>Value-access provides access to the referenced object rather
+ than the reference itself.</li>
+ <li>Pointer-access provides a pointer to the referenced object rather
than the reference itself.</li>
</ul>
@@ -1254,8 +1423,7 @@
b = 3 ;
assert(ra!=b); // 'ra' is not rebound to 'b'
</pre>
-<p>Now, if you assign to an <i>initialized</i> optional<T&>, the
effect is to <b>
-rebind</b> to the new object instead of assigning the referee. This is unlike
+<p>Now, if you assign to an <i>initialized</i> optional<T&>, the
effect is to <b>rebind</b> to the new object instead of assigning the referee.
This is unlike
bare C++ references.</p>
<pre>int a = 1 ;
int b = 2 ;
@@ -1311,6 +1479,13 @@
<HR>
+<H2><A NAME="none">none_t</A></H2>
+<p>
+</p>
+
+
+<HR>
+
<H2><A NAME="inplace">In-Place Factories</A></H2>
<p>
One of the typical problems with wrappers and containers is that their
@@ -1358,8 +1533,7 @@
</pre>
<p>A limitation of this method is that it doesn't scale well to wrapped
objects with multiple
constructors nor to generic code were the constructor overloads are
unknown.</p>
-<p>The solution presented in this library is the family of
<b>InPlaceFactories</b> and
-<b>TypedInPlaceFactories</b>.<br>
+<p>The solution presented in this library is the family of
<b>InPlaceFactories</b> and <b>TypedInPlaceFactories</b>.<br>
These factories are a family of classes which encapsulate an increasing number
of arbitrary
constructor parameters and supply a method to construct an object of a given
type using those
parameters at an address specified by the user via placement new.</p>
@@ -1427,10 +1601,7 @@
W ( in_place(123,"hello") ) ;
}
</pre>
-<p>The factories are implemented in the headers:
-<a href="../../../boost/utility/in_place_factory.hpp">in_place_factory.hpp</a>
and
-<a
href="../../../boost/utility/typed_in_place_factory.hpp">typed_in_place_factory.hpp</a>
-</p>
+<p>The factories are implemented in the headers: <a
href="../../../boost/utility/in_place_factory.hpp">in_place_factory.hpp</a> and
<a
href="../../../boost/utility/typed_in_place_factory.hpp">typed_in_place_factory.hpp</a>
</p>
<HR>
@@ -1440,9 +1611,8 @@
the <i>maybe</i> state <u>represents a valid value</u>, unlike the
corresponding state
of an uninitialized optional<bool>.<br>
It should be carefully considered if an optional<bool> instead of a
tribool is really needed</p>
-<p>Second, optional<> provides an implicit conversion to bool. This
conversion
- refers to the initialization state and not to the contained value.<br>
-Using optional<bool> can lead to subtle errors due to the implicit bool
conversion:</p>
+<p>Second, optional<> provides a simple way to test initialization
state: an implicit conversion to a type that evaluates as a 'bool' in a boolean
context.<br>
+Using optional<bool> can lead to subtle errors due to this implicit
conversion:</p>
<pre>void foo ( bool v ) ;
void bar()
{
@@ -1458,7 +1628,9 @@
integral promotions don't apply (i.e. if foo() takes an 'int' instead, it
won't compile). <HR>
<H2><A NAME="exsafety">Exception Safety Guarantees</A></H2>
-<H3><u>Assignment and Reset:</u></H3>
+
+<H3><u>Assignment:</u></H3>
+<p><i>IMPORTANT NOTE: This changed in 1.33.1 with respect to previous
versions</i></p>
<p>Because of the current implementation (see <A HREF="#impl">Implementation
Notes</A>), all
of the assignment methods:</p>
<ul>
@@ -1471,61 +1643,17 @@
InPlaceFactory const& ) </code></li>
<li> <code>template<class TypedInPlaceFactory>
optional<T>::operator= (
TypedInPlaceFactory const& ) </code></li>
- <li> <code>optional<T>:::reset ( T const&)</code></li>
</ul>
-<p>Can only <i>guarantee</i> the <u>basic exception safety</u>: The lvalue
optional is left <u>uninitialized</u>
-if an exception is thrown (any previous value is <i>first</i> destroyed using
T::~T())</p>
+<p>cannot offer any <i>exception safety guarantee</i> beyond that provided by
<code>T::operator=( T const& )</code></p>
<p>On the other hand, the <i>uninitializing</i> methods:</p>
<ul>
<li><code>optional<T>::operator= ( detail::none_t ) </code></li>
- <li><code>optional<T>::reset()</code></li>
</ul>
-<p>Provide the no-throw guarantee (assuming a no-throw T::~T())</p>
-<p>However, since <code>optional<></code> itself doesn't throw any
exceptions,
-the only source for exceptions here are T's constructor, so if you know the
exception guarantees
-for T::T ( T const& ), you know that optional's assignment and reset has
the same guarantees.</p>
-<pre>//
-// Case 1: Exception thrown during assignment.
-//
-T v0(123);
-optional<T> opt0(v0);
-try
-{
- T v1(456);
- optional<T> opt1(v1);
- opt0 = opt1 ;
-
- // If no exception was thrown, assignment succeeded.
- assert( *opt0 == v1 ) ;
-}
-catch(...)
-{
- // If any exception was thrown, 'opt0' is reset to uninitialized.
- assert( !opt0 ) ;
-}
-
-//
-// Case 2: Exception thrown during reset(v)
-//
-T v0(123);
-optional<T> opt(v0);
-try
-{
- T v1(456);
- opt.reset ( v1 ) ;
+<p>Provides the no-throw guarantee (assuming a no-throw T::~T()) becuse it
only destroys the stored object.</p>
- // If no exception was thrown, reset succeeded.
- assert( *opt == v1 ) ;
-}
-catch(...)
-{
- // If any exception was thrown, 'opt' is reset to uninitialized.
- assert( !opt ) ;
-}
-</pre>
<H3><u>Swap:</u></H3>
<p><code>void swap( optional<T>&, optional<T>& )</code>
has the same exception guarantee as <code>swap(T&,T&)</code> when both
optionals are initialized.<br>
-If only one of the optionals is initialized, it gives the same <i>basic</i>
exception guarantee as <code>optional<T>::reset( T const& )</code>
(since <code>optional<T>::reset()</code> doesn't throw).<br>
+If only one of the optionals is initialized, it gives the same exception
guarantee as <code>T::operator=( T const& )</code> (since
<code>optional<T>::operator=( none_t )</code> doesn't throw).<br>
If none of the optionals is initialized, it has no-throw guarantee since it is
a no-op. </p>
<HR>
@@ -1539,14 +1667,11 @@
<H2><A NAME="impl">Implementation Notes</A></H2>
<p>optional<T> is currently implemented
- using a custom aligned storage facility built from <code>alignment_of</code>
and <code>type_with_alignment</code> (both from Type Traits).
- It uses a separate boolean flag to indicate the initialization state.<br>
- Placement new with T's copy constructor and T's destructor
- are explicitly used to initialize,copy and destroy optional values.<br>
- As a result, T's default constructor is effectively by-passed, but the
exception
- guarantees are basic.<br>
- It is planned to replace the current implementation with another with
- stronger exception safety, such as a future boost::variant<T,nil_t>. </p>
+ using a custom aligned storage facility built from <code>alignment_of</code>
and <code>type_with_alignment</code> (both from Type Traits).
+ It uses a separate boolean flag to indicate the initialization state.</p>
+<p>Placement new with T's copy constructor and T's destructor
+ is explicitly used to initialize and destroy optional values. This allows
T's default constructor to be effectively by-passed.</p>
+<p>If assignment is used and the lvalue optional is uninitialized, T's copy
constructor is used. However, if it is already initialized, T's assignment
operator is used. This prevents optional from offering any exception guarantee
stronger than the one offered by the type T itself</p>
<HR>
@@ -1600,15 +1725,12 @@
</blockquote>
<HR>
-<P>Revised April 21, 2005</P>
-<p>© Copyright Fernando Luis Cacciola Carballal, 2003,2004,2005</p>
+<P>Revised March 1, 2007</P>
+<p>© Copyright Fernando Luis Cacciola Carballal, 2003-2007</p>
<p> Use, modification, and distribution are subject to the Boost Software
-License, Version 1.0. (See accompanying file <a
href="../../../LICENSE_1_0.txt">
-LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt";>
-www.boost.org/LICENSE_1_0.txt</a>)</p>
+License, Version 1.0. (See accompanying file <a
href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";>www.boost.org/LICENSE_1_0.txt</a>)</p>
<P>Developed by <A HREF="mailto:[EMAIL PROTECTED]">Fernando Cacciola</A>,
the latest version of this file can be found at <A
-HREF="http://www.boost.org";>www.boost.org</A>, and the boost
-<A HREF="http://www.boost.org/more/mailing_lists.htm#main";>discussion
lists</A></P>
-</BODY>
-</HTML>
+HREF="http://www.boost.org";>www.boost.org</A>, and the boost <A
HREF="http://www.boost.org/more/mailing_lists.htm#main";>discussion lists</A></P>
+</pre></BODY>
+</HTML>
\ No newline at end of file
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys-and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
