forked from boostorg/range
*** empty log message ***
[SVN r23241]
This commit is contained in:
1 parent
6a455033ee
commit
ee8211dc0f
15 files changed
+1728
No files matched your search
@@ -0,0 +1,168 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title> Collection Traits </title><meta http-equiv="Content-Type"content="text/html; charset=iso-8859-1"></head> <body><table ><tr ><td ><img src="cboost.gif" width="100%" border="0"></td><td ><h1 ><br> Collection Traits </h1></td></tr></table><ul ><li ><a href="#Introduction" >Introduction</a></li><li ><a href="#Reference" >Reference</a></li><ul ><li ><a href="#Synopsis" >Synopsis</a></li><li ><a href="#Library headers" >Library headers</a></li><li ><a href="#Semantics" >Semantics</a></li></ul><li ><a href="#Examples" >Examples</a></li><li ><a href="#Portability" >Portability</a></li><li ><a href="#FAQ" >FAQ</a></li><li ><a href="#History" >History</a></li></ul><hr size="1" ><h2 >Introduction</h2><a name="Introduction" ></a><p >This library makes it possible to treat different types as if they have
|
||||
implemented a subset of the container requirements
|
||||
(see §23.1of the C++ standard). Formally, that subset is defined by
|
||||
the <a href="Collection.htm" target="_self" >CollectionConcept.</a>
|
||||
The subset deals mostly with
|
||||
iterator returning functions and nested <code >typedef</code>s.
|
||||
The main goal is to treat built-in arrays, standard containers,
|
||||
pairs of iterators and some iterators uniformly. Formally, this library is an implementation
|
||||
of the <a href="#ExternalCollectionConcept" >ExternalCollectionConcept</a> (see also this explanation of <a href="external_concepts.html" target="_self" >External Concepts</a> ).</p><p >The main advantages are <ul ><li >safe use of built-in arrays</li><li >simpler implementation of generic container algorithms</li><li >more flexible client code</li><li >correct handling of null-terminated strings</li></ul></p><p >Below are given a small example (the complete example can be found <a href="../test/algorithm_example.cpp" target="_self" >here</a> ):<pre >
|
||||
//
|
||||
// Example: extracting bounds in generic algorithms
|
||||
//
|
||||
|
||||
template< typename ExternalCollection, typename T >
|
||||
inline typename boost::iterator_of<ExternalCollection>::type
|
||||
find( ExternalCollection& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
|
||||
template< typename ExternalCollection, typename T >
|
||||
inline typename boost::const_iterator_of<ExternalCollection>::type
|
||||
find( const ExternalCollection& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
|
||||
//
|
||||
// replace first value and return its index
|
||||
//
|
||||
template< typename EC, typename T >
|
||||
inline typename boost::size_type_of< EC >::type
|
||||
my_generic_replace( EC& c, const T& value, const T& replacement )
|
||||
{
|
||||
typename boost::const_iterator_of<EC>::type found = find( c, value );
|
||||
*found = replacement;
|
||||
return std::distance( boost::begin( c ), found );
|
||||
}
|
||||
|
||||
//
|
||||
// usage
|
||||
//
|
||||
std::vector<int> my_vector;
|
||||
typedef vector<int>::iterator iterator;
|
||||
std::pair<iterator,iterator> my_view( my_vector.begin(), my_vector.begin() + N );
|
||||
char str[] = "a string";
|
||||
// ...
|
||||
std::cout << my_generic_replace( my_vector, 4, 2 )
|
||||
<< my_generic_replace( my_view, 4, 2 )
|
||||
<< my_generic_replace( str, 'a', 'b' );
|
||||
</pre>By using the free-standing functions and type-generators, the code automatically
|
||||
works for all the types supported by this library. Notice that we have to provide
|
||||
two version of <code >find()</code> since we cannot
|
||||
forward a non-const rvalue with reference arguments (see this article about <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_self" >The Forwarding Problem</a> ).</p><hr size="1" ><h2 >Reference</h2><a name="Reference" ></a><p ><pre >#include <boost/collection_traits.hpp></pre></p><p >Five types of objects are currently supported by the library:<ul ><li >standard containers</li><li >built-in arrays</li><li >null terminated strings (this includes <code >char[]</code>,<code >wchar_t[]</code>,<code >char*</code>, and <code >wchar_t*</code>)</li><li ><code >std::pair<iterator,iterator></code></li><li >iterators which when default constructed denotes the end of the range</li></ul>It is worth noticing that some functionality requires partial template specialization, in particular,
|
||||
full array support does (remark: this is a very small problem since one would use <code>boost::array<></code>
|
||||
anyway). Also note that arrays and pointers of <code >char</code> or <code >whar_t</code> are treated special because of their use in string algorithms.</p><h3 >ExternalCollectionConcept</h3><a name="ExternalCollectionConcept" ></a><p >The concept is defined by the type-generators and the
|
||||
functions below. Even though these functions are defined in
|
||||
namespace <code>boost</code>, there is no such general requirement, that is,
|
||||
if one wants to extend the list of supported types, it can be done in any
|
||||
namespace.</p><h3 >Synopsis</h3><a name="Synopsis" ></a><p ><pre>
|
||||
namespace boost
|
||||
{
|
||||
//
|
||||
// type generators
|
||||
//
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#value_type_of" >value_type_of</a>
|
||||
{
|
||||
typedef ... type; // type of stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#iterator_of" >iterator_of</a>
|
||||
{
|
||||
typedef ... type; // iterator over stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#const_iterator_of" >const_iterator_of</a>
|
||||
{
|
||||
typedef ... type; // iterator over immutable stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#difference_type_of" >difference_type_of</a>
|
||||
{
|
||||
typedef ... type;
|
||||
BOOST_STATIC_ASSERT( boost::is_signed< type >::value );
|
||||
//
|
||||
// remark: if std::iterator_traits<> works for the type, this assertion must hold
|
||||
//
|
||||
BOOST_STATIC_ASSERT( boost::is_same< type, std::iterator_traits< typename
|
||||
<a href="#iterator_of" >iterator_of</a>< EC >::type >::difference_type>::value );
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#size_type_of" >size_type_of</a>
|
||||
{
|
||||
typedef ... type;
|
||||
BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
|
||||
BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( <a href="#difference_type_of" >difference_type_of</a>< EC >::type ) );
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#result_iterator_of" >result_iterator_of</a>
|
||||
{
|
||||
typedef ... type;
|
||||
// <a href="#iterator_of" >iterator_of</a>< EC >::type if EC is non-const, <a href="#const_iterator_of" >const_iterator_of</a>< EC >::type otherwise
|
||||
};
|
||||
|
||||
//
|
||||
// funtions
|
||||
//
|
||||
|
||||
template< typename EC >
|
||||
inline typename iterator_of<EC>::type
|
||||
<a href="#begin" >begin</a>( EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename const_iterator_of< EC >::type
|
||||
<a href="#begin" >begin</a>( const EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename iterator_of< EC >::type
|
||||
<a href="#end" >end</a>( EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename const_iterator_of< EC >::type
|
||||
<a href="#end" >end</a>( const EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline bool
|
||||
<a href="#empty" >empty</a>( const EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename size_type_of< EC >::type
|
||||
<a href="#size" >size</a>( const EC& c );
|
||||
|
||||
} // namespace 'boost' </pre></p><h3 >Library headers</h3><a name="Library headers" ></a><table cellpadding=5 border=1 > <tr ><th >Header</th><th >Includes</th></tr><tr ><td ><code ><boost/collection_traits.hpp></code></td><td >everything</td></tr><tr ><td ><code ><boost/collection_traits/types.hpp></code></td><td >every type-generator</td></tr><tr ><td ><code ><boost/collection_traits/functions.hpp></code></td><td >every function</td></tr><tr ><td ><code ><boost/collection_traits/value_type.hpp></code></td><td ><a href="#value_type_of" >value_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/iterator.hpp></code></td><td ><a href="#iterator_of" >iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/const_iterator.hpp></code></td><td ><a href="#const_iterator_of" >const_iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/difference_type.hpp></code></td><td ><a href="#difference_type_of" >difference_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/size_type.hpp></code></td><td ><a href="#size_type_of" >size_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/result_iterator.hpp></code></td><td ><a href="#result_iterator_of" >result_iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/begin.hpp></code></td><td ><a href="#begin" >begin</a></td></tr><tr ><td ><code ><boost/collection_traits/end.hpp></code></td><td ><a href="#end" >end</a></td></tr><tr ><td ><code ><boost/collection_traits/empty.hpp></code></td><td ><a href="#empty" >empty</a></td></tr><tr ><td ><code ><boost/collection_traits/size.hpp></code></td><td ><a href="#size" >size</a></td></tr> </table><br><h3 >Semantics</h3><a name="Semantics" ></a><p >In the table <code >C</code> is a type that conforms to the ExternalCollectionConcept and <code >c</code> is an object of that type.<code > SC</code> will denote a standard
|
||||
container, <code > T[sz]</code> will denote an array of type <code >T</code> of size <code >sz</code>, <code >P</code> will denote <code >std::pair<></code>, <code > I</code> means an iterator which default construction
|
||||
denotes the end of the range and <code >sc,t,p,i</code> are objects of these types,
|
||||
respectively. Special cases for <code >char*</code> and <code >wchar_t*</code> are described explicitly. </p><table border=1 cellpadding=5 > <tr ><th >Expression</th><th >Return type</th><th >Complexity</th></tr><tr ><a name="value_type_of" ></a><td ><code >value_type_of<C>::type</code></td><td ><code >SC::value_type</code><br><code >T</code><br><code >std::iterator_traits<P::first_type>::value_type</code><br><code >std::iterator_traits<I>::value_type</code></td><td >compile time</td></tr><tr ><a name="iterator_of" ></a><td ><code >iterator_of<C>::type</code></td><td ><code >SC::iterator</code><br><code >T*</code><br><code >P::first_type</code><br><code >I</code></td><td >compile time</td></tr><tr ><a name="const_iterator_of" ></a><td ><code >const_iterator_of<C>::type</code></td><td ><code >SC::const_iterator</code><br><code >const T*</code><br><code >P::first_type</code><br><code >I</code></td><td >compile time</td></tr><tr ><a name="difference_type_of" ></a><td ><code >difference_type_of<C>::type</code></td><td ><code >SC::difference_type</code><br><code >std::ptrdiff_t</code><br><code >std::iterator_traits<P::first_type>::difference_type</code><br><code >std::iterator_traits<I>::difference_type</code></td><td >compile time</td></tr><tr ><a name="size_type_of" ></a><td ><code >size_type_of<C>::type</code></td><td ><code >SC::size_type</code><br><code >std::size_t</code><br><code >std::size_t</code><br><code >std::size_t</code></td><td >compile time</td></tr><tr ><a name="result_iterator_of" ></a><td ><code >result_iterator_of<C>::type</code></td><td ><code >const_iterator_of<C>::type</code> if <code >C</code> is <code >const</code><br><code >iterator_of<C>::type</code> otherwise </td><td >compile time</td></tr> </table> <br> <table border=1 cellpadding=5 > <tr ><th >Expression</th><th >Return type</th><th >Effects</th><th >Complexity</th></tr><tr ><a name="begin" ></a><td ><code >begin( c )</code></td><td ><code >result_iterator_of<C>::type</code></td><td ><code >sc.begin()</code><br><code >t</code><br><code >p.first</code><br><code >i</code></td><td >constant time</td></tr><tr ><a name="end" ></a><td ><code >end( c )</code></td><td ><code >result_iterator_of<C>::type</code></td><td ><code >sc.end()</code><br><code >t + std::char_traits<C>::length( t )</code> if <code >C</code> is <code >char*</code> or <code >wchar_t*</code><br><code >t + sz - 1</code> if <code >C</code> is <code >char[sz]</code> or <code >wchar_t[sz]</code><br><code >t + sz</code> otherwise <br><code >p.second</code><br><code >I()</code></td><td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code><br>constant time otherwise</td></tr><tr ><a name="empty" ></a><td ><code >empty( c )</code></td><td >Convertible to <code >bool</code></td><td ><code >sc.empty()</code><br><code >size( t ) == 0</code><br><code >p.first == p.second</code><br><code >begin( i ) == end( i )</code></td><td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code><br>constant time otherwise<br></td></tr><tr ><a name="size" ></a><td ><code >size( c )</code></td><td ><code >size_type_of<C>::type</code></td><td ><code >sc.size()</code><br><code >end( t ) - begin( t )</code><br><code >distance( p.first, p.second )</code><br><code >not available for iterators</code></td><td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code><br> or if <code >std::distance()</code> is linear <br>constant time otherwise</td></tr> </table><p >Please note that <code >char*</code>,<code >whar_t*</code>,<code >char[]</code>, and <code >wchar_t[]</code> behaves differently from
|
||||
normal arrays only for <code >size()</code> and <code >end()</code>.
|
||||
Note that the null pointer is allowed as an argument in these cases.</p><br><hr size="1" ><h2 >Examples</h2><a name="Examples" ></a><p >Some examples are given in the accompanying test
|
||||
files:</p><ul ><li > <a href="../test/iterator.cpp" target="_self" ><code >iterator.cpp</code></a> </li> shows how to implement a container version of <code >std::copy()</code> that works with <code >std::ifstream_iterator<>.</code><li > <a href="../test/string.cpp" target="_self" ><code >string.cpp</code></a> </li> shows how to implement a container version of <code >std::find()</code> that works with <code >char[],wchar_t[],char*,wchar_t*.</code><li > <a href="../test/algorithm_example.cpp" target="_self" ><code >algorithm_example.cpp</code></a> </li> shows the replace example from the introduction. </ul><hr size="1" ><h2 >Portability</h2><a name="Portability" ></a><p >Full support for built-in arrays require that the
|
||||
compiler supports class template partial specialization.</p><p >Notice that some compilers cannot do function template ordering
|
||||
properly. In that case one cannot rely of <code >result_iterator_of<></code> and a single function definition; instead one needs to supply
|
||||
a function overloaded for const and non-const arguments if it is required.</p><p >Full support for iterators like <code >std::istream_iterator<></code> depends very
|
||||
much on a conforming standard library.</p><p >Most of the tests have been run successfully on these compilers<ul ><li >vc7.1</li><li >gcc3.2</li><li >como4.3.0.1</li><li >bcc6</li></ul></p><hr size="1" ><h2 >FAQ</h2><a name="FAQ" ></a><ol ><li >Why is there no difference between <code >iterator_of<C>::type</code> and <code >const_iterator_of<C>::type</code> for <code >std::pair<iterator,iterator></code> or iterators which default construction denotes the end of the range?</li><p >In general it is not possible nor desirable to find a corresponding <code >const_iterator</code>. When it is possible to come up with
|
||||
one, the client might choose to
|
||||
construct a <code >std::pair<const_iterator,const_iterator></code> object. </p><li >Why does the traits not supply more types or more functions?<p >The traits class have been kept small because its current interface
|
||||
will serve most purposes. If and when a genuine need arises for
|
||||
more functionality, it can be implemented.</p></li><li >How should I implement generic algorithms for external collections?<p >One should always start with a generic algorithm that takes two iterators as input. Then use the
|
||||
collection traits to build handier versions on top of the base algorithm.</p></li></ol><hr size="1" ><h2 >History</h2><a name="History" ></a><p >The library have been under way for a long time. Dietmar Kühl originally
|
||||
intended to submit an <code >array_traits<></code> class template which had most
|
||||
of the functionality present now, but only for arrays and standard containers.
|
||||
Meanwhile work on container algorithms
|
||||
in various context showed the need for handling pairs of iterators, and
|
||||
string libraries needed special treatment of character arrays.
|
||||
Thorsten Ottosen wrote everything from the ground up including the first
|
||||
work-around for missing partial template specialization. Pavol Droba helped to
|
||||
improve the work-around for handicapped compilers and the special character support.
|
||||
The naming scheme of type-generators was suggested by Peter Dimov. </p><hr size="1" ><p >© Thorsten Ottosen 2003-2004 (nesotto_AT_cs.auc.dk).
|
||||
Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears
|
||||
in all copies. This software is provided "as is" without express or implied warranty, and with no
|
||||
claim as to its suitability for any purpose.</p><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></body></html>
|
||||
<!-- Copyright Dezide Aps 2003-2004 -->
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 8.6 KiB |
@@ -0,0 +1,38 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title> Concepts and External Concepts </title><meta http-equiv="Content-Type"content="text/html; charset=iso-8859-1"></head> <body><table ><tr ><td ><img src="cboost.gif" width="100%" border="0"></td><td ><h1 >Concepts and External Concepts</h1></td></tr></table><p >Generic programming in C++ is characterized by the use of function and class templates where
|
||||
the template parameter(s) must satisfy certain requirements.Often these
|
||||
requirements are so important that we give them a name: we call
|
||||
such a set of type requirements a <b>concept</b>. We say that a type <i>
|
||||
conforms to a concept</i> or that it <i>is a model of a concept</i> if it
|
||||
satisfies all of those requirements. The concept can be specified as a set
|
||||
of member functions with well-defined semantics
|
||||
and a set of nested typedefs with well-defined properties.</p><p >Often it much more flexible to provide free-standing functions and typedefs
|
||||
which provides the exact same semantics (but a different syntax) as
|
||||
specified
|
||||
by the concept. This allows generic code to treat different types <i> as if
|
||||
</i> they fulfilled the concept. In this case we say that the concept has
|
||||
been <b> externalized </b> or that the new requirements constitutes an <b>external
|
||||
concept </b>. We say that a type <i> conforms to an external concept </i>
|
||||
or that it <i> is a model of an external concept </i>. A concept may exist
|
||||
without a corresponding external concept and conversely.</p><p >Whenever a concept specifies a member function, the corresponding external
|
||||
concept
|
||||
must specify a free-standing function of the same name, same return type and
|
||||
the same argument list except there is an extra first argument which must
|
||||
be of the type (or a reference to that type) that is to fulfill the external
|
||||
concept. If the corresonding member function has any cv-qulifiers, the
|
||||
first argument must have the same cv-qualifiers. Whenever a concept
|
||||
specifies a nested typedef, the corresponding external concept
|
||||
specifies a <b>type-generator</b>, that is, a type with a nested typedef
|
||||
named <code>type</code>. The type-generator has the name as the nested typedef with
|
||||
<code>_of</code> appended.
|
||||
The converse relationship of an external concept and its corresponding concept
|
||||
also holds.</p><p ><b ><i >Example:</i></b></p><p >A type <code>T</code> fulfills the FooConcept if it
|
||||
has the follwing public members:</p><code> void T::foo( int ) const; <br>
|
||||
int T::bar(); <br>
|
||||
typedef <i>implementation defined </i> foo_type;</code><p >The corresponding external concept is the ExternalFooConcept.</p><p >A type <code>T</code> fullfills the ExternalFooConcept if these
|
||||
free-standing functions and type-generators exists:</p><code>void foo( const T&, int ); <br>
|
||||
int bar( T& ); <br>
|
||||
foo_type_of< T >::type;</code> <br> <br><hr size="1" ><h3 >Literature</h3><ul ><li > <a href="http://www.boost.org/more/generic_programming.html#type_generator" target="_self" >Type Generators</a> </li><li > <a href="http://www.boost.org/more/generic_programming.html#concept" target="_self" >Concepts</a> </li><li > <a href="http://www.sgi.com/tech/stl/stl_introduction.html" target="_self" >Concepts and SGI STL</a> </li></ul><hr size="1" ><p >© Thorsten Ottosen 2003-2004 (nesotto_AT_cs.auc.dk).
|
||||
Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears
|
||||
in all copies. This software is provided "as is" without express or implied warranty, and with no
|
||||
claim as to its suitability for any purpose.</p><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></body></html>
|
||||
<!-- Copyright Dezide Aps 2003-2004 -->
|
||||
Executable
+612
@@ -0,0 +1,612 @@
|
||||
<HTML>
|
||||
<!--
|
||||
-- Copyright (c) Jeremy Siek 2000
|
||||
--
|
||||
-- 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.
|
||||
-->
|
||||
<Head>
|
||||
<Title>Collection</Title>
|
||||
</HEAD>
|
||||
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
||||
ALINK="#ff0000">
|
||||
<IMG SRC="cboost.gif"
|
||||
ALT="C++ Boost">
|
||||
<IMG SRC="/Images/stat.gif" ALT="" BORDER=0 WIDTH = "6" HEIGHT = "6" >
|
||||
|
||||
<BR Clear>
|
||||
<H1>Collection</H1>
|
||||
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
A Collection is a <i>concept</i> similar to the STL <a
|
||||
href="http://www.sgi.com/Technology/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:
|
||||
|
||||
<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>The semantics of copying a Collection object is not defined (it
|
||||
could be a deep or shallow copy or not even support copying).
|
||||
<LI>The associated reference type of a Collection does
|
||||
not have to be a real C++ reference.
|
||||
</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.
|
||||
|
||||
<p>
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<Table border>
|
||||
<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/Technology/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/Technology/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="#1">[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>
|
||||
<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>
|
||||
|
||||
The following expressions must be valid.
|
||||
<p>
|
||||
|
||||
<Table border>
|
||||
<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>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
<TH>
|
||||
Postcondition
|
||||
</TH>
|
||||
</TR>
|
||||
<TD VAlign=top>
|
||||
<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
|
||||
</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>
|
||||
|
||||
<tt>begin()</tt> and <tt>end()</tt> are amortized constant time.
|
||||
<P>
|
||||
<tt>size()</tt> is at most linear in the Collection's
|
||||
size. <tt>empty()</tt> is amortized constant time.
|
||||
<!-- <P>
|
||||
<tt>swap()</tt> is at most linear in the size of the two collections. -->
|
||||
<h3>Invariants</h3>
|
||||
<Table border>
|
||||
<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> <tt>array_ptr</tt> -->
|
||||
<LI> <tt>vector<bool></tt>
|
||||
</UL>
|
||||
|
||||
<!--
|
||||
<h3>Collection Refinements</h3>
|
||||
|
||||
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.
|
||||
|
||||
<h4>ForwardCollection</h4>
|
||||
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/Technology/STL/EqualityComparable.html">EqualityComparable</A>
|
||||
and
|
||||
<A
|
||||
href="http://www.sgi.com/Technology/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>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
</TR>
|
||||
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Font
|
||||
</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.first())</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
|
||||
</table>
|
||||
|
||||
|
||||
<h4>ReversibleCollection</h4>
|
||||
|
||||
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/Technology/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>
|
||||
<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>
|
||||
|
||||
The elements are arranged in a strict linear order. No extra methods
|
||||
are required.
|
||||
-->
|
||||
|
||||
<h3>Notes</h3>
|
||||
|
||||
<P><A name="1">[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). 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).
|
||||
|
||||
<h3>See also</h3>
|
||||
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
||||
|
||||
|
||||
<br>
|
||||
<HR>
|
||||
<TABLE>
|
||||
<TR valign=top>
|
||||
<TD nowrap>Copyright © 2000</TD><TD>
|
||||
<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>)
|
||||
</TD></TR>
|
||||
<tr >
|
||||
<TD nowrap>Copyright © 2004</TD><TD>
|
||||
Thorsten Ottosen.
|
||||
</TABLE>
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in new issue
Block a user