diff options
Diffstat (limited to 'src/boost/libs/utility/OptionalPointee.html')
| -rw-r--r-- | src/boost/libs/utility/OptionalPointee.html | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/src/boost/libs/utility/OptionalPointee.html b/src/boost/libs/utility/OptionalPointee.html new file mode 100644 index 000000000..c3c7e44eb --- /dev/null +++ b/src/boost/libs/utility/OptionalPointee.html @@ -0,0 +1,159 @@ +<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> |