Boost.Range terminology and style guidelines

The use of a consistent terminologi is as important for iterator Ranges and ExternalRange-based algorithms as it is for iterators and iterator-based algorithms. If a conventional set of names are adopted, we can avoid misunderstandings and write generic function prototypes that are self-documenting.

Since iterator ranges are characterized by a specific underlying iterator type, we get a type of iterator range for each type of iterator. Hence we can speak of the following types of iterator ranges:

Range
ReversibleRange
Value access category:
- ReadableRange
- WriteableRange
- SwappableRange
- LvalueRange
Traversal category:
- IncrementableRange
- SinglePassRange
- ForwardRange
- BidirectionalRange
- RandomAccessRange

Notice how we have used the categories from the new style iterators. Similarly, for ExternalRange we have

XRange
XReversibleRange
Value access category:
- XReadableRange
- XWriteableRange
- XSwappableRange
- XLvalueRange
Traversal category:
- XIncrementableRange
- XSinglePassRange
- XForwardRange
- XBidirectionalRange
- XRandomAccessRange

The convention of using an X to mean "External" save us from rediculously long parameter names and is easy to associate with an external concept.

Notice that an interator (and therefore an iterator range) has one traversal property and one or more properties from the value access category. So in reality we will mostly talk about mixtures such as

RandomAccessReadableWriteableRange
XForwardLvalueRange

By convention, we should always specify the travelsal property first as done above. This seems resonable since there will only be one traversal property, but perhaps many value acccess properties.

As an example, consider how we specify the interface of std::sort(). The iterator-based version looks like this:

   template< class RandomAccessTraversalReadableWritableIterator >
   void sort( RandomAccessTraversalReadableWritableIterator first,
              RandomAccessTraversalReadableWritableIterator last );

For external iterator ranges the interface becomes

   template< class XRandomAccessReadableWritableRange >
   void sort( XRandomAccessReadableWritableRange& r );

Had the function been specified like

   template< class RandomAccessReadableWritableRange >
   void sort( RandomAccessReadableWritableRange& r );

we should expect the underlying code to call r.begin() and r.end() to extract the iterators instead of begin( r ) and end( r ). In general it is much more flexible to rely on external iterator ranges than iterator ranges.