mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 15:04:00 +00:00
Restored docs removed by 703a4bf752c153ccbf3688c9841295d234a4f085.
Some of the HTML docs in the root directory were not converted to QuickBook by 703a4bf752c153ccbf3688c9841295d234a4f085 and were incorrectly removed. These docs are referenced by other libraries' docs, so restoring these pages.
This commit is contained in:
Andrey Semashev
parent
65b40cbf99
commit
656b5397c5
116
Assignable.html
116
Assignable.html
@ -1,19 +1,109 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
||||
|
||||
<title>Assignable</title>
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
|
||||
<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
|
||||
"#FF0000">
|
||||
<img src="../../boost.png" alt="C++ Boost" width="277" height=
|
||||
"86"><br clear="none">
|
||||
|
||||
<h1>Assignable</h1>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>A type is Assignable if it is possible to assign one object of the type
|
||||
to another object of that type.</p>
|
||||
|
||||
<h3>Notation</h3>
|
||||
|
||||
<table summary="">
|
||||
<tr>
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top">is type that is a model of Assignable</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>t</tt></td>
|
||||
|
||||
<td valign="top">is an object of type <tt>T</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>u</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 summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Assignment</td>
|
||||
|
||||
<td valign="top"><tt>t = u</tt></td>
|
||||
|
||||
<td valign="top"><tt>T&</tt></td>
|
||||
|
||||
<td valign="top"><tt>t</tt> is equivalent to <tt>u</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Models</h3>
|
||||
|
||||
<ul>
|
||||
<li><tt>int</tt></li>
|
||||
|
||||
<li><tt>std::pair</tt></li>
|
||||
</ul>
|
||||
|
||||
<h3>See also</h3>
|
||||
|
||||
<p><a href=
|
||||
"http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>
|
||||
and <a href="./CopyConstructible.html">CopyConstructible</a><br></p>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<br>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
|
||||
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
||||
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
||||
height="31" width="88"></a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
|
||||
|
||||
<table summary="">
|
||||
<tr valign="top">
|
||||
<td nowrap><i>Copyright © 2000</i></td>
|
||||
|
||||
<td><i><a href="http://www.lsc.nd.edu/~jsiek">Jeremy Siek</a>, Univ.of
|
||||
Notre Dame (<a href=
|
||||
"mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</a>)</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
||||
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
||||
copy at <a href=
|
||||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
541
Collection.html
541
Collection.html
@ -1,19 +1,534 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
||||
|
||||
<title>Collection</title>
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
|
||||
<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
|
||||
"#FF0000">
|
||||
<h1><img src="../../boost.png" alt="boost logo" width="277" align="middle"
|
||||
height="86"><br>
|
||||
Collection</h1>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>A Collection is a <i>concept</i> similar to the STL <a href=
|
||||
"http://www.sgi.com/tech/stl/Container.html">Container</a> concept. A
|
||||
Collection provides iterators for accessing a range of elements and
|
||||
provides information about the number of elements in the Collection.
|
||||
However, a Collection has fewer requirements than a Container. The
|
||||
motivation for the Collection concept is that there are many useful
|
||||
Container-like types that do not meet the full requirements of Container,
|
||||
and many algorithms that can be written with this reduced set of
|
||||
requirements. To summarize the reduction in requirements:</p>
|
||||
|
||||
<ul>
|
||||
<li>It is not required to "own" its elements: the lifetime of an element
|
||||
in a Collection does not have to match the lifetime of the Collection
|
||||
object, though the lifetime of the element should cover the lifetime of
|
||||
the Collection object.</li>
|
||||
|
||||
<li>The semantics of copying a Collection object is not defined (it could
|
||||
be a deep or shallow copy or not even support copying).</li>
|
||||
|
||||
<li>The associated reference type of a Collection does not have to be a
|
||||
real C++ reference.</li>
|
||||
</ul>Because of the reduced requirements, some care must be taken when
|
||||
writing code that is meant to be generic for all Collection types. In
|
||||
particular, a Collection object should be passed by-reference since
|
||||
assumptions can not be made about the behaviour of the copy constructor.
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<td valign="top">Value type</td>
|
||||
|
||||
<td valign="top"><tt>X::value_type</tt></td>
|
||||
|
||||
<td valign="top">The type of the object stored in a Collection. If the
|
||||
Collection is <i>mutable</i> then the value type must be <a href=
|
||||
"http://www.sgi.com/tech/stl/Assignable.html">Assignable</a>. Otherwise
|
||||
the value type must be <a href=
|
||||
"./CopyConstructible.html">CopyConstructible</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Iterator type</td>
|
||||
|
||||
<td valign="top"><tt>X::iterator</tt></td>
|
||||
|
||||
<td valign="top">The type of iterator used to iterate through a
|
||||
Collection's elements. The iterator's value type is expected to be the
|
||||
Collection's value type. A conversion from the iterator type to the
|
||||
const iterator type must exist. The iterator type must be an <a href=
|
||||
"http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Const iterator type</td>
|
||||
|
||||
<td valign="top"><tt>X::const_iterator</tt></td>
|
||||
|
||||
<td valign="top">A type of iterator that may be used to examine, but
|
||||
not to modify, a Collection's elements.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Reference type</td>
|
||||
|
||||
<td valign="top"><tt>X::reference</tt></td>
|
||||
|
||||
<td valign="top">A type that behaves like a reference to the
|
||||
Collection's value type. <a href="#n1">[1]</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Const reference type</td>
|
||||
|
||||
<td valign="top"><tt>X::const_reference</tt></td>
|
||||
|
||||
<td valign="top">A type that behaves like a const reference to the
|
||||
Collection's value type.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Pointer type</td>
|
||||
|
||||
<td valign="top"><tt>X::pointer</tt></td>
|
||||
|
||||
<td valign="top">A type that behaves as a pointer to the Collection's
|
||||
value type.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Distance type</td>
|
||||
|
||||
<td valign="top"><tt>X::difference_type</tt></td>
|
||||
|
||||
<td valign="top">A signed integral type used to represent the distance
|
||||
between two of the Collection's iterators. This type must be the same
|
||||
as the iterator's distance type.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Size type</td>
|
||||
|
||||
<td valign="top"><tt>X::size_type</tt></td>
|
||||
|
||||
<td valign="top">An unsigned integral type that can represent any
|
||||
nonnegative value of the Collection's distance type.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Notation</h3>
|
||||
|
||||
<table summary="">
|
||||
<tr>
|
||||
<td valign="top"><tt>X</tt></td>
|
||||
|
||||
<td valign="top">A type that is a model of Collection.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>a</tt>, <tt>b</tt></td>
|
||||
|
||||
<td valign="top">Object of type <tt>X</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top">The value type of <tt>X</tt>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Valid expressions</h3>
|
||||
|
||||
<p>The following expressions must be valid.</p>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Beginning of range</td>
|
||||
|
||||
<td valign="top"><tt>a.begin()</tt></td>
|
||||
|
||||
<td valign="top"><tt>iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_iterator</tt> otherwise</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">End of range</td>
|
||||
|
||||
<td valign="top"><tt>a.end()</tt></td>
|
||||
|
||||
<td valign="top"><tt>iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_iterator</tt> otherwise</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Size</td>
|
||||
|
||||
<td valign="top"><tt>a.size()</tt></td>
|
||||
|
||||
<td valign="top"><tt>size_type</tt></td>
|
||||
</tr><!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>size_type</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
-->
|
||||
|
||||
<tr>
|
||||
<td valign="top">Empty Collection</td>
|
||||
|
||||
<td valign="top"><tt>a.empty()</tt></td>
|
||||
|
||||
<td valign="top">Convertible to <tt>bool</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Swap</td>
|
||||
|
||||
<td valign="top"><tt>a.swap(b)</tt></td>
|
||||
|
||||
<td valign="top"><tt>void</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Expression semantics</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
|
||||
<th>Postcondition</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Beginning of range</td>
|
||||
|
||||
<td valign="top"><tt>a.begin()</tt></td>
|
||||
|
||||
<td valign="top">Returns an iterator pointing to the first element in
|
||||
the Collection.</td>
|
||||
|
||||
<td valign="top"><tt>a.begin()</tt> is either dereferenceable or
|
||||
past-the-end. It is past-the-end if and only if <tt>a.size() ==
|
||||
0</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">End of range</td>
|
||||
|
||||
<td valign="top"><tt>a.end()</tt></td>
|
||||
|
||||
<td valign="top">Returns an iterator pointing one past the last element
|
||||
in the Collection.</td>
|
||||
|
||||
<td valign="top"><tt>a.end()</tt> is past-the-end.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Size</td>
|
||||
|
||||
<td valign="top"><tt>a.size()</tt></td>
|
||||
|
||||
<td valign="top">Returns the size of the Collection, that is, its
|
||||
number of elements.</td>
|
||||
|
||||
<td valign="top"><tt>a.size() >= 0</tt></td>
|
||||
</tr><!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the largest size that this Collection can ever have. <A href="#8">[8]</A>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size() >= 0 && a.max_size() >= a.size()</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
-->
|
||||
|
||||
<tr>
|
||||
<td valign="top">Empty Collection</td>
|
||||
|
||||
<td valign="top"><tt>a.empty()</tt></td>
|
||||
|
||||
<td valign="top">Equivalent to <tt>a.size() == 0</tt>. (But possibly
|
||||
faster.)</td>
|
||||
|
||||
<td valign="top"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Swap</td>
|
||||
|
||||
<td valign="top"><tt>a.swap(b)</tt></td>
|
||||
|
||||
<td valign="top">Equivalent to <tt>swap(a,b)</tt></td>
|
||||
|
||||
<td valign="top"> </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Complexity guarantees</h3>
|
||||
|
||||
<p><tt>begin()</tt> and <tt>end()</tt> are amortized constant time.</p>
|
||||
|
||||
<p><tt>size()</tt> is at most linear in the Collection's size.
|
||||
<tt>empty()</tt> is amortized constant time.</p>
|
||||
|
||||
<p><tt>swap()</tt> is at most linear in the size of the two
|
||||
collections.</p>
|
||||
|
||||
<h3>Invariants</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<td valign="top">Valid range</td>
|
||||
|
||||
<td valign="top">For any Collection <tt>a</tt>, <tt>[a.begin(),
|
||||
a.end())</tt> is a valid range.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Range size</td>
|
||||
|
||||
<td valign="top"><tt>a.size()</tt> is equal to the distance from
|
||||
<tt>a.begin()</tt> to <tt>a.end()</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Completeness</td>
|
||||
|
||||
<td valign="top">An algorithm that iterates through the range
|
||||
<tt>[a.begin(), a.end())</tt> will pass through every element of
|
||||
<tt>a</tt>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Models</h3>
|
||||
|
||||
<ul>
|
||||
<li><tt>array</tt></li>
|
||||
|
||||
<li><tt>array_ptr</tt></li>
|
||||
|
||||
<li><tt>vector<bool></tt></li>
|
||||
</ul>
|
||||
|
||||
<h3>Collection Refinements</h3>
|
||||
|
||||
<p>There are quite a few concepts that refine the Collection concept,
|
||||
similar to the concepts that refine the Container concept. Here is a brief
|
||||
overview of the refining concepts.</p>
|
||||
|
||||
<h4>ForwardCollection</h4>
|
||||
|
||||
<p>The elements are arranged in some order that does not change
|
||||
spontaneously from one iteration to the next. As a result, a
|
||||
ForwardCollection is <a href=
|
||||
"http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a>
|
||||
and <a href=
|
||||
"http://www.sgi.com/tech/stl/LessThanComparable.html">LessThanComparable</a>.
|
||||
In addition, the iterator type of a ForwardCollection is a
|
||||
MultiPassInputIterator which is just an InputIterator with the added
|
||||
requirements that the iterator can be used to make multiple passes through
|
||||
a range, and that if <tt>it1 == it2</tt> and <tt>it1</tt> is
|
||||
dereferenceable then <tt>++it1 == ++it2</tt>. The ForwardCollection also
|
||||
has a <tt>front()</tt> method.</p>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Front</td>
|
||||
|
||||
<td valign="top"><tt>a.front()</tt></td>
|
||||
|
||||
<td valign="top"><tt>reference</tt> if <tt>a</tt> is mutable,<br>
|
||||
<tt>const_reference</tt> otherwise.</td>
|
||||
|
||||
<td valign="top">Equivalent to <tt>*(a.begin())</tt>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>ReversibleCollection</h4>
|
||||
|
||||
<p>The container provides access to iterators that traverse in both
|
||||
directions (forward and reverse). The iterator type must meet all of the
|
||||
requirements of <a href=
|
||||
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>
|
||||
except that the reference type does not have to be a real C++ reference.
|
||||
The ReversibleCollection adds the following requirements to those of
|
||||
ForwardCollection.</p>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Beginning of range</td>
|
||||
|
||||
<td valign="top"><tt>a.rbegin()</tt></td>
|
||||
|
||||
<td valign="top"><tt>reverse_iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reverse_iterator</tt> otherwise.</td>
|
||||
|
||||
<td valign="top">Equivalent to
|
||||
<tt>X::reverse_iterator(a.end())</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">End of range</td>
|
||||
|
||||
<td valign="top"><tt>a.rend()</tt></td>
|
||||
|
||||
<td valign="top"><tt>reverse_iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reverse_iterator</tt> otherwise.</td>
|
||||
|
||||
<td valign="top">Equivalent to
|
||||
<tt>X::reverse_iterator(a.begin())</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Back</td>
|
||||
|
||||
<td valign="top"><tt>a.back()</tt></td>
|
||||
|
||||
<td valign="top"><tt>reference</tt> if <tt>a</tt> is mutable,<br>
|
||||
<tt>const_reference</tt> otherwise.</td>
|
||||
|
||||
<td valign="top">Equivalent to <tt>*(--a.end())</tt>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>SequentialCollection</h4>
|
||||
|
||||
<p>The elements are arranged in a strict linear order. No extra methods are
|
||||
required.</p>
|
||||
|
||||
<h4>RandomAccessCollection</h4>
|
||||
|
||||
<p>The iterators of a RandomAccessCollection satisfy all of the
|
||||
requirements of <a href=
|
||||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">RandomAccessIterator</a>
|
||||
except that the reference type does not have to be a real C++ reference. In
|
||||
addition, a RandomAccessCollection provides an element access operator.</p>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Element Access</td>
|
||||
|
||||
<td valign="top"><tt>a[n]</tt></td>
|
||||
|
||||
<td valign="top"><tt>reference</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reference</tt> otherwise.</td>
|
||||
|
||||
<td valign="top">Returns the nth element of the Collection. <tt>n</tt>
|
||||
must be convertible to <tt>size_type</tt>. Precondition: <tt>0 <= n
|
||||
< a.size()</tt>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Notes</h3>
|
||||
|
||||
<p><a name="n1" id="n1">[1]</a> The reference type does not have to be a
|
||||
real C++ reference. The requirements of the reference type depend on the
|
||||
context within which the Collection is being used. Specifically it depends
|
||||
on the requirements the context places on the value type of the Collection.
|
||||
The reference type of the Collection must meet the same requirements as the
|
||||
value type. In addition, the reference objects must be equivalent to the
|
||||
value type objects in the collection (which is trivially true if they are
|
||||
the same object). Also, in a mutable Collection, an assignment to the
|
||||
reference object must result in an assignment to the object in the
|
||||
Collection (again, which is trivially true if they are the same object, but
|
||||
non-trivial if the reference type is a proxy class).</p>
|
||||
|
||||
<h3>See also</h3>
|
||||
|
||||
<p><a href=
|
||||
"http://www.sgi.com/tech/stl/Container.html">Container</a><br></p>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<br>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
|
||||
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
||||
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
||||
height="31" width="88"></a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
|
||||
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
|
||||
|
||||
<table summary="">
|
||||
<tr valign="top">
|
||||
<td nowrap><i>Copyright © 2000</i></td>
|
||||
|
||||
<td><i><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy
|
||||
Siek</a>, Univ.of Notre Dame and C++ Library & Compiler Group/SGI
|
||||
(<a href="mailto:jsiek@engr.sgi.com">jsiek@engr.sgi.com</a>)</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
||||
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
||||
copy at <a href=
|
||||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,19 +1,185 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
||||
|
||||
<title>Copy Constructible</title>
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
|
||||
<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
|
||||
"#FF0000">
|
||||
<img src="../../boost.png" alt="C++ Boost" width="277" height=
|
||||
"86"><br clear="none">
|
||||
|
||||
<h1>Copy Constructible</h1>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>A type is Copy Constructible if it is possible to copy objects of that
|
||||
type.</p>
|
||||
|
||||
<h3>Notation</h3>
|
||||
|
||||
<table summary="">
|
||||
<tr>
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top">is type that is a model of Copy Constructible</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>t</tt></td>
|
||||
|
||||
<td valign="top">is an object of type <tt>T</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>u</tt></td>
|
||||
|
||||
<td valign="top">is an object of type <tt>const T</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Definitions</h3>
|
||||
|
||||
<h3>Valid expressions</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Return type</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Copy constructor</td>
|
||||
|
||||
<td valign="top"><tt>T(t)</tt></td>
|
||||
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top"><tt>t</tt> is equivalent to <tt>T(t)</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Copy constructor</td>
|
||||
|
||||
<td valign="top">
|
||||
<pre>
|
||||
T(u)
|
||||
</pre>
|
||||
</td>
|
||||
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top"><tt>u</tt> is equivalent to <tt>T(u)</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Destructor</td>
|
||||
|
||||
<td valign="top">
|
||||
<pre>
|
||||
t.~T()
|
||||
</pre>
|
||||
</td>
|
||||
|
||||
<td valign="top"><tt>T</tt></td>
|
||||
|
||||
<td valign="top"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Address Operator</td>
|
||||
|
||||
<td valign="top">
|
||||
<pre>
|
||||
&t
|
||||
</pre>
|
||||
</td>
|
||||
|
||||
<td valign="top"><tt>T*</tt></td>
|
||||
|
||||
<td valign="top">denotes the address of <tt>t</tt></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Address Operator</td>
|
||||
|
||||
<td valign="top">
|
||||
<pre>
|
||||
&u
|
||||
</pre>
|
||||
</td>
|
||||
|
||||
<td valign="top"><tt>T*</tt></td>
|
||||
|
||||
<td valign="top">denotes the address of <tt>u</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Models</h3>
|
||||
|
||||
<ul>
|
||||
<li><tt>int</tt></li>
|
||||
|
||||
<li><tt>std::pair</tt></li>
|
||||
</ul>
|
||||
|
||||
<h3>Concept Checking Class</h3>
|
||||
<pre>
|
||||
template <class T>
|
||||
struct CopyConstructibleConcept
|
||||
{
|
||||
void constraints() {
|
||||
T a(b); // require copy constructor
|
||||
T* ptr = &a; // require address of operator
|
||||
const_constraints(a);
|
||||
ignore_unused_variable_warning(ptr);
|
||||
}
|
||||
void const_constraints(const T& a) {
|
||||
T c(a); // require const copy constructor
|
||||
const T* ptr = &a; // require const address of operator
|
||||
ignore_unused_variable_warning(c);
|
||||
ignore_unused_variable_warning(ptr);
|
||||
}
|
||||
T b;
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h3>See also</h3>
|
||||
|
||||
<p><a href="http://www.sgi.com/tech/stl/DefaultConstructible.html">Default
|
||||
Constructible</a> and <a href="./Assignable.html">Assignable</a><br></p>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<br>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
|
||||
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
||||
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
||||
height="31" width="88"></a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
|
||||
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
|
||||
|
||||
<table summary="">
|
||||
<tr valign="top">
|
||||
<td nowrap><i>Copyright © 2000</i></td>
|
||||
|
||||
<td><i><a href="http://www.lsc.nd.edu/~jsiek">Jeremy Siek</a>, Univ.of
|
||||
Notre Dame (<a href=
|
||||
"mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</a>)</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
||||
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
||||
copy at <a href=
|
||||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,19 +1,210 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<!--
|
||||
== Copyright (c) 1996-1999
|
||||
== Silicon Graphics Computer Systems, Inc.
|
||||
==
|
||||
== Permission to use, copy, modify, distribute and sell this software
|
||||
== and its documentation for any purpose is hereby granted without fee,
|
||||
== provided that the above copyright notice appears in all copies and
|
||||
== that both that copyright notice and this permission notice appear
|
||||
== in supporting documentation. Silicon Graphics makes no
|
||||
== representations about the suitability of this software for any
|
||||
== purpose. It is provided "as is" without express or implied warranty.
|
||||
==
|
||||
== Copyright (c) 1994
|
||||
== Hewlett-Packard Company
|
||||
==
|
||||
== Permission to use, copy, modify, distribute and sell this software
|
||||
== and its documentation for any purpose is hereby granted without fee,
|
||||
== provided that the above copyright notice appears in all copies and
|
||||
== that both that copyright notice and this permission notice appear
|
||||
== in supporting documentation. Hewlett-Packard Company makes no
|
||||
== representations about the suitability of this software for any
|
||||
== purpose. It is provided "as is" without express or implied warranty.
|
||||
==
|
||||
-->
|
||||
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
||||
|
||||
<title>LessThanComparable</title>
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
|
||||
<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
|
||||
"#FF0000">
|
||||
<img src="../../boost.png" alt="C++ Boost" width="277" height=
|
||||
"86"><br clear="none">
|
||||
|
||||
<h1>LessThanComparable</h1>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>A type is LessThanComparable if it is ordered: it must be possible to
|
||||
compare two objects of that type using <tt>operator<</tt>, and
|
||||
<tt>operator<</tt> must be a strict weak ordering relation.</p>
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<h3>Notation</h3>
|
||||
|
||||
<table summary="">
|
||||
<tr>
|
||||
<td valign="top"><tt>X</tt></td>
|
||||
|
||||
<td valign="top">A type that is a model of LessThanComparable</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt>x</tt>, <tt>y</tt>, <tt>z</tt></td>
|
||||
|
||||
<td valign="top">Object of type <tt>X</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Definitions</h3>
|
||||
|
||||
<p>Consider the relation <tt>!(x < y) && !(y < x)</tt>. If
|
||||
this relation is transitive (that is, if <tt>!(x < y) && !(y
|
||||
< x) && !(y < z) && !(z < y)</tt> implies <tt>!(x
|
||||
< z) && !(z < x)</tt>), then it satisfies the mathematical
|
||||
definition of an equivalence relation. In this case, <tt>operator<</tt>
|
||||
is a <i>strict weak ordering</i>.</p>
|
||||
|
||||
<p>If <tt>operator<</tt> is a strict weak ordering, and if each
|
||||
equivalence class has only a single element, then <tt>operator<</tt> is
|
||||
a <i>total ordering</i>.</p>
|
||||
|
||||
<h3>Valid expressions</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Type requirements</th>
|
||||
|
||||
<th>Return type</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Less</td>
|
||||
|
||||
<td valign="top"><tt>x < y</tt></td>
|
||||
|
||||
<td valign="top"> </td>
|
||||
|
||||
<td valign="top">Convertible to <tt>bool</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Expression semantics</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
|
||||
<th>Expression</th>
|
||||
|
||||
<th>Precondition</th>
|
||||
|
||||
<th>Semantics</th>
|
||||
|
||||
<th>Postcondition</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Less</td>
|
||||
|
||||
<td valign="top"><tt>x < y</tt></td>
|
||||
|
||||
<td valign="top"><tt>x</tt> and <tt>y</tt> are in the domain of
|
||||
<tt><</tt></td>
|
||||
|
||||
<td valign="top"> </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Complexity guarantees</h3>
|
||||
|
||||
<h3>Invariants</h3>
|
||||
|
||||
<table border summary="">
|
||||
<tr>
|
||||
<td valign="top">Irreflexivity</td>
|
||||
|
||||
<td valign="top"><tt>x < x</tt> must be false.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Antisymmetry</td>
|
||||
|
||||
<td valign="top"><tt>x < y</tt> implies !(y < x) <a href=
|
||||
"#n2">[2]</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top">Transitivity</td>
|
||||
|
||||
<td valign="top"><tt>x < y</tt> and <tt>y < z</tt> implies <tt>x
|
||||
< z</tt> <a href="#n3">[3]</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Models</h3>
|
||||
|
||||
<ul>
|
||||
<li>int</li>
|
||||
</ul>
|
||||
|
||||
<h3>Notes</h3>
|
||||
|
||||
<p><a name="n1" id="n1">[1]</a> Only <tt>operator<</tt> is fundamental;
|
||||
the other inequality operators are essentially syntactic sugar.</p>
|
||||
|
||||
<p><a name="n2" id="n2">[2]</a> Antisymmetry is a theorem, not an axiom: it
|
||||
follows from irreflexivity and transitivity.</p>
|
||||
|
||||
<p><a name="n3" id="n3">[3]</a> Because of irreflexivity and transitivity,
|
||||
<tt>operator<</tt> always satisfies the definition of a <i>partial
|
||||
ordering</i>. The definition of a <i>strict weak ordering</i> is stricter,
|
||||
and the definition of a <i>total ordering</i> is stricter still.</p>
|
||||
|
||||
<h3>See also</h3>
|
||||
|
||||
<p><a href=
|
||||
"http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a>,
|
||||
<a href=
|
||||
"http://www.sgi.com/tech/stl/StrictWeakOrdering.html">StrictWeakOrdering</a><br>
|
||||
</p>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<br>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
|
||||
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
||||
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
||||
height="31" width="88"></a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
|
||||
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
|
||||
|
||||
<table summary="">
|
||||
<tr valign="top">
|
||||
<td nowrap><i>Copyright © 2000</i></td>
|
||||
|
||||
<td><i><a href="http://www.lsc.nd.edu/~jsiek">Jeremy Siek</a>, Univ.of
|
||||
Notre Dame (<a href=
|
||||
"mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</a>)</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
||||
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
||||
copy at <a href=
|
||||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,19 +1,95 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
||||
|
||||
<title>MultiPassInputIterator</title>
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
|
||||
<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
|
||||
"#FF0000">
|
||||
<img src="../../boost.png" alt="C++ Boost" width="277" height=
|
||||
"86"><br clear="none">
|
||||
|
||||
<h2><a name="concept:MultiPassInputIterator" id=
|
||||
"concept:MultiPassInputIterator"></a> Multi-Pass Input Iterator</h2>
|
||||
|
||||
<p>This concept is a refinement of <a href=
|
||||
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>, adding
|
||||
the requirements that the iterator can be used to make multiple passes
|
||||
through a range, and that if <tt>it1 == it2</tt> and <tt>it1</tt> is
|
||||
dereferenceable then <tt>++it1 == ++it2</tt>. The Multi-Pass Input Iterator
|
||||
is very similar to the <a href=
|
||||
"http://www.sgi.com/tech/stl/ForwardIterator.html">Forward Iterator</a>.
|
||||
The only difference is that a <a href=
|
||||
"http://www.sgi.com/tech/stl/ForwardIterator.html">Forward Iterator</a>
|
||||
requires the <tt>reference</tt> type to be <tt>value_type&</tt>,
|
||||
whereas MultiPassInputIterator is like <a href=
|
||||
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a> in that
|
||||
the <tt>reference</tt> type merely has to be convertible to
|
||||
<tt>value_type</tt>.</p>
|
||||
|
||||
<h3>Design Notes</h3>
|
||||
|
||||
<p>comments by Valentin Bonnard:</p>
|
||||
|
||||
<p>I think that introducing Multi-Pass Input Iterator isn't the right
|
||||
solution. Do you also want to define Multi-Pass Bidirectionnal Iterator and
|
||||
Multi-Pass Random Access Iterator ? I don't, definitly. It only confuses
|
||||
the issue. The problem lies into the existing hierarchy of iterators, which
|
||||
mixes movabillity, modifiabillity and lvalue-ness, and these are clearly
|
||||
independant.</p>
|
||||
|
||||
<p>The terms Forward, Bidirectionnal and Random Access are about
|
||||
movabillity and shouldn't be used to mean anything else. In a completly
|
||||
orthogonal way, iterators can be immutable, mutable, or neither. Lvalueness
|
||||
of iterators is also orthogonal with immutabillity. With these clean
|
||||
concepts, your Multi-Pass Input Iterator is just called a Forward
|
||||
Iterator.</p>
|
||||
|
||||
<p>Other translations are:<br>
|
||||
std::Forward Iterator -> ForwardIterator & Lvalue Iterator<br>
|
||||
std::Bidirectionnal Iterator -> Bidirectionnal Iterator & Lvalue
|
||||
Iterator<br>
|
||||
std::Random Access Iterator -> Random Access Iterator & Lvalue
|
||||
Iterator<br></p>
|
||||
|
||||
<p>Note that in practice the only operation not allowed on my Forward
|
||||
Iterator which is allowed on std::Forward Iterator is <tt>&*it</tt>. I
|
||||
think that <tt>&*</tt> is rarely needed in generic code.</p>
|
||||
|
||||
<p>reply by Jeremy Siek:</p>
|
||||
|
||||
<p>The above analysis by Valentin is right on. Of course, there is the
|
||||
problem with backward compatibility. The current STL implementations are
|
||||
based on the old definition of Forward Iterator. The right course of action
|
||||
is to get Forward Iterator, etc. changed in the C++ standard. Once that is
|
||||
done we can drop Multi-Pass Input Iterator.<br></p>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<br>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
|
||||
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
|
||||
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
|
||||
height="31" width="88"></a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
|
||||
December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
|
||||
|
||||
<table summary="">
|
||||
<tr valign="top">
|
||||
<td nowrap><i>Copyright © 2000</i></td>
|
||||
|
||||
<td><i><a href="http://www.lsc.nd.edu/~jsiek">Jeremy Siek</a>, Univ.of
|
||||
Notre Dame (<a href=
|
||||
"mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</a>)</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
||||
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
||||
copy at <a href=
|
||||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,19 +1,159 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Boost.Utility</title>
|
||||
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
|
||||
</head>
|
||||
<body>
|
||||
Automatic redirection failed, please go to
|
||||
<a href="./doc/html/index.html">./doc/html/index.html</a>
|
||||
<hr>
|
||||
<tt>
|
||||
Boost.Utility<br>
|
||||
<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>
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
|
||||
<br>
|
||||
</tt>
|
||||
</body>
|
||||
</html>
|
||||
</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>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user