std::pair<iterator,iterator>
char[],wchar_t[],
char*, and wchar_t*)
std::pair<iterator,iterator>
- boost::array<> anyway). Also note
that arrays and pointers of char or whar_t are
treated special because of their use in string algorithms.
-
-The concept is defined by the type-generators and the functions below. Even
+The concept is defined by the metafunction and the functions below. Even
though these functions are defined in namespace boost, 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.
+
- namespace boost
- {
- //
- // type generators
- //
-
- template< typename EC >
- struct value_type_of
- {
- typedef ... type; // type of stored objects
- };
-
- template< typename EC >
- struct iterator_of
- {
- typedef ... type; // iterator over stored objects
- };
-
- template< typename EC >
- struct const_iterator_of
- {
- typedef ... type; // iterator over immutable stored objects
- };
-
- template< typename EC >
- struct difference_type_of
- {
- 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
- iterator_of< EC >::type >::difference_type>::value );
- };
-
- template< typename EC >
- struct size_type_of
- {
- typedef ... type;
- BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
- BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof(
- difference_type_of< EC >::type ) );
- };
-
- template< typename EC >
- struct result_iterator_of
- {
- typedef ... type;
- // iterator_of< EC >::type if EC is non-const,
- const_iterator_of< EC >::type otherwise
- };
-
- //
- // funtions
- //
-
- template< typename EC >
- inline typename iterator_of::type
- begin( EC& c );
+namespace boost
+{
+ //
+ // Range metafunctions
+ //
- template< typename EC >
- inline typename const_iterator_of< EC >::type
- begin( const EC& c );
-
- template< typename EC >
- inline typename iterator_of< EC >::type
- end( EC& c );
-
- template< typename EC >
- inline typename const_iterator_of< EC >::type
- end( const EC& c );
+ template< class T >
+ struct value_type_of
+ {
+ typedef ... type; // type of stored objTts
+ };
+
+ template< class T >
+ struct iterator_of
+ {
+ typedef ... type; // iterator over stored objects
+ };
+
+ template< class T >
+ struct const_iterator_of
+ {
+ typedef ... type; // iterator over immutable stored objects
+ };
+
+ template< class T >
+ struct difference_type_of
+ {
+ 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
+ iterator_of< T >::type >::difference_type>::value );
+ };
+
+ template< class T >
+ struct size_type_of
+ {
+ typedef ... type;
+ BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
+ BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof(
+ difference_type_of< T >::type ) );
+ };
+
+ template< class T >
+ struct result_iterator_of
+ {
+ typedef ... type;
+ // iterator_of< T >::type if T is non-const,
+ const_iterator_of< T >::type otherwise
+ };
+
+ //
+ // funtions
+ //
+
+ template< class T >
+ inline typename iterator_of::type
+ begin( T& c );
+
+ template< class T >
+ inline typename const_iterator_of< T >::type
+ begin( const T& c );
- template< typename EC >
- inline bool
- empty( const EC& c );
-
- template< typename EC >
- inline typename size_type_of< EC >::type
- size( const EC& c );
-
- } // namespace 'boost'
+ template< class T >
+ inline typename iterator_of< T >::type
+ end( T& c );
+
+ template< class T >
+ inline typename const_iterator_of< T >::type
+ end( const T& c );
+
+ template< class T >
+ inline bool
+ empty( const T& c );
+
+ template< class T >
+ inline typename size_type_of< T >::type
+ size( const T& c );
+
+} // namespace 'boost'
diff --git a/doc/external_concepts.html b/doc/external_concepts.html
index 98ccf90..f04671d 100644
--- a/doc/external_concepts.html
+++ b/doc/external_concepts.html
@@ -1,38 +1,123 @@
- | Concepts and External Concepts |
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 concept. We say that a type - conforms to a concept or that it is a model of a concept 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.
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 as if - they fulfilled the concept. In this case we say that the concept has - been externalized or that the new requirements constitutes an external - concept . We say that a type conforms to an external concept - or that it is a model of an external concept . A concept may exist - without a corresponding external concept and conversely.
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 type-generator, that is, a type with a nested typedef
- named type. The type-generator has the name as the nested typedef with
- _of appended.
- The converse relationship of an external concept and its corresponding concept
- also holds.
Example:
A type T fulfills the FooConcept if it
- has the follwing public members:
void T::foo( int ) const;
- int T::bar();
- typedef implementation defined foo_type;The corresponding external concept is the ExternalFooConcept.
A type T fullfills the ExternalFooConcept if these
- free-standing functions and type-generators exists:
void foo( const T&, int );
- int bar( T& );
- foo_type_of< T >::type; © 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.
|
+ Concepts and External Concepts |
+
+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 concept. We say that a type conforms to a +concept or that it is a model of a concept 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. +
++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 as if they +fulfilled the concept. In this case we say that the concept has been externalized + or that the new requirements constitutes an external concept . We +say that a type conforms to an external concept or that it is a model +of an external concept . A concept may exist without a corresponding +external concept and conversely. +
+
+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 metafunction,
+that is, a type with a nested typedef named type. The metafunction
+has the name as the nested typedef with _of appended. The converse
+relationship of an external concept and its corresponding concept also holds.
+
+Example: +
+
+A type T fulfills the FooConcept if it has the follwing public
+members:
+
void T::foo( int ) const;
+int T::bar();
+typedef implementation defined foo_type;
++The corresponding external concept is the ExternalFooConcept. +
+
+A type T fullfills the ExternalFooConcept if these free-standing
+functions and metafunctions exists:
+
void foo( const T&, int );
+int bar( T& );
+foo_type_of< T >::type; +© 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. +
+-
iterator_of<C>::type and const_iterator_of<C>::type
- for std::pair<iterator, iterator>.
+ Why is there no difference between iterator_of<C>::type
+ and const_iterator_of<C>::type for std::pair<iterator,
+ iterator>.
In general it is not possible nor desirable to find a corresponding const_iterator.
@@ -30,24 +30,71 @@
object.
- The library 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. + The library 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.
- One should always start with a generic algorithm that takes two - iterators (or more) as - input. Then use Boost.Range to build handier versions on top of the - iterator based algorithm. Please notice that once the range version - of the algorithm is done, it makes sense not to expose the - iterator version in the public interface. + One should always start with a generic algorithm that takes two iterators (or + more) as input. Then use Boost.Range to build handier versions on top of the + iterator based algorithm. Please notice that once the range version of the + algorithm is done, it makes sense not to expose the iterator version in + the public interface.
+ Even though we speak of incrementable iterators, it would not make + much sense for ranges; for example, we cannot determine the size and + emptiness of a range since we cannot even compare + its iterators. +
++ instead of +boost::begin( r );
++ when calling functions in this library? If so, can I still rely on argument + dependent lookup (ADL) to kick in? +using namespace boost; +begin( r )
+ The answer to the first question is that "it's up to you". The + answer to the second question is Yes. Normally qualified syntax + disables ADL, but the functions are implemented in a special + manner that preserves ADL properties. The trick was explained by + Daniel Frey on comp.lang.std.c++ in the thread "Whence Swap" and + it is best explained by some code:
+
+namespace boost
+{
+ namespace range_detail
+ {
+ template< class T >
+ typename iterator_of<T>:type begin( T& r )
+ { /* normal implementation */ }
+ }
+
+ template< class T >
+ typename iterator_of<T>::type begin( T& r )
+ {
+ //
+ // Create ADL hook
+ //
+ using range_detail::begin;
+ return begin( r );
+ }
+}
+
+
+
<boost/range.hpp><boost/range/types.hpp><boost/range/metafunctions.hpp><boost/range/functions.hpp><boost/range/value_type.hpp><boost/range/iterator.hpp><boost/range/const_iterator.hpp><boost/range/difference_type.hpp><boost/range/size_type.hpp><boost/range/result_iterator.hpp><boost/range/reverse_iterator.hpp><boost/range/const_reverse_iterator.hpp><boost/range/reverse_result_iterator.hpp><boost/range/begin.hpp><boost/range/end.hpp><boost/range/empty.hpp><boost/range/size.hpp><boost/range/rbegin.hpp><boost/range/rend.hpp><boost/range/iterator_range.hpp><boost/range/sub_range.hpp>- Meanwhile work on container algorithms in various context showed the + Meanwhile work on algorithms for containers in various contexts showed the need for handling pairs of iterators, and string libraries needed special - treatment of character arrays. -
+ treatment of character arrays. In the end it made sense to formalize the + minimal requirements of these similar concepts. And the results are the + Range concepts found in this library. + +
+ The term Range was adopted because of paragraph 24.1/7 from the
+C++ standard:
+ Most of the library's algorithmic templates that operate on data + structures have interfaces that use ranges. A range is a pair of + iterators that designate the beginning and end of the computation. A + range [i, i) is an empty range; in general, a range [i, j) refers to + the elements in the data structure starting with the one pointed to + by i and up to but not including the one pointed to by j. Range [i, + j) is valid if and only if j is reachable from i. The result of the + application of functions in the library to invalid ranges is + undefined. +
Special thanks goes to diff --git a/doc/intro.html b/doc/intro.html index eadca07..e65c7d1 100755 --- a/doc/intro.html +++ b/doc/intro.html @@ -18,22 +18,32 @@
+ When writing generic code that works with Standard Library containers, one often
+ finds it desirable to extend that code to work with other types that offer
+ enough functionality to satisfy the needs of the generic code, but in an altered
+ form. For example, raw arrays are often suitable for use with generic code that
+ works with containers, provided a suitable adapter is used. Likewise, null
+ terminated strings can be treated as containers of characters, if suitably
+ adapted. This library provides the means to adapt Standard Library containers,
+ null terminated strings, std::pairs of iterators, and raw
+arrays, such that the same generic code can work with them all.
+
The main advantages are
Below are given a small example (the complete example can be found here ): -