From 06e624858b64b6b253106f731878c02ad67aba90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thorsten=20J=C3=B8rgen=20Ottosen?= Date: Wed, 7 Sep 2005 16:12:03 +0000 Subject: [PATCH] added discussion on extension mechanism [SVN r30854] --- doc/boost_range.html | 1012 +++++++++++++++++++++++++----------------- doc/example.cpp | 125 ++++++ doc/range.html | 12 +- 3 files changed, 747 insertions(+), 402 deletions(-) create mode 100644 doc/example.cpp diff --git a/doc/boost_range.html b/doc/boost_range.html index 79b54c1..b10714c 100644 --- a/doc/boost_range.html +++ b/doc/boost_range.html @@ -1,79 +1,68 @@ - - Boost.Range Range Implementation - - - - - - - - - - - -


- Boost.Range

- -

Synopsis and Reference

- - -
- - -

Overview

-

- Four types of objects are currently supported by the library: -

- - Even though the behavior of the primary templates are exactly such that standard - containers will be supported by default, the requirements are much lower than - the standard container requirements. For example, the utility class iterator_range implements - the minimal interface required to make the - class a Forward Range. -

- -

- Please also see Range concepts for more details. -

- -

Synopsis

- -

- - 

+	
+		Boost.Range Range Implementation 
+		
+		
+	
+	
+		
+			
+				
+				
+			
+		


+						Boost.Range
+					

+				

+		
Synopsis and Reference
+		

+		
+		

+		
+		
Overview

+		

+			Four types of objects are currently supported by the library:
+			

+			Even though the behavior of the primary templates are exactly such that 
+			standard containers will be supported by default, the requirements are much 
+			lower than the standard container requirements. For example, the utility class 
+				iterator_range implements the minimal 
+				interface required to make the class a Forward 
+				Range
+		.
+		

+		

+			Please also see Range concepts for more details.
+		

+		
+		
Synopsis

+		

+			
 namespace boost
 {
     //
@@ -207,341 +196,572 @@ class=identifier>T& } // namespace 'boost' 
 
 

-    

+		

+		
+		
Semantics

+		
notation

+		

+			
+				
+					
+				
+					
+				
+					
+					
+				
+				
+					
+				
+					
+				
+					
+				
+			

+						Type
+						
+							Object
+							
+					Describes
+				
X
+					x
+					any type
T
+					t
+					denotes behavior of the primary templates
P
+					p
+					denotes std::pair<iterator,iterator>
A[sz]
+					a
+					denotes an array of type A of size sz
+				
Char*
+					s
+					denotes either char* or wchar_t*

+		

+		

+			Please notice in tables below that when four lines appear in a cell, the first 
+			line will describe the primary template, the second line pairs of iterators, 
+			the third line arrays and the last line null-terminated strings.
+		

+		
Metafunctions

+		

+			
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+				
+					
+					
+					
+				
+			

+						Expression
+						Return type
+						Complexity
range_value<X>::typeT::value_type

+						boost::iterator_value<P::first_type>::type

+						A

+						Char
+							compile time
range_iterator<X>::typeT::iterator

+						P::first_type

+						A*

+						Char*
+							compile time
range_const_iterator<X>::typeT::const_iterator

+						P::first_type

+						const A*

+						const Char*
+							compile time
range_difference<X>::typeT::difference_type

+						boost::iterator_difference<P::first_type>::type

+						std::ptrdiff_t

+						std::ptrdiff_t

+							compile time
range_size<X>::typeT::size_type

+						std::size_t

+						std::size_t

+						std::size_t

+							compile time
range_result_iterator<X>::typerange_const_iterator<X>::type if X is const
+						

+						range_iterator<X>::type otherwise
+							compile time
range_reverse_iterator<X>::typeboost::reverse_iterator< typename range_iterator<T>::type >

+							compile time
range_const_reverse_iterator<X>::typeboost::reverse_iterator< typename range_const_iterator<T>::type >
+						

+							compile time
range_reverse_result_iterator<X>::typeboost::reverse_iterator< typename range_result_iterator<T>::type 
+							>
+					compile time

+		

+		

+			The special metafunctions range_result_iterator and range_reverse_result_iterator
+			are not part of any Range concept, but they are very useful when implementing 
+			certain Range classes like sub_range
+			because of their ability to select iterators based on constness.
+		

+		
Functions

+		

+			
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+				
+					
+					
+					
+					
+				
+			

+						Expression
+						Return type
+						Returns
+						Complexity
begin(x)range_result_iterator<X>::typet.begin()

+						p.first

+						a

+						s

