9
3

OptionalPointee.html 5.9 KB

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