diff --git a/doc/range.htm b/doc/range.htm index 2f045a0..7819b69 100755 --- a/doc/range.htm +++ b/doc/range.htm @@ -11,7 +11,7 @@ -- purpose. It is provided "as is" without express or implied warranty. --> -Collection +Range Concepts @@ -20,147 +20,32 @@
-

Collection

- +

Range

Description

-A Collection is a concept similar to the STL concept similar to the STL Container -concept. A Collection provides iterators for accessing a range of +concept. A Range 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 +Range. However, a Range has fewer requirements than a +Container. The motivation for the Range 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: +with this reduced set of requirements. In particular, a Range does +not necessarily - + - -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. +Because of the second requirement, a Range object must +be passed by reference in generic code.

-

Associated types

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Value type - -X::value_type - -The type of the object stored in a Collection. -If the Collection is mutable then -the value type must be Assignable. -Otherwise the value type must be CopyConstructible. -
-Iterator type - -X::iterator - -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 InputIterator. -
-Const iterator type - -X::const_iterator - -A type of iterator that may be used to examine, but not to modify, - a Collection's elements. -
-Reference type - -X::reference - -A type that behaves like a reference to the Collection's value type. -[1] -
-Const reference type - -X::const_reference - -A type that behaves like a const reference to the Collection's value type. -
-Pointer type - -X::pointer - -A type that behaves as a pointer to the Collection's value type. -
-Distance type - -X::difference_type - -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. -
-Size type - -X::size_type - -An unsigned integral type that can represent any nonnegative value - of the Collection's distance type. -

Notation

@@ -168,7 +53,7 @@ An unsigned integral type that can represent any nonnegative value X @@ -189,6 +74,120 @@ The value type of X.
-A type that is a model of Collection. +A type that is a model of Range.
+

Associated types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Value type + +X::value_type + +The type of the object stored in a Range. + +
+Iterator type + +X::iterator + +The type of iterator used to iterate through a Range's + elements. The iterator's value type is expected to be the + Range's value type. A conversion + from the iterator type to the const iterator type must exist. + The iterator type must at least be an InputIterator. +
+Const iterator type + +X::const_iterator + +A type of iterator that may be used to examine, but not to modify, + a Range's elements. +
+Reference type + +X::reference + +A type that behaves like a reference to the Range's value type. +[1] +
+Distance type + +X::difference_type + +A signed integral type used to represent the distance between two + of the Range's iterators. This type must be the same as + the iterator's distance type. +
+Size type + +X::size_type + +An unsigned integral type that can represent any nonnegative value + of the Range's distance type. +
+ +

Valid expressions

The following expressions must be valid. @@ -254,7 +253,7 @@ Maximum size --> -Empty Collection +Empty range a.empty() @@ -302,7 +301,7 @@ Beginning of range a.begin() -Returns an iterator pointing to the first element in the Collection. +Returns an iterator pointing to the first element in the Range. a.begin() is either dereferenceable or past-the-end. It is @@ -318,7 +317,7 @@ End of range Returns an iterator pointing one past the last element in the - Collection. + Range. a.end() is past-the-end. @@ -391,12 +390,11 @@ Equivalent to swap(a,b)

Complexity guarantees

-begin() and end() are amortized constant time. -

-size() is at most linear in the Collection's -size. empty() is amortized constant time. - +All four functions are at most amortized linear time. For +most practical purposes, one can expect +begin(), end() and empty() to be amortized constant +time. +

Invariants

@@ -404,7 +402,7 @@ size. empty() is amortized constant time. Valid range @@ -430,81 +428,66 @@ An algorithm that iterates through the range [a.begin(), a.end())

Models

- +rbegin() has the same complexity as end() and +rend() has the same complexity as begin() from Range. +

Models

+ + + +

Notes

