mirror of
https://github.com/boostorg/utility.git
synced 2026-01-27 07:22:14 +00:00
4ca0c3b7c2
https://svn.boost.org/svn/boost/trunk ........ r40889 | nikiml | 2007-11-07 08:06:55 -0800 (Wed, 07 Nov 2007) | 1 line added forgotten array_object_manager_traits::get_pytype ........ r40890 | bemandawes | 2007-11-07 08:08:09 -0800 (Wed, 07 Nov 2007) | 1 line Copyright and/or License cleanup ........ r40892 | nesotto | 2007-11-07 08:54:10 -0800 (Wed, 07 Nov 2007) | 1 line changed constants to inline function to avoid ODR problems ........ r40893 | garcia | 2007-11-07 09:06:19 -0800 (Wed, 07 Nov 2007) | 2 lines changed url to the right one. ........ r40894 | johnmaddock | 2007-11-07 09:17:39 -0800 (Wed, 07 Nov 2007) | 1 line Added support for VC9. ........ r40895 | johnmaddock | 2007-11-07 09:21:41 -0800 (Wed, 07 Nov 2007) | 1 line Regenerated docs to add license info. ........ r40896 | johnmaddock | 2007-11-07 09:38:19 -0800 (Wed, 07 Nov 2007) | 2 lines Removed PDF docs: we'll put these somewhere else. Fixed some license/copyright issues. ........ r40897 | igaztanaga | 2007-11-07 09:55:18 -0800 (Wed, 07 Nov 2007) | 1 line Increased shared memory size, since it was insufficient for 64 bit applications ........ r40898 | jhunold | 2007-11-07 10:06:31 -0800 (Wed, 07 Nov 2007) | 4 lines Fix: remove <user-interface>gui from usage-requirements of QtGui. Rationale: <user-interface>gui merely disables console output window on <target-os>windows. But users often need console debug output when running Gui apps. ........ r40900 | johnmaddock | 2007-11-07 10:26:11 -0800 (Wed, 07 Nov 2007) | 1 line Added license info. ........ r40901 | johnmaddock | 2007-11-07 10:27:08 -0800 (Wed, 07 Nov 2007) | 1 line Added license info. ........ r40902 | johnmaddock | 2007-11-07 10:29:00 -0800 (Wed, 07 Nov 2007) | 1 line Added copyright. ........ r40903 | johnmaddock | 2007-11-07 10:38:23 -0800 (Wed, 07 Nov 2007) | 1 line Added license info. ........ r40906 | guwi17 | 2007-11-07 11:34:03 -0800 (Wed, 07 Nov 2007) | 2 lines - io.hpp: added missing include ........ r40907 | danieljames | 2007-11-07 12:27:25 -0800 (Wed, 07 Nov 2007) | 1 line Copied Joel's license changes to the xhtml stylesheet. ........ r40912 | bemandawes | 2007-11-07 13:54:48 -0800 (Wed, 07 Nov 2007) | 1 line Initial commit. The starting point for the reference documentation is N1975, Filesystem Library Proposal for TR2 (Revision 3). ........ r40914 | pdimov | 2007-11-07 14:47:55 -0800 (Wed, 07 Nov 2007) | 1 line Attempt unspecified bool fix for Sun 5.7-5.9 ........ r40916 | bemandawes | 2007-11-07 17:47:36 -0800 (Wed, 07 Nov 2007) | 1 line Explicitly say 'no top-posting'. Add links to Wikipedia posting article ........ r40918 | bemandawes | 2007-11-07 18:55:21 -0800 (Wed, 07 Nov 2007) | 1 line Cope with larger errno on 64-bit systems ........ r40919 | chris_kohlhoff | 2007-11-07 20:10:14 -0800 (Wed, 07 Nov 2007) | 2 lines Eliminate the need for an extra thread to perform timer dispatching. ........ [SVN r40922]
164 lines
6.0 KiB
HTML
164 lines
6.0 KiB
HTML
<HTML>
|
|
<Head>
|
|
<Title>OptionalPointee Concept</Title>
|
|
</HEAD>
|
|
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
|
ALINK="#ff0000">
|
|
<IMG SRC="../../boost.png"
|
|
ALT="C++ Boost" width="277" height="86">
|
|
<!--end header-->
|
|
<BR Clear>
|
|
<H1>Concept: OptionalPointee</H1>
|
|
|
|
<h3>Description</h3>
|
|
A type is a model of <i>OptionalPointee</i> if it points to (or refers to) a value
|
|
that may not exist. That is, if it has a <b>pointee</b> which might be <b>valid</b>
|
|
(existent) or <b>invalid</b> (inexistent); and it is possible to test whether the
|
|
pointee is valid or not.
|
|
This model does <u>not</u> imply pointer semantics: i.e., it does not imply shallow copy nor
|
|
aliasing.
|
|
<h3>Notation</h3>
|
|
<Table>
|
|
<TR>
|
|
<TD VAlign=top> <tt>T</tt> </TD>
|
|
<TD VAlign=top> is a type that is a model of OptionalPointee</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VAlign=top> <tt>t</tt> </TD>
|
|
<TD VAlign=top> is an object of type <tt>T</tt> or possibly <tt>const T</tt></TD>
|
|
</tr>
|
|
</table>
|
|
<h3>Definitions</h3>
|
|
<h3>Valid expressions</h3>
|
|
<Table border>
|
|
<TR>
|
|
<TH> Name </TH>
|
|
<TH> Expression </TH>
|
|
<TH> Return type </TH>
|
|
<TH> Semantics </TH>
|
|
</TR>
|
|
<TR>
|
|
<TD VAlign=top>Value Access</TD>
|
|
<TD VAlign=top> <tt>*t</tt></TD>
|
|
<TD VAlign=top> <tt>T&</tt></TD>
|
|
<TD VAlign=top>If the pointee is valid returns a reference to
|
|
the pointee.<br>
|
|
If the pointee is invalid the result is <i>undefined</i>.</TD>
|
|
<TD VAlign=top> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VAlign=top>Value Access</TD>
|
|
<TD VAlign=top> <tt>t-><i>xyz</i></tt></TD>
|
|
<TD VAlign=top> <tt>T*</tt></TD>
|
|
<TD VAlign=top>If the pointee is valid returns a builtin pointer to the pointee.<br>
|
|
If the pointee is invalid the result is <i>undefined</i> (It might not even return NULL).<br>
|
|
</TD>
|
|
<TD VAlign=top> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VAlign=top>Validity Test</TD>
|
|
<TD VAlign=top> <tt>t</tt><br>
|
|
<tt>t != 0</tt><br>
|
|
<tt>!!t</tt>
|
|
</TD>
|
|
<TD VAlign=top> bool </TD>
|
|
<TD VAlign=top>If the pointee is valid returns true.<br>
|
|
If the pointee is invalid returns false.</TD>
|
|
<TD VAlign=top></TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VAlign=top>Invalidity Test</TD>
|
|
<TD VAlign=top> <tt>t == 0</tt><br>
|
|
<tt>!t</tt>
|
|
</TD>
|
|
<TD VAlign=top> bool </TD>
|
|
<TD VAlign=top>If the pointee is valid returns false.<br>
|
|
If the pointee is invalid returns true.</TD>
|
|
<TD VAlign=top></TD>
|
|
</TR>
|
|
</table>
|
|
|
|
|
|
<h3>Models</h3>
|
|
|
|
<UL>
|
|
<LI><tt>pointers, both builtin and smart.</tt>
|
|
<LI><tt>boost::optional<></tt>
|
|
</UL>
|
|
|
|
<HR>
|
|
<h3>OptionalPointee and relational operations</h3>
|
|
<p>This concept does not define any particular semantic for relational operations, therefore,
|
|
a type which models this concept might have either shallow or deep relational semantics.<br>
|
|
For instance, pointers, which are models of OptionalPointee, have shallow relational operators:
|
|
comparisons of pointers do not involve comparisons of pointees.
|
|
This makes sense for pointers because they have shallow copy semantics.<br>
|
|
But boost::optional<T>, on the other hand, which is also a model of OptionalPointee, has
|
|
deep-copy and deep-relational semantics.<br>
|
|
If generic code is written for this concept, it is important not to use relational
|
|
operators directly because the semantics might be different depending on the actual type.<br>
|
|
Still, the concept itsef can be used to define <i>deep</i> relational tests that can
|
|
be used in generic code with any type which models OptionalPointee:</p>
|
|
<a name="equal"></a>
|
|
<p><u>Equivalence relation:</u></p>
|
|
<pre>template<class OptionalPointee>
|
|
inline
|
|
bool equal_pointees ( OptionalPointee const& x, OptionalPointee const& y )
|
|
{
|
|
return (!x) != (!y) ? false : ( !x ? true : (*x) == (*y) ) ;
|
|
}
|
|
template<class OptionalPointee>
|
|
struct equal_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool>
|
|
{
|
|
bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
|
|
{ return equal_pointees(x,y) ; }
|
|
} ;
|
|
</pre>
|
|
<p>The preceding generic function and function object have the following semantics:<br>
|
|
If both <b>x</b> and <b>y</b> have valid pointees, it compares values via <code>(*x == *y)</code>.<br>
|
|
If only one has a valid pointee, returns <code>false</code>.<br>
|
|
If both have invalid pointees, returns <code>true</code>.</p>
|
|
<a name="less"></a>
|
|
<p><u>Less-than relation:</u></p>
|
|
<pre>template<class OptionalPointee>
|
|
inline
|
|
bool less_pointees ( OptionalPointee const& x, OptionalPointee const& y )
|
|
{
|
|
return !y ? false : ( !x ? true : (*x) < (*y) ) ;
|
|
}
|
|
template<class OptionalPointee>
|
|
struct less_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool>
|
|
{
|
|
bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
|
|
{ return less_pointees(x,y) ; }
|
|
} ;
|
|
</pre>
|
|
<p>The preceding generic function and function object have the following semantics:<br>
|
|
If <b>y</b> has an invalid pointee, returns <code>false</code>.<br>
|
|
Else, if <b>x</b> has an invalid pointee, returns <code>true</code>.<br>
|
|
Else, ( <b>x</b> and <b>y</b> have valid pointees), compares values via <code>(*x <
|
|
*y).</code></p>
|
|
<p><br>
|
|
All these functions and function
|
|
objects are is implemented in <a href="../../boost/utility/compare_pointees.hpp">compare_pointees.hpp</a></p>
|
|
<p>Notice that OptionalPointee does not imply aliasing (and optional<> for instance does not alias);
|
|
so direct usage of relational operators with the implied aliasing of shallow semantics
|
|
-as with pointers- should not be used with generic code written for this concept.</p>
|
|
|
|
<h3>Acknowledgements</h3>
|
|
<p>Based on the original concept developed by Augustus Saunders.
|
|
|
|
<br>
|
|
</p>
|
|
<HR>
|
|
<TABLE>
|
|
<TR valign=top>
|
|
<TD nowrap>Copyright © 2003</TD><TD>
|
|
<A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>
|
|
</TD></TR></TABLE>
|
|
|
|
<p>Distributed under the Boost Software License, Version 1.0. See
|
|
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
|
|
|
|
</BODY>
|
|
</HTML> |