+						boost_range_begin(x) otherwise
+							constant time
end(x)range_result_iterator<X>::typet.end()

+						p.second

+						a + sz

+						s + std::char_traits<X>::length( s ) if X is Char*
+						

+						s + sz - 1 if X is Char[sz]
+						

+					    boost_range_end(x) otherwise
+						
+							linear if X is Char*
+						

+						constant time otherwise
empty(x)boolbegin(x) == end( x )

+							linear if X is Char*
+						

+						constant time otherwise

+					
size(x)range_size<X>::typet.size()

+						std::distance(p.first,p.second)

+						sz

+						end(s) - s

+						boost_range_size(x) otherwise
+							linear if X is Char*
+						

+						or if std::distance() is linear
+						

+						constant time otherwise
rbegin(x)range_reverse_result_iterator<X>::typerange_reverse_result_iterator<X>::type( end(x) )
+						

+							same as end(x)
+					
rend(x)range_reverse_result_iterator<X>::typerange_reverse_result_iterator<X>::type( begin(x) )
+					same as begin(x)
const_begin(x)range_const_iterator<X>::typerange_const_iterator<X>::type( begin(x) )
+						

+							same as begin(x)
+					
const_end(x)range_const_iterator<X>::typerange_const_iterator<X>::type( end(x) )
+					same as end(x)
const_rbegin(x)range_const_reverse_iterator<X>::typerange_const_reverse_iterator<X>::type( rbegin(x) )
+						

+							same as rbegin(x)
+					
const_rend(x)range_const_reverse_iterator<X>::typerange_const_reverse_iterator<X>::type( rend(x) )
+					same as rend(x)

+		

+		

+			The special const functions are not part of any Range concept, but 
+			are very useful when you want to document clearly that your code is read-only.
+		

+		

+		
+		
Extending the library

+		
+		
+		
+		
Method 1: provide member functions and nested types

+		
+		

+		This procedure assumes that you have control over the types that should be made
+		conformant to a Range concept. If not, see method 2.
+		

+		
+		

+			The primary templates in this library are implemented such that standard 
+			containers will work automatically and so will boost::array. 
+			Below is given an overview of which member functions and member types a class 
+			must specify to be useable as a certain Range concept.
+		

+		

+			
+				
+					
+					
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+			

+						Member function
+						Related concept
begin()Single Pass Range
end()
+					Single Pass Range
size()Forward Range

+		

+		

+			Notice that rbegin() and rend() member functions are 
+			not needed even though the container can support bidirectional iteration.
+		

+		

+			The required member types are:
+		

+		

+			
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+			

+						Member type
+						Related concept
value_typeSingle Pass Range
iteratorSingle Pass Range
const_iteratorSingle Pass Range
difference_typeForward Range
size_typeForward Range

+		

+		

+			Again one should notice that member types reverse_iterator and const_reverse_iterator
+			are not needed.
+		

+		
+    	
Method 2: provide free-standing functions and specialize metafunctions

 
-     
Semantics

+		

+		This procedure assumes that you cannot (or do not wish to) change the types that should be made
+		conformant to a Range concept. If this is not true, see method 1.
+		

+		
+		

+			The primary templates in this library are implemented such that
+			certain functions are found via argument-dependent-lookup (ADL).
+			Below is given an overview of which free-standing functions a class 
+			must specify to be useable as a certain Range concept.
+			Let x be a variable (const or mutable)
+			of the class in question.
+		

+		

+			
+				
+					
+					
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+			

+						Function
+						Related concept
boost_range_begin(x)Single Pass Range
boost_range_end(x)
+					Single Pass Range
boos_range_size(x)Forward Range
		
+		

+		
boost_range_begin() and boost_range_end() must be
+		overloaded for both const and mutable reference arguments.
+		

+		
+		

+		You must also specialize 3-5 metafunctions for your type X:
+		

+		

+			
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+				
+					
+					
+				
+			

+						Metafunction
+						Related concept
boost::range_valueSingle Pass Range
boost::range_iteratorSingle Pass Range
boost::range_const_iteratorSingle Pass Range
boost::range_differenceForward Range
boost::range_sizeForward Range

+		

+		

+		A complete example is given here:
+		

+		

+		
+#include <boost/range.hpp>
+#include <iterator>         // for std::iterator_traits, std::distance()
 
-    
notation

-    

-    
-        
-            
-        
-            
-        
-            
-            
-        
-        
-            
-        
-            
-        
-            
-    
Type
-            Object
-            Describes
-        
X
-            x
-            any type
-        
T t
-            denotes behavior of the primary templates
P
-            p
-            denotes std::pair<iterator,iterator>
-        
A[sz]
-            a
-            denotes an array of type A of size sz
-        
Char*
-            s
-            denotes either char* or wchar_t*
-        