[1] 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 +the Range is being used. Specifically it depends on the +requirements the context places on the value type of the Range. +The reference type of the Range 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, +equivalent to the value type objects in the Range (which is +trivially true if they are the same). Also, in a mutable Range, an assignment to the reference object must result in an assignment to -the object in the Collection (again, which is trivially true if they +the object in the Range (again, which is trivially true if they are the same object, but non-trivial if the reference type is a proxy class). -

See also

-Container - -
+

+
+
-For any Collection a, [a.begin(), a.end()) is a valid +For any Range a, [a.begin(), a.end()) is a valid range.
Copyright © 2000 diff --git a/doc/style.css b/doc/style.css new file mode 100755 index 0000000..52f82f1 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,23 @@ +pre{ + BORDER-RIGHT: gray 1pt solid; + PADDING-RIGHT: 2pt; + BORDER-TOP: gray 1pt solid; + DISPLAY: block; + PADDING-LEFT: 2pt; + PADDING-BOTTOM: 2pt; + BORDER-LEFT: gray 1pt solid; + MARGIN-RIGHT: 32pt; + PADDING-TOP: 2pt; + BORDER-BOTTOM: gray 1pt solid; + FONT-FAMILY: "Courier New", Courier, mono; + background-color: #EEEEEE; +} + + +.keyword{color: #0000FF;} +.identifier{} +.comment{font-style: italic; color: #008000;} +.special{color: #800040;} +.preprocessor{color: #3F007F;} +.string{font-style: italic; color: #666666;} +.literal{font-style: italic; color: #666666;} diff --git a/doc/utility_class.html b/doc/utility_class.html new file mode 100644 index 0000000..637cfad --- /dev/null +++ b/doc/utility_class.html @@ -0,0 +1,201 @@ + + + + + +Boost.Range Utility Classes + + + + + + + + + +
+

Boost.Range utility classes

+
+ +

+ +

Having an abstraction that encapsulates a pair of iterators is very + useful. The standard library uses std::pair in some +cercumstances, but that class is cumbersome to use because we need to +specify two template arguments, and for all range algorithm purposes, +we must enforce the two template arguments to be the same. Moreover, +std::pair<iterator,iterator> is hardly self-documenting +whereas more domain specific class names are. Therefore these two +classes are provided: + +

+ + +The iterator_range class is templated on an iterator and should be +used whenever super general code is needed. The sub_range class +is templated on an ExternalRange +and it is less general, but a bit easier to use since its template argument +is easier to specify. +

+ +

iterator_range

+ + The intention of the +iterator_range class is to encapsulate +two iterators so they fulfill the Range concept. +A few other functions are also provided for convinience. + +

Synopsis

+ +
+namespace boost
+{
+    template< class Iterator > 
+    class iterator_range
+    {
+        iterator_range(); // not implemented
+        
+    public: // Range types
+        typedef ...        value_type;
+        typedef ...        difference_type;
+        typedef ...        size_type;
+        typedef Iterator   iterator;        
+        typedef Iterator   const_iterator;
+
+    public: // construction, assignment
+        template< class Iterator >
+        iterator_range( Iterator Begin, Iterator End );
+                    
+        template< class XRange >
+        iterator_range( XRange& r ); 
+  
+        template< class XRange >
+        iterator_range( const XRange& r ); 
+        
+        template< class XRange >
+        iterator_range& operator=( XRange& r );
+
+        template< class XRange >
+        iterator_range& operator=( const XRange& r );
+    
+    public: // Range functions
+        iterator  begin() const; 
+        iterator  end() const; 
+        size_type size() const;
+        bool      empty() const;
+        
+    public: // convenience
+        operator  unspecified_bool_type() const;
+        void      swap( iterator_range& r );
+    };
+    
+    // stream output
+    template< class Iterator, class T, class Traits >
+    std::basic_ostream<T,Traits>& operator<<( std::basic_ostream<T,Traits>& Os,
+                                              const iterator_range<Iterator>& r );
+
+    // comparison
+    template< class Iterator > 
+    bool operator==( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );
+    
+    template< class Iterator > 
+    bool operator!=( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );
+
+    // external construction
+    template< class Iterator >
+    iterator_range< Iterator > 
+    make_iterator_range( Iterator Begin, Iterator End ); 
+       
+    template< class XRange >
+    iterator_range< typename iterator_of<XRange>::type >
+    make_iterator_range( XRange& r ); 
+
+    template< class XRange >
+    iterator_range< typename const_iterator_of<XRange>::type >
+    make_iterator_range( const XRange& r ); 
+
+    // convenience
+    template< class Sequence, class XRange >
+    Sequence copy_range( const XRange& r )
+
+    template< class Sequence, class XRange, class Func >
+    Sequence transform_range( const XRange& r, Func func );
+
+} // namespace 'boost'
+
+ +

+It is worth noticing that the templated constructors and assignment operators +allow conversion from iterator_range to +iterator_range. If an instance of +iterator_range is constructed by a client with two iterators, the +client must ensure that the two iterators delimit a valid closed-open range +[begin,end). + +

+ +
+

sub_range

+ +The sub_range class inherits all its functionality +from the iterator_range class. +The sub_range class is often easier to use because +one must specify the ExternalRange +template argument instead of an iterator. + +

Synopsis

+ +
+namespace boost
+{
+    
+    template< class XRange > 
+    class sub_range : public iterator_range< typename result_iterator_of<XRange>::type > 
+    {
+    public: // construction, assignment
+        template< class Iterator >
+        sub_range( Iterator Begin, Iterator End );
+
+        template< class XRange2 >
+        sub_range( XRange2& r );
+         
+        template< class XRange2 >
+        sub_range( const Range2& r );
+         
+        template< class XRange2 >
+        sub_range& operator=( XRange2& r );
+
+        template< class XRange2 >
+        sub_range& operator=( const XRange2& r );
+        
+    public:
+        // rest of interface inherited from iterator_range
+    };
+    
+} // namespace 'boost'
+
+
+ +
+

+ (C) Copyright Thorsten Ottosen 2003-2004 +

+ +
+
+
+
+
+
+
+
+
+
+
+
+ + + + diff --git a/index.html b/index.html index 5a83ab6..2bf64b7 100755 --- a/index.html +++ b/index.html @@ -1,8 +1,95 @@ - Collection Traits - - - - + + + + + +Boost.Range Documentation + + + + + + + + + +
+

Range Library

+
+ +

+ Copyright © 2003-2004 Thorsten Ottosen +

+

+ Use, modification and distribution is subject to the Boost Software License, Version 1.0 + (see + http://www.boost.org/LICENSE_1_0.txt). +

+ +

Overview

+

+ Boost.Range is a collection of concepts and utilities that are particularly + useful for specifying and implementing generic algorithms. The documentation + consists of the following sections: +

+ +
    +
  • Introduction + +
  • Concepts: +
      +
    • Range +
    • ReversibleRange +
    • ExternalRange +
    • ExternalReversibleRange +
    + +
  • Implementation of ExternalReversibleRange for +
      +
    • arrays +
    • Ranges +
    • strings +
    • pairs of iterators +
    + +
  • Utility classses: + + +
  • + Utility functions: +
      +
    • make_iterator_range() +
    • copy_range() +
    • transform_range() +
    +
  • Style and terminology guidelines +
  • Headers
    • + +
+ +
+

+ (C) Copyright Thorsten Ottosen 2003-2004 +

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