Update of /cvsroot/boost/boost/libs/optional/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv26241
Modified Files:
Tag: RC_1_34_0
optional.html
Log Message:
Doc update to reflect latest additions
Index: optional.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/optional/doc/optional.html,v
retrieving revision 1.17.4.2
retrieving revision 1.17.4.3
diff -u -d -r1.17.4.2 -r1.17.4.3
--- optional.html 1 Mar 2007 23:08:33 -0000 1.17.4.2
+++ optional.html 5 Apr 2007 18:55:22 -0000 1.17.4.3
@@ -24,7 +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="#none">none_t and none</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>
@@ -385,6 +385,30 @@
template<class T> inline bool operator >= ( optional<T> const& x,
optional<T> const& y ) ;
+template<class T> inline bool operator == ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator != ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator < ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator > ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator <= ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator >= ( optional<T> const& x,
T const& n ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator == ( T const& n,
optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator != ( T const& n,
optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator < ( T const& n,
optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator > ( T const& n,
optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator <= ( T const& n,
optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
+
+template<class T> inline bool operator >= ( T const& n,
optional<T> const& y ) ; <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>
@@ -912,32 +936,6 @@
<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>
@@ -967,6 +965,33 @@
<HR>
+<pre>T const& optional<T>::get_value_or( T const& default) const
;
+T& optional<T>::get_value_or( T& default ) ;
+
+inline T const& get_optional_value_or ( optional<T> const& o, T
const& default ) ;
+inline T& get_optional_value_or ( optional<T>& o,
T& default ) ;
+</pre>
+<blockquote>
+<p><b>Returns:</b> A reference to the contained value (which can be itself a
reference), 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>::get_ptr() const ;
T* optional<T>::get_ptr() ;
@@ -1235,18 +1260,37 @@
<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 );
+bool operator == ( optional<T> const& x, T const& n );
+bool operator != ( optional<T> const& x, T const& n );
+bool operator < ( optional<T> const& x, T const& n );
+bool operator > ( optional<T> const& x, T const& n );
+bool operator <= ( optional<T> const& x, T const& n );
+bool operator >= ( optional<T> const& x, T const& n );
+bool operator == ( T const& n, optional<T> const& y );
+bool operator != ( T const& n, optional<T> const& y );
+bool operator < ( T const& n, optional<T> const& y );
+bool operator > ( T const& n, optional<T> const& y );
+bool operator <= ( T const& n, optional<T> const& y );
+bool operator >= ( T const& n, optional<T> const& y );
+</pre>
+<blockquote>
+ <p><b>Returns:</b> The result obtained by replacing the argument 'n' by
optional<T>(n).</p>
+</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>
@@ -1388,7 +1432,7 @@
<li>InPlace assignment</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>
+value, a true real reference is stored, thus aliasing can ocurr: </p>
<ul>
<li>Copies of optional<T&> copies the reference, but all copied
references
@@ -1396,7 +1440,7 @@
<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>
+ than a pointer to the reference itself.</li>
</ul>
<HR>
@@ -1407,7 +1451,7 @@
<pre>int x = 1 ;
int& rx = x ;
optional<int&> ora ;
-optional<int&> orb(x) ;
+optional<int&> orb(rx) ;
ora = orb ; // now 'ora' is bound to 'x' through 'rx'
*ora = 2 ; // Changes value of 'x' through 'ora'
assert(x==2);
@@ -1418,7 +1462,7 @@
int& ra = a ;
int b = 2 ;
int& rb = b ;
-ra = rb ; // Changes the value of 'a' to 'b'
+ra = rb ; // Changes the VALUE of 'a' to that of 'b'
assert(a==b);
b = 3 ;
assert(ra!=b); // 'ra' is not rebound to 'b'
@@ -1444,45 +1488,68 @@
It is true that optional<U> strives to behave as much as possible as U
does
whenever it is initialized; but in the case when U is T&, doing so would
result
in inconsistent behavior w.r.t to the lvalue initialization state.</p>
-<p>Imagine optional<T&> forwarding assignment to the referenced
object (thus
-changing the referenced object value but not rebinding), and consider the
-following code :</p>
-<pre> optional<int&> a = get();
- int x = 1 ;
- int& rx = x ;
- optional<int&> b(rx);
- a = b ;
+<p>Consider the following code :</p>
+<pre>
+int x = 1 ;
+int& rx = x ;
+void foo ( optional<int&> & outer )
+{
+ optional<int&> b(rx);
+ outer = b ;
+}
+</pre>
+<p>What should the assignment to 'outer' do?<br>
+If 'outer' is <i>uninitialized</i>, the answer is clear: it should bind to 'x'
(so we now have
+a second reference to 'x').<br>
+But what if 'outer' is already <i>initialized?</i><br>
+The assignment could change the value of the
+referenced object (whatever that is), but doing that would be inconsistent
with the uninitialized case
+and then you wouldn't be able to reason at compile time about all the
references to x since
+the appearance of a new reference to it would depend on wheter the lvalue
('outer')
+is initialized or not.</p>
+<p>Arguably, if rebinding the reference to another object is wrong for your
code, then is
+likely that binding it for the fist time via assignment instead of
intialization is also wrong.
+In that case, you can always just assign the value to the referenced object
directly via
+the access operator <code>*opt=value</code>.</p>
+<p>If rebinding is wrong but first-time binding
+isn't (via assignment), you can always work around the rebinding semantics
using a discriminator:</p>
+<pre>
+if ( !opt )
+ opt = value ; // first-time binding
+else *opt = value ; // assign to referee without rebinding
</pre>
-<p>What does the assignment do?<br>
-If 'a' is <i>uninitialized</i>, the answer is clear: it binds to 'x' (we now
have
-another reference to 'x').<br>
-But what if 'a' is already <i>initialized? </i>it would change the value of
the
-referenced object (whatever that is); which is inconsistent with the other
-possible case.</p>
-<p>If optional<T&> would assign just like T& does, you would
never be able to
-use Optional's assignment without explicitly handling the previous
-initialization state unless your code is capable of functioning whether after
-the assignment, 'a'
-aliases the same object as 'b' or not.</p>
-<p>That is, you would have to discriminate in order to be consistency.<br>
-<br>
-If in your code rebinding to another object is not an option, then is very
-likely that binding for the fist time isn't either. In such case, assignment
to
-an <i>uninitialized</i> optional<T&> shall be prohibited. It is
quite
-possible that in such scenario the precondition that the lvalue must be
already
-initialized exist. If it doesn't, then binding for the first time is OK while
-rebinding is not which is IMO
-very unlikely.<br>
-In such scenario, you can assign the value itself directly, as in:</p>
-<pre>assert(!!opt);
-*opt=value; </pre>
<HR>
-<H2><A NAME="none">none_t</A></H2>
-<p>
+<H2><A NAME="none">none_t and none</A></H2>
+<p>optional<T> supports uninitialized states with a convenient syntax
via a constant of
+the <i>implementation-defined</i> type <code>boost::none_t</code>, identified
as <code>boost::none</code>.</p>
+<p>Starting with Boost version 1.34.0, both <code>boost::none_t</code> and
<code>boost::none</code> are
+included in <code>boost/none.hpp</code>, which is automatically included by
<code>boost/optional/optional.hpp</code>
</p>
+<p>This contant is similar in purpose to NULL, except that is not a <i>null
pointer value</i>. You can use it to initialize
+an optional<T> instance, which has the same effect of a default
constructor, and you can assign it which has the
+effect of reseting the optional<T> instance. You can also use it in
relational operators to make the predicate expression
+more clear.</p>
+<p>Here are some typical examples:</p>
+<pre>
+#include "boost/optional/optional.hpp" // boost/none.hpp is included
automatically
+boost::optional<int> foo ( int a )
+{
+ return some_condition(a) ? boost::make_optional(a) : boost::none ;
+
+ // NOTE: in real code you can just use this:
make_optional(some_condition(a), a )
+}
+
+boost::optional<int> opt = boost::none ;
+
+if ( opt == boost::none )
+ opt = foo(123);
+
+opt = boost::none ;
+
+</pre>
<HR>
@@ -1725,7 +1792,7 @@
</blockquote>
<HR>
-<P>Revised March 1, 2007</P>
+<P>Revised March 27, 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>
-------------------------------------------------------------------------
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