-    

+namespace Foo
+{
+	//
+	// Our sample UDT. A 'Pair'
+	// will work as a range when the stored
+	// elements are iterators.
+	//
+	template< class T >
+	struct Pair
+	{
+		T first, last;	
+	};
 
-    

-    Please notice in tables below that when four lines appear in a cell, the first 
-    line will describe the primary template, the second line pairs of iterators, the 
-    third line arrays and the last line null-terminated strings.
-    

-    
Metafunctions

-    

-    
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
-        
-            
-            
-            
-        
+}// namespace 'Foo'
 
+namespaceboost
+{
+	//
+	// Specialize metafunctions. We must include the range.hpp header.
+	// We must open the 'boost' namespace.
+	//
+	template<classT>
+	structrange_value<Foo::Pair<T>>
+	{
+		typedeftypenamestd::iterator_traits<T>::value_typetype;
+	};
 
-    
ExpressionReturn typeComplexity
range_value<X>::typeT::value_type

-                boost::iterator_value<P::first_type>::type

-                A

-                Char
-            		compile time
range_iterator<X>::typeT::iterator

-                P::first_type

-                A*

-                Char*
-            		compile time
range_const_iterator<X>::typeT::const_iterator

-                P::first_type

-                const A*

-                const Char*
-            		compile time
range_difference<X>::typeT::difference_type

-                boost::iterator_difference<P::first_type>::type

-                std::ptrdiff_t

-                std::ptrdiff_t

-            		compile time
range_size<X>::typeT::size_type

-                std::size_t

-                std::size_t

-                std::size_t

-            		compile time
range_result_iterator<X>::typerange_const_iterator<X>::type if X is const 

-                range_iterator<X>::type otherwise 		compile time
range_reverse_iterator<X>::typeboost::reverse_iterator< typename range_iterator<T>::type >

-            		compile time
range_const_reverse_iterator<X>::typeboost::reverse_iterator< typename range_const_iterator<T>::type >
-                

-            		compile time
range_reverse_result_iterator<X>::typeboost::reverse_iterator< typename range_result_iterator<T>::type 
-            >
-            compile time
           

-    

-    

-    The special metafunctions range_result_iterator and range_reverse_result_iterator 
-    are not part of any Range concept, but they are very useful when implementing 
-    certain Range classes like sub_range because of their 
-      ability to select iterators based on constness.
-    

+	template< class T >
+	struct range_iterator< Foo::Pair<T> >
+	{
+		typedef T type;
+	};
 
-    
Functions

-    

-    
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
-        
-            
-            
-            
-            
-        
+}// namespace 'boost'
 
-    
ExpressionReturn typeReturnsComplexity
begin(x)range_result_iterator<X>::typet.begin()

-                p.first

-                a

-                s
-            		constant time
end(x)range_result_iterator<X>::typet.end()

-                p.second

-                a + sz 

-                s + std::char_traits<X>::length( s ) if X is Char*
-                

-                s + sz - 1 if X is Char[sz] 

+	template< class T >
+	struct range_const_iterator< Foo::Pair<T> >
+	{
+		//
+		// Remark: this is defined similar to 'range_iterator'
+		//         because the 'Pair' type does not distinguish
+		//         between an iterator and a const_iterator.
+		//
+		typedef T type;
+	};
 
+	template< class T >
+	struct range_difference< Foo::Pair<T> >
+	{
+		typedef typename std::iterator_traits<T>::difference_type type;
+	};
 
-            		linear if X is Char* 

-                constant time otherwise
empty(x)boolbegin(x) == end( x )

-            		linear if X is Char* 

-                constant time otherwise

-            
size(x)range_size<X>::typet.size()

-                std::distance(p.first,p.second)

-                sz

-                end(s) - s
+	template< class T >
+	struct range_size< Foo::Pair<T> >
+	{
+		int static_assertion[ sizeof( std::size_t ) >= 
+			  sizeof( typename range_difference< Foo::Pair<T> >::type ) ];
+		typedef std::size_t type;
+	};
 
-            		linear if X is Char* 

-                or if std::distance() is linear 

-                constant time otherwise
rbegin(x)range_reverse_result_iterator<X>::typerange_reverse_result_iterator<X>::type( end(x) ) 

-            		same as end(x) 
rend(x)range_reverse_result_iterator<X>::typerange_reverse_result_iterator<X>::type( begin(x) )
-            same as begin(x)
const_begin(x)range_const_iterator<X>::typerange_const_iterator<X>::type( begin(x) ) 
-
 		same as begin(x) 
