mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 18:34:02 +00:00
656b5397c5
Some of the HTML docs in the root directory were not converted to QuickBook by 703a4bf752c153ccbf3688c9841295d234a4f085 and were incorrectly removed. These docs are referenced by other libraries' docs, so restoring these pages.
160 lines
5.9 KiB
HTML
160 lines
5.9 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>bool(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</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>
|