Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/utility/OptionalPointee.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 5.8 KB
Line 
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>&nbsp;<tt>*t</tt></TD>
43    <TD VAlign=top>&nbsp;<tt>T&amp;</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>&nbsp;<tt>t-><i>xyz</i></tt></TD>
52    <TD VAlign=top>&nbsp;<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>&nbsp;<tt>t</tt><br>
61     &nbsp;<tt>t != 0</tt><br>
62     &nbsp;<tt>!!t</tt>
63     </TD>
64    <TD VAlign=top>&nbsp;bool </TD>
65    <TD VAlign=top>If the pointee is valid returns true.<br>
66      If the pointee is invalid returns false.</TD>
67    <TD VAlign=top></TD>
68  </TR>
69  <TR>
70    <TD VAlign=top>Invalidity Test</TD>
71    <TD VAlign=top>&nbsp;<tt>t == 0</tt><br>
72                   &nbsp;<tt>!t</tt>
73    </TD>
74    <TD VAlign=top>&nbsp;bool </TD>
75    <TD VAlign=top>If the pointee is valid returns false.<br>
76      If the pointee is invalid returns true.</TD>
77    <TD VAlign=top></TD>
78  </TR>
79</table>
80
81
82<h3>Models</h3>
83
84<UL>
85  <LI><tt>pointers, both builtin and smart.</tt>
86  <LI><tt>boost::optional&lt;&gt;</tt>
87</UL>
88
89<HR>
90<h3>OptionalPointee and relational operations</h3>
91<p>This concept does not define any particular semantic for relational operations, therefore,
92a type which models this concept might have either shallow or deep relational semantics.<br>
93For instance, pointers, which are models of OptionalPointee, have shallow relational operators:
94comparisons of pointers do not involve comparisons of pointees.
95This makes sense for pointers because they have shallow copy semantics.<br>
96But boost::optional&lt;T&gt;, on the other hand, which is also a model of OptionalPointee, has
97deep-copy and deep-relational semantics.<br>
98If generic code is written for this concept, it is important not to use relational
99operators directly because the semantics might be different depending on the actual type.<br>
100Still, the concept itsef can be used to define <i>deep</i> relational tests that can
101be used in generic code with any type which models OptionalPointee:</p>
102<a name="equal"></a>
103<p><u>Equivalence relation:</u></p>
104<pre>template&lt;class OptionalPointee&gt;
105inline
106bool equal_pointees ( OptionalPointee const&amp; x, OptionalPointee const&amp; y )
107{
108  return (!x) != (!y) ? false : ( !x ? true : (*x) == (*y) ) ;
109}
110template&lt;class OptionalPointee&gt;
111struct equal_pointees_t : std::binary_function&lt;OptionalPointee,OptionalPointee,bool&gt;
112{
113  bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
114    { return equal_pointees(x,y) ; }
115} ;
116</pre>
117<p>The preceding generic function and function object have the following semantics:<br>
118If both <b>x</b> and <b>y</b> have valid pointees, it compares values via <code>(*x == *y)</code>.<br>
119If only one has a valid pointee, returns <code>false</code>.<br>
120If both have invalid pointees, returns <code>true</code>.</p>
121<a name="less"></a>
122<p><u>Less-than relation:</u></p>
123<pre>template&lt;class OptionalPointee&gt;
124inline
125bool less_pointees ( OptionalPointee const&amp; x, OptionalPointee const&amp; y )
126{
127  return !y ? false : ( !x ? true : (*x) < (*y) ) ;
128}
129template&lt;class OptionalPointee&gt;
130struct less_pointees_t : std::binary_function&lt;OptionalPointee,OptionalPointee,bool&gt;
131{
132  bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
133    { return less_pointees(x,y) ; }
134} ;
135</pre>
136<p>The preceding generic function and function object have the following semantics:<br>
137If <b>y</b> has an invalid pointee, returns <code>false</code>.<br>
138Else, if <b>x</b> has an invalid pointee, returns <code>true</code>.<br>
139Else, ( <b>x</b> and <b>y</b> have valid pointees), compares values via <code>(*x &lt; 
140*y).</code></p>
141<p><br>
142All these functions and function
143objects are is implemented in <a href="../../boost/utility/compare_pointees.hpp">compare_pointees.hpp</a></p>
144<p>Notice that OptionalPointee does not imply aliasing (and optional&lt;&gt; for instance does not alias);
145so direct usage of relational operators with the implied aliasing of shallow semantics
146-as with pointers- should not be used with generic code written for this concept.</p>
147
148<br>
149<HR>
150<TABLE>
151<TR valign=top>
152<TD nowrap>Copyright &copy 2003</TD><TD>
153<A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>,
154based on the original concept developed by Augustus Saunders.
155</TD></TR></TABLE>
156
157</BODY>
158</HTML>
Note: See TracBrowser for help on using the repository browser.