1<HTML> 2<Head> 3<Title>OptionalPointee Concept</Title> 4</HEAD> 5<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 6 ALINK="#ff0000"> 7<IMG SRC="../../boost.png" 8 ALT="C++ Boost" width="277" height="86"> 9<!--end header--> 10<BR Clear> 11<H1>Concept: OptionalPointee</H1> 12 13<h3>Description</h3> 14A type is a model of <i>OptionalPointee</i> if it points to (or refers to) a value 15that may not exist. That is, if it has a <b>pointee</b> which might be <b>valid</b> 16(existent) or <b>invalid</b> (inexistent); and it is possible to test whether the 17pointee is valid or not. 18This model does <u>not</u> imply pointer semantics: i.e., it does not imply shallow copy nor 19aliasing. 20<h3>Notation</h3> 21<Table> 22 <TR> 23 <TD VAlign=top> <tt>T</tt> </TD> 24 <TD VAlign=top> is a type that is a model of OptionalPointee</TD> 25 </TR> 26 <TR> 27 <TD VAlign=top> <tt>t</tt> </TD> 28 <TD VAlign=top> is an object of type <tt>T</tt> or possibly <tt>const T</tt></TD> 29 </tr> 30</table> 31<h3>Definitions</h3> 32<h3>Valid expressions</h3> 33<Table border> 34 <TR> 35 <TH> Name </TH> 36 <TH> Expression </TH> 37 <TH> Return type </TH> 38 <TH> Semantics </TH> 39 </TR> 40 <TR> 41 <TD VAlign=top>Value Access</TD> 42 <TD VAlign=top> <tt>*t</tt></TD> 43 <TD VAlign=top> <tt>T&</tt></TD> 44 <TD VAlign=top>If the pointee is valid returns a reference to 45 the pointee.<br> 46 If the pointee is invalid the result is <i>undefined</i>.</TD> 47 <TD VAlign=top> </TD> 48 </TR> 49 <TR> 50 <TD VAlign=top>Value Access</TD> 51 <TD VAlign=top> <tt>t-><i>xyz</i></tt></TD> 52 <TD VAlign=top> <tt>T*</tt></TD> 53 <TD VAlign=top>If the pointee is valid returns a builtin pointer to the pointee.<br> 54 If the pointee is invalid the result is <i>undefined</i> (It might not even return NULL).<br> 55 </TD> 56 <TD VAlign=top> </TD> 57 </TR> 58 <TR> 59 <TD VAlign=top>Validity Test</TD> 60 <TD VAlign=top> <tt>bool(t)</tt></TD> 61 <TD VAlign=top> bool </TD> 62 <TD VAlign=top>If the pointee is valid returns true.<br> 63 If the pointee is invalid returns false.</TD> 64 <TD VAlign=top></TD> 65 </TR> 66 <TR> 67 <TD VAlign=top>Invalidity Test</TD> 68 <TD VAlign=top> <tt>!t</tt></TD> 69 <TD VAlign=top> bool </TD> 70 <TD VAlign=top>If the pointee is valid returns false.<br> 71 If the pointee is invalid returns true.</TD> 72 <TD VAlign=top></TD> 73 </TR> 74</table> 75 76 77<h3>Models</h3> 78 79<UL> 80 <LI><tt>pointers, both builtin and smart.</tt> 81 <LI><tt>boost::optional<></tt> 82</UL> 83 84<HR> 85<h3>OptionalPointee and relational operations</h3> 86<p>This concept does not define any particular semantic for relational operations, therefore, 87a type which models this concept might have either shallow or deep relational semantics.<br> 88For instance, pointers, which are models of OptionalPointee, have shallow relational operators: 89comparisons of pointers do not involve comparisons of pointees. 90This makes sense for pointers because they have shallow copy semantics.<br> 91But boost::optional<T>, on the other hand, which is also a model of OptionalPointee, has 92deep-copy and deep-relational semantics.<br> 93If generic code is written for this concept, it is important not to use relational 94operators directly because the semantics might be different depending on the actual type.<br> 95Still, the concept itsef can be used to define <i>deep</i> relational tests that can 96be used in generic code with any type which models OptionalPointee:</p> 97<a name="equal"></a> 98<p><u>Equivalence relation:</u></p> 99<pre>template<class OptionalPointee> 100inline 101bool equal_pointees ( OptionalPointee const& x, OptionalPointee const& y ) 102{ 103 return (!x) != (!y) ? false : ( !x ? true : (*x) == (*y) ) ; 104} 105template<class OptionalPointee> 106struct equal_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool> 107{ 108 bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const 109 { return equal_pointees(x,y) ; } 110} ; 111</pre> 112<p>The preceding generic function and function object have the following semantics:<br> 113If both <b>x</b> and <b>y</b> have valid pointees, it compares values via <code>(*x == *y)</code>.<br> 114If only one has a valid pointee, returns <code>false</code>.<br> 115If both have invalid pointees, returns <code>true</code>.</p> 116<a name="less"></a> 117<p><u>Less-than relation:</u></p> 118<pre>template<class OptionalPointee> 119inline 120bool less_pointees ( OptionalPointee const& x, OptionalPointee const& y ) 121{ 122 return !y ? false : ( !x ? true : (*x) < (*y) ) ; 123} 124template<class OptionalPointee> 125struct less_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool> 126{ 127 bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const 128 { return less_pointees(x,y) ; } 129} ; 130</pre> 131<p>The preceding generic function and function object have the following semantics:<br> 132If <b>y</b> has an invalid pointee, returns <code>false</code>.<br> 133Else, if <b>x</b> has an invalid pointee, returns <code>true</code>.<br> 134Else, ( <b>x</b> and <b>y</b> have valid pointees), compares values via <code>(*x < 135*y).</code></p> 136<p><br> 137All these functions and function 138objects are is implemented in <a href="../../boost/utility/compare_pointees.hpp">compare_pointees.hpp</a></p> 139<p>Notice that OptionalPointee does not imply aliasing (and optional<> for instance does not alias); 140so direct usage of relational operators with the implied aliasing of shallow semantics 141-as with pointers- should not be used with generic code written for this concept.</p> 142 143<h3>Acknowledgements</h3> 144<p>Based on the original concept developed by Augustus Saunders. 145 146<br> 147</p> 148<HR> 149<TABLE> 150<TR valign=top> 151<TD nowrap>Copyright © 2003</TD><TD> 152<A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A> 153</TD></TR></TABLE> 154 155<p>Distributed under the Boost Software License, Version 1.0. See 156<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p> 157 158</BODY> 159</HTML> 160