const_end(x)range_const_iterator<X>::typerange_const_iterator<X>::type( end(x) )
-            same as end(x)
const_rbegin(x)range_const_reverse_iterator<X>::typerange_const_reverse_iterator<X>::type( rbegin(x) )
-             
 		same as rbegin(x) 
const_rend(x)range_const_reverse_iterator<X>::typerange_const_reverse_iterator<X>::type( rend(x) )
-            same as rend(x)
 

-    

-    
-    

-    The special const functions are not part of any Range concept, 
-    but are very useful when you want to document clearly that your code is 
-    read-only.
-    

+namespace Foo
+{
+	//
+	// The required functions. These should be defined in
+	// the same namespace as 'Pair', in this case 
+	// in namespace 'Foo'.
+	//
+	
+	template< class T >
+	inline T boost_range_begin( Pair<T>& x )
+	{ 
+		return x.first;
+	}
 
-    

-     
Extending the library

-    

-    The primary templates in this library are implemented such that standard 
-    containers will work automatically and so will boost::array. Below is given an overview of 
-        which member functions and member types a class must specify to 
-be useable as a certain Range concept.
-    

-    

-    
-        
-            
-            
-        
-            
-            
-        
-        
-            
-            
-        
-        
-            
-            
-        
+	template<classT>
+	inlineTboost_range_begin(constPair<T>&x)
+	{ 
+		returnx.first;
+	}
 
-    
Member functionRelated concept
begin()Single Pass Range
end() Single Pass Range
size()Forward Range
          

-    

-    

-    Notice that rbegin() and rend() member functions 
-    are not needed even though the container can support bidirectional iteration.
-    

-    

-    The required member types are:
-    

-    

-    
-        
-            
-            
-        
-        
-            
-            
-        
-        
-            
-            
-        
-        
-            
-            
-        
-        
-            
-            
-        
-        
-            
-            
-        
-        
-    
Member typeRelated concept
value_typeSingle Pass Range
iteratorSingle Pass Range
const_iteratorSingle Pass Range
difference_typeForward Range
size_typeForward Range
        
-        

-        

-    Again one should notice that member types reverse_iterator and
-    const_reverse_iterator are not needed.
-

- 
- 

-    

-    (C) Copyright Thorsten Ottosen 2003-2004
-    

+	template< class T >
+	inline T boost_range_end( Pair<T>& x )
+	{ 
+		return x.last;
+	}
 
-    

-    

-    

-    

-    

-    

-    

-    

-    

-    

-    

-    

+	template< class T >
+	inline T boost_range_end( const Pair<T>& x )
+	{ 
+		return x.last;
+	}
 
+	template< class T >
+	inline typename boost::range_size< Pair<T> >::type
+	boost_range_size( const Pair<T>& x )
+	{
+		return std::distance(x.first,x.last);
+	}
 
-    
+} // namespace 'Foo'
+
+#include <vector>
+
+int main()
+{
+	typedef std::vector<int>::iterator  iter;
+	std::vector<int>                    vec;
+	Foo::Pair<iter>                     pair = { vec.begin(), vec.end() };
+	const Foo::Pair<iter>&              cpair = pair; 
+	//
+	// Notice that we call 'begin' etc with qualification. 
+	//
+	iter i = boost::begin( pair );
+	iter e = boost::end( pair );
+	i      = boost::begin( cpair );
+	e      = boost::end( cpair );
+	boost::range_size< Foo::Pair<iter> >::type s = boost::size( pair );
+	s      = boost::size( cpair );
+	boost::range_const_reverse_iterator< Foo::Pair<iter> >::type
+	ri     = boost::rbegin( cpair ),
+	re     = boost::rend( cpair );
+}	
+

+

+		
+		

+		

+			(C) Copyright Thorsten Ottosen 2003-2004
+		

+		

+		

+		

+		

+		

+		

+		

+		

+		

+		

+		

+		

+	
 
