Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / a57b70145cb0a950c1c3a9a4fddf0438c60126f2 / . / third_party / boostorg / utility / OptionalPointee.html
blob: c3c7e44eb6a5a5a43cd160f7a639413bde60de27 [file] [log] [blame]
Brian Silverman60e3e2a2018-08-04 23:57:12 -0700[diff] [blame]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>bool(t)</tt></TD>
61 <TD VAlign=top>&nbsp;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>&nbsp;<tt>!t</tt></TD>
69 <TD VAlign=top>&nbsp;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&lt;&gt;</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&lt;T&gt;, 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&lt;class OptionalPointee&gt;
100inline
101bool equal_pointees ( OptionalPointee const&amp; x, OptionalPointee const&amp; y )
102{
103 return (!x) != (!y) ? false : ( !x ? true : (*x) == (*y) ) ;
104}
105template&lt;class OptionalPointee&gt;
106struct equal_pointees_t : std::binary_function&lt;OptionalPointee,OptionalPointee,bool&gt;
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&lt;class OptionalPointee&gt;
119inline
120bool less_pointees ( OptionalPointee const&amp; x, OptionalPointee const&amp; y )
121{
122 return !y ? false : ( !x ? true : (*x) < (*y) ) ;
123}
124template&lt;class OptionalPointee&gt;
125struct less_pointees_t : std::binary_function&lt;OptionalPointee,OptionalPointee,bool&gt;
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 &lt;
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&lt;&gt; 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 &copy 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>