diff --git a/doc/example.cpp b/doc/example.cpp
new file mode 100644
index 0000000..af3e96b
--- /dev/null
+++ b/doc/example.cpp
@@ -0,0 +1,125 @@
+#include 
+#include          // for std::iterator_traits, std::distance()
+
+namespace Foo
+{
+	//
+	// Our sample UDT. A 'Pair'
+	// will work as a range when the stored
+	// elements are iterators.
+	//
+	template< class T >
+	struct Pair
+	{
+		T first, last;	
+	};
+
+} // namespace 'Foo'
+
+namespace boost
+{
+	//
+	// Specialize metafunctions. We must include the range.hpp header.
+	// We must open the 'boost' namespace.
+	//
+	template< class T >
+	struct range_value< Foo::Pair >
+	{
+		typedef typename std::iterator_traits::value_type type;
+	};
+
+	template< class T >
+	struct range_iterator< Foo::Pair >
+	{
+		typedef T type;
+	};
+
+	template< class T >
+	struct range_const_iterator< Foo::Pair >
+	{
+		//
+		// Remark: this is defined similar to 'range_iterator'
+		//         because the 'Pair' type does not distinguish
+		//         between an iterator and a const_iterator.
+		//
+		typedef T type;
+	};
+
+    template< class T >
+	struct range_difference< Foo::Pair >
+	{
+		typedef typename std::iterator_traits::difference_type type;
+	};
+
+	template< class T >
+    struct range_size< Foo::Pair >
+	{
+		int static_assertion[ sizeof( std::size_t ) >= 
+			  sizeof( typename range_difference< Foo::Pair >::type ) ];
+		typedef std::size_t type;
+	};
+
+} // namespace 'boost'
+
+namespace Foo
+{
+	//
+	// The required functions. These should be defined in
+	// the same namespace as 'Pair', in this case 
+	// in namespace 'Foo'.
+	//
+	
+	template< class T >
+	inline T boost_range_begin( Pair& x )
+	{ 
+		return x.first;
+	}
+
+    template< class T >
+	inline T boost_range_begin( const Pair& x )
+	{ 
+		return x.first;
+	}
+
+	template< class T >
+    inline T boost_range_end( Pair& x )
+	{ 
+		return x.last;
+	}
+
+	template< class T >
+    inline T boost_range_end( const Pair& x )
+	{ 
+		return x.last;
+	}
+
+	template< class T >
+	inline typename boost::range_size< Pair >::type
+	boost_range_size( const Pair& x )
+	{
+		return std::distance(x.first,x.last);
+	}
+
+} // namespace 'Foo'
+
+#include 
+
+int main()
+{
+	typedef std::vector::iterator  iter;
+	std::vector                    vec;
+	Foo::Pair                     pair = { vec.begin(), vec.end() };
+	const Foo::Pair&              cpair = pair; 
+	//
+	// Notice that we call 'begin' etc with qualification. 
+	//
+	iter i = boost::begin( pair );
+	iter e = boost::end( pair );
+	i      = boost::begin( cpair );
+	e      = boost::end( cpair );
+	boost::range_size< Foo::Pair >::type s = boost::size( pair );
+	s      = boost::size( cpair );
+	boost::range_const_reverse_iterator< Foo::Pair >::type
+	ri     = boost::rbegin( cpair ),
+	re	   = boost::rend( cpair );
+}
diff --git a/doc/range.html b/doc/range.html
index b2f907c..13b5ad4 100755
--- a/doc/range.html
+++ b/doc/range.html
@@ -386,7 +386,7 @@ VAlign="top">boost::range_const_reverse_iterator<X>::type
         
         
             Beginning of range
-            rboost::begin(a)
+            boost::rbegin(a)
             boost::range_reverse_iterator<X>::type if
 a is mutable, boost::range_const_reverse_iterator<X>::type
 otherwise.
@@ -394,7 +394,7 @@ otherwise.
 boost::range_reverse_iterator<X>::type(boost::end(a)). 
         
             End of range
-            rboost::end(a)
+            boost::rend(a)
             boost::range_reverse_iterator<X>::type if
 a is mutable, boost::range_const_reverse_iterator<X>::type
 otherwise.
@@ -405,7 +405,7 @@ otherwise.
 
     
Complexity guarantees

 
-    rboost::begin(a) has the same complexity as boost::end(a) and rboost::end(a) 
+    boost::rbegin(a) has the same complexity as boost::end(a) and boost::rend(a) 
     has the same complexity as boost::begin(a) from Forward Range.
 
@@ -414,13 +414,13 @@ otherwise.
     
-            
-            

         

             Valid reverse rangeFor any Bidirectional Range a, [rboost::begin(a),rboost::end(a)) 
-            is a valid range, that is, rboost::end(a) is reachable from rboost::begin(a) 
+            For any Bidirectional Range a, [boost::rbegin(a),boost::rend(a)) 
+            is a valid range, that is, boost::rend(a) is reachable from boost::rbegin(a) 
             in a finite number of increments.
         

         

             CompletenessAn algorithm that iterates through the range [rboost::begin(a),rboost::end(a))
+            An algorithm that iterates through the range [boost::rbegin(a),boost::rend(a))
             will pass through every element of a.