<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Range Library Proposal</title>
<meta name="author" content="Thorsten Ottosen" />
<meta name="date" content="2005-08-27" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2004/01/12 02:49:54 $
:version: $Revision: 1.2 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
*/

.first {
  margin-top: 0 }

.last {
  margin-bottom: 0 }

a.toc-backref {
  text-decoration: none ;
  color: black }

dd {
  margin-bottom: 0.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 0em 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.citation {
  border-left: solid thin gray ;
  padding-left: 0.5ex }

table.docinfo {
  margin: 2em 4em }

table.footnote {
  border-left: solid thin black ;
  padding-left: 0.5ex }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

th.docinfo-name, th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }
  
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: #000000;}
.strike { text-decoration: line-through }
.u { text-decoration: underline }

</style>
</head>
<body>
<div class="document" id="range-library-proposal">
<h1 class="title">Range Library Proposal</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Thorsten Ottosen</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:nesotto&#64;cs.aau.dk">nesotto&#64;cs.aau.dk</a></td></tr>
<tr class="field"><th class="docinfo-name">organizations:</th><td class="field-body"><a class="reference" href="http://www.dezide.com">Dezide Aps</a> and <a class="reference" href="http://www.cs.aau.dk">Aalborg University</a></td>
</tr>
<tr><th class="docinfo-name">Date:</th>
<td>2005-08-27</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">WG21/N1871 and J16/05-0131</td>
</tr>
<tr class="field"><th class="docinfo-name">Working Group:</th><td class="field-body">(R)Evolution</td>
</tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>This paper proposes the addition of ranges
to the C++ standard library to reduce the syntactic burden
on programmers. The paper also considers a number of
range related utilities that can greatly simplify the use of
algorithms and loops.</p>
</div>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#motivation" id="id16" name="id16">1&nbsp;&nbsp;&nbsp;Motivation</a><ul class="auto-toc">
<li><a class="reference" href="#what-is-a-range" id="id17" name="id17">1.1&nbsp;&nbsp;&nbsp;What is a range?</a></li>
<li><a class="reference" href="#advantages" id="id18" name="id18">1.2&nbsp;&nbsp;&nbsp;Advantages</a></li>
</ul>
</li>
<li><a class="reference" href="#related-information-and-overview" id="id19" name="id19">2&nbsp;&nbsp;&nbsp;Related information and overview</a></li>
<li><a class="reference" href="#basic-range-infrastructure-part-1" id="id20" name="id20">3&nbsp;&nbsp;&nbsp;Basic range infrastructure (Part 1)</a><ul class="auto-toc">
<li><a class="reference" href="#range-concepts" id="id21" name="id21">3.1&nbsp;&nbsp;&nbsp;Range concepts</a></li>
<li><a class="reference" href="#synopsis-1" id="id22" name="id22">3.2&nbsp;&nbsp;&nbsp;Synopsis (1)</a></li>
<li><a class="reference" href="#specification-1" id="id23" name="id23">3.3&nbsp;&nbsp;&nbsp;Specification (1)</a></li>
<li><a class="reference" href="#discussion" id="id24" name="id24">3.4&nbsp;&nbsp;&nbsp;Discussion</a></li>
</ul>
</li>
<li><a class="reference" href="#additions-to-existing-library-components-part-2" id="id25" name="id25">4&nbsp;&nbsp;&nbsp;Additions to existing library components (Part 2)</a><ul class="auto-toc">
<li><a class="reference" href="#overloaded-algorithms" id="id26" name="id26">4.1&nbsp;&nbsp;&nbsp;Overloaded algorithms</a><ul class="auto-toc">
<li><a class="reference" href="#algorithm-and-numeric" id="id27" name="id27">4.1.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;numeric&gt;</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#new-member-functions" id="id28" name="id28">4.2&nbsp;&nbsp;&nbsp;New member functions</a></li>
<li><a class="reference" href="#tr1-and-other-proposals" id="id29" name="id29">4.3&nbsp;&nbsp;&nbsp;Tr1 and other proposals</a></li>
<li><a class="reference" href="#id9" id="id30" name="id30">4.4&nbsp;&nbsp;&nbsp;Discussion</a></li>
</ul>
</li>
<li><a class="reference" href="#range-utilities-part-3" id="id31" name="id31">5&nbsp;&nbsp;&nbsp;Range utilities (Part 3)</a><ul class="auto-toc">
<li><a class="reference" href="#range" id="id32" name="id32">5.1&nbsp;&nbsp;&nbsp;Range</a><ul class="auto-toc">
<li><a class="reference" href="#synopsis" id="id33" name="id33">5.1.1&nbsp;&nbsp;&nbsp;Synopsis</a></li>
<li><a class="reference" href="#specification" id="id34" name="id34">5.1.2&nbsp;&nbsp;&nbsp;Specification</a></li>
</ul>
</li>
<li><a class="reference" href="#sub-range" id="id35" name="id35">5.2&nbsp;&nbsp;&nbsp;Sub_range</a><ul class="auto-toc">
<li><a class="reference" href="#id10" id="id36" name="id36">5.2.1&nbsp;&nbsp;&nbsp;Synopsis</a></li>
<li><a class="reference" href="#id11" id="id37" name="id37">5.2.2&nbsp;&nbsp;&nbsp;Specification</a></li>
</ul>
</li>
<li><a class="reference" href="#id12" id="id38" name="id38">5.3&nbsp;&nbsp;&nbsp;Discussion</a></li>
</ul>
</li>
<li><a class="reference" href="#range-adapters-part-4" id="id39" name="id39">6&nbsp;&nbsp;&nbsp;Range adapters (Part 4)</a><ul class="auto-toc">
<li><a class="reference" href="#id14" id="id40" name="id40">6.1&nbsp;&nbsp;&nbsp;Specification</a></li>
<li><a class="reference" href="#id15" id="id41" name="id41">6.2&nbsp;&nbsp;&nbsp;Discussion</a></li>
</ul>
</li>
<li><a class="reference" href="#acknowledgements" id="id42" name="id42">7&nbsp;&nbsp;&nbsp;Acknowledgements</a></li>
</ul>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id16" name="motivation">1&nbsp;&nbsp;&nbsp;Motivation</a></h1>
<div class="section" id="what-is-a-range">
<h2><a class="toc-backref" href="#id17" name="what-is-a-range">1.1&nbsp;&nbsp;&nbsp;What is a range?</a></h2>
<p>A range is simply an encapsulation
of two iterators. The term range is due to paragraph 24.1/7 from the C++ standard:</p>
<blockquote>
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 <tt class="docutils literal"><span class="pre">[i,</span> <span class="pre">i)</span></tt> is an empty range; in general, a range <tt class="docutils literal"><span class="pre">[i,</span> <span class="pre">j)</span></tt> refers to
the elements in the data structure starting with the one pointed to by <tt class="docutils literal"><span class="pre">i</span></tt>
and up to but not including the one pointed to by <tt class="docutils literal"><span class="pre">j</span></tt>. Range <tt class="docutils literal"><span class="pre">[i,</span> <span class="pre">j)</span></tt> is valid if
and only if <tt class="docutils literal"><span class="pre">j</span></tt> is reachable from <tt class="docutils literal"><span class="pre">i</span></tt>. 
The result of the application of functions in the library to invalid ranges is undefined.</blockquote>
</div>
<div class="section" id="advantages">
<h2><a class="toc-backref" href="#id18" name="advantages">1.2&nbsp;&nbsp;&nbsp;Advantages</a></h2>
<p>Even though standard algorithms are specified in terms of iterator ranges,
they are still somewhat clumsy to use. By combining the two iterators into
one object, we can achieve great benefits. This proposal 
will give standard C++</p>
<blockquote>
<ol class="arabic simple">
<li>a drastic reduction in syntactic overhead,</li>
</ol>
</blockquote>
<!--  -->
<blockquote>
<ol class="arabic simple" start="2">
<li>an infrastructure for range-based algorithms
(which can also be used for the new <tt class="docutils literal"><span class="pre">for</span></tt>-loop (see <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1868.html">n1868</a>)),</li>
</ol>
</blockquote>
<!--  -->
<blockquote>
<ol class="arabic simple" start="3">
<li>a new concise idiomatic use of algorithms and loops,</li>
</ol>
</blockquote>
<!--  -->
<blockquote>
<ol class="arabic simple" start="4">
<li>safer use of built-in arrays.</li>
</ol>
</blockquote>
<p>The next example shows how slick and functional the 
syntax becomes with use of ranges:</p>
<pre class="literal-block">
vector&lt;int&gt; integers;

// old style
typedef vector&lt;int&gt;::iterator iterator;
pair&lt;iterator,iterator&gt; p = equal_range( integers.begin(), integers.end(), 0 );
for_each( p.first, p.second, some_functor() );

// new style
for_each( equal_range(integers, 0), some_functor() );
</pre>
<p>The latter approach won't give you Cobol-fingers.</p>
<p>The range infrastructure consists of free-standing traits and functions
that enable easy support of UDTs. Some of the functions have been separately
suggested in Walter Browns proposal (see <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1674.pdf">n1674</a>).</p>
<p>A set of range adapters and overloaded operators
make it a dream to use standard algorithms. Just consider
the following example:</p>
<pre class="literal-block">
std::vector&lt;int*&gt; ptr_vec = ...;

std::copy( ptr_vec | std::reversed | std::indirected,
           std::ostream_iterator&lt;int&gt;( std::cout ) );
</pre>
<p>The expression <tt class="docutils literal"><span class="pre">ptr_vec</span> <span class="pre">|</span> <span class="pre">std::reverse</span> <span class="pre">|</span> <span class="pre">std::indirect</span></tt>
extracts the <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> iterators from <tt class="docutils literal"><span class="pre">ptr_vec</span></tt>
and then wraps those iterators in (1) <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt>s
and (2) <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt>s. The result of the expression
is then a range holding these wrapped iterators---that range
is then passed to a new overload of <tt class="docutils literal"><span class="pre">std::copy()</span></tt> that
accepts a range as its first argument. Accomplishing the 
same without the range abstractions takes quite some
work.</p>
</div>
</div>
<div class="section" id="related-information-and-overview">
<h1><a class="toc-backref" href="#id19" name="related-information-and-overview">2&nbsp;&nbsp;&nbsp;Related information and overview</a></h1>
<p>This proposal is based on <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost.Range</a> which has been
successfully used in many contexts. For example,
the following libraries use <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost.Range</a> as their
infrastructure:</p>
<ul class="simple">
<li><a class="reference" href="http://www.boost.org/doc/html/string_algo.html">Boost.StringAlgo</a> (Part of Boost since 1.32)</li>
</ul>
<!--  -->
<ul class="simple">
<li>Boost.ForEach (Accepted into Boost, but not yet part of the release)</li>
</ul>
<!--  -->
<ul class="simple">
<li>Adope's Open Source <a class="reference" href="http://opensource.adobe.com/group__algorithm.html">Algorithms</a></li>
</ul>
<p>Furthermore, the library is also used in other Boost libraries
like Boost.IOStreams, Boost.PtrContainer and Boost.Assign.</p>
<p>As said before, this proposal incorporates Walter Browns
paper <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1674.pdf">n1674</a>.</p>
<p>The range adapters in this proposal can be
implemented with the new iterator 
adapter library as described in</p>
<ul class="simple">
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1640.html">n1640</a></li>
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1641.html">n1641</a></li>
</ul>
<p>but this is not a requirement.</p>
<!-- Furthermore, some of the new iterator traits -->
<!-- a used in core functionality (see `Part 1`__). -->
<!--  -->
<!-- `Basic range infrastructure (Part 1)`_ -->
<p>There has been some recent work on
ranges by John Torjo and Matthew Wilson.
Their library may be seen here</p>
<ul class="simple">
<li><a class="reference" href="http://www.torjo.com/rangelib/index.html">Iterable Range Library</a></li>
</ul>
<p>A couple
of <a class="reference" href="http://www.torjo.com/rangelib/index.html#articles">articles</a> appeared in CUJ on the topic 
too.</p>
<p>This proposal deviates a little from
the current Boost.Range, and it will
be said explicitly when there is a 
difference.</p>
<p>The proposal is divided into four
parts:</p>
<ul class="simple">
<li><a class="reference" href="#basic-range-infrastructure-part-1">Part 1</a> is the core infrastructure.
This is also needed for the new for-loop.</li>
</ul>
<ul class="simple">
<li><a class="reference" href="#additions-to-existing-library-components-part-2">Part 2</a> suggests minor additions to existing
library components to take advantage of the
new infrastructure.</li>
</ul>
<ul class="simple">
<li><a class="reference" href="#range-utilities-part-3">Part 3</a> consists of a few simple helper classes.</li>
</ul>
<ul class="simple">
<li><a class="reference" href="#range-adapters-part-4">Part 4</a> is a powerful (yet simple) set of
range adapters which make programming a dream.</li>
</ul>
<p>I have taken the liberty to let the
proposal depend on two new core-language
changes:</p>
<ul class="simple">
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1794.pdf">n1794</a> and <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1705.pdf">n1705</a> (<tt class="docutils literal"><span class="pre">auto</span></tt>/<tt class="docutils literal"><span class="pre">decltype</span></tt>)</li>
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1770.html">n1770</a> (move-semantics)</li>
</ul>
<p>This <em>greatly</em> simplifies the specification
of this proposal.</p>
<p>A few other proposals depend on the core 
functionality of this proposal:</p>
<ul class="simple">
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1872.html">n1872</a> (new string algorithms)</li>
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1868.html">n1868</a> (new <tt class="docutils literal"><span class="pre">for</span></tt>-loop)</li>
</ul>
</div>
<div class="section" id="basic-range-infrastructure-part-1">
<h1><a class="toc-backref" href="#id20" name="basic-range-infrastructure-part-1">3&nbsp;&nbsp;&nbsp;Basic range infrastructure (Part 1)</a></h1>
<p>The basic elements of the library consists of
typetraits and freestanding functions.</p>
<ul class="simple">
<li><a class="reference" href="#range-concepts">range concepts</a></li>
<li><a class="reference" href="#synopsis-1">synopsis (1)</a></li>
<li><a class="reference" href="#specification-1">specification (1)</a></li>
</ul>
<div class="section" id="range-concepts">
<h2><a class="toc-backref" href="#id21" name="range-concepts">3.1&nbsp;&nbsp;&nbsp;Range concepts</a></h2>
<p>This section briefly introduces range
concepts. A range concept has two components:</p>
<ol class="arabic simple">
<li>the traversal type of its associated iterators</li>
</ol>
<!--  -->
<ol class="arabic simple" start="2">
<li>whether the range is copyable and owns the elements
it provides iteration over</li>
</ol>
<p>A range is assume to be noncopyable unless otherwise
specified.</p>
<p>We thus talk about the following types of ranges</p>
<ul class="simple">
<li>SinglePassRange</li>
<li>ForwardRange</li>
<li>BidirectionalRange</li>
<li>RandomAccessRange</li>
</ul>
<p>All expressions <tt class="docutils literal"><span class="pre">rng</span></tt> whose type models a range 
can be used as arguments to the three freestanding
functions</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">begin(rng)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">end(rng)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">empty(rng)</span></tt></li>
</ul>
<p>In addition, for an expression whose type models a 
ForwardRange we can say</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">size(rng)</span></tt></li>
</ul>
<p>A CopyableRange owns the elements in the range
and has a deep-copy copy-constructor.</p>
<p><strong>See also</strong></p>
<ul class="simple">
<li>Boost.Range <a class="reference" href="http://www.boost.org/libs/range/doc/range.html">concepts</a></li>
<li><a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1640.html">n1640</a> (new iterator concepts)</li>
</ul>
</div>
<div class="section" id="synopsis-1">
<h2><a class="toc-backref" href="#id22" name="synopsis-1">3.2&nbsp;&nbsp;&nbsp;Synopsis (1)</a></h2>
<p>Add the following to the <tt class="docutils literal"><span class="pre">&lt;iterator&gt;</span></tt> header
(in namespace <tt class="docutils literal"><span class="pre">std</span></tt>):</p>
<pre class="literal-block">
template&lt; class T &gt;
auto begin( T&amp;&amp; t ) -&gt; decltype( t.begin() );

template&lt; class T &gt;
T begin( const pair&lt;T,T&gt;&amp; p );
    
template&lt; class T, size_t N &gt;
T* begin( T (&amp;a)[N] );

template&lt; class T &gt;
auto end( T&amp;&amp; t ) -&gt; decltype( t.end() );

template&lt; class T &gt;
T end( const pair&lt;T,T&gt;&amp; p );
    
template&lt; class T, size_t N &gt;
T* end( T (&amp;a)[N] );

template&lt; class T &gt;
bool empty( const T&amp; t );
 
template&lt; class T &gt;
auto size( const T&amp; t ) -&gt; decltype( t.size() );

template&lt; class T &gt;
typename iterator_traits&lt;T&gt;::size_type size( const pair&lt;T,T&gt;&amp; p );
    
template&lt; class T, size_t N &gt;
size_t size( const T (&amp;a)[N] );

template&lt; class T &gt;
struct range_iterator; 

template&lt; class T &gt;
struct range_reverse_iterator;

template&lt; class T &gt;
struct range_value;
             
template&lt; class T &gt;
struct range_difference;

template&lt; class T &gt;
struct range_size;

template&lt; class T &gt;
typename range_reverse_iterator&lt;T&gt;::type rbegin( T&amp;&amp; t );

template&lt; class T &gt;
auto rend( T&amp;&amp; t ) -&gt; decltype( rbegin(t) );
    
template&lt; class T &gt;
typename range_iterator&lt;const T&gt;::type const_begin( const T&amp; t );

template&lt; class T &gt;
auto const_end( const T&amp; t ) -&gt; decltype( const_begin(t) );

template&lt; class T &gt;
typename range_reverse_iterator&lt;const T&gt;::type const_rbegin( const T&amp; t );
    
template&lt; class T &gt;
auto const_rend( const T&amp; t ) -&gt; decltype( const_rbegin(t) );
</pre>
</div>
<div class="section" id="specification-1">
<h2><a class="toc-backref" href="#id23" name="specification-1">3.3&nbsp;&nbsp;&nbsp;Specification (1)</a></h2>
<p>In the following <tt class="docutils literal"><span class="pre">ptr</span></tt> is a variable
of type <tt class="docutils literal"><span class="pre">T*</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">begin(</span> <span class="pre">T&amp;&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">t.begin()</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">t.begin()</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">T</span> <span class="pre">begin(</span> <span class="pre">const</span> <span class="pre">pair&lt;T,T&gt;&amp;</span> <span class="pre">p</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">p.first</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">size_t</span> <span class="pre">N</span> <span class="pre">&gt;</span>
<span class="pre">T*</span> <span class="pre">begin(</span> <span class="pre">T</span> <span class="pre">(&amp;a)[N]</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">a</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">end(</span> <span class="pre">T&amp;&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">t.end()</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">t.end()</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">T</span> <span class="pre">end(</span> <span class="pre">const</span> <span class="pre">pair&lt;T,T&gt;&amp;</span> <span class="pre">p</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">p.second</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">size_t</span> <span class="pre">N</span> <span class="pre">&gt;</span>
<span class="pre">T*</span> <span class="pre">end(</span> <span class="pre">T</span> <span class="pre">(&amp;a)[N]</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">N</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">empty(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">begin(t)</span> <span class="pre">==</span> <span class="pre">end(t)</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">size(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">t.size()</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">t.size()</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">typename</span> <span class="pre">iterator_traits&lt;T&gt;::size_type</span> <span class="pre">size(</span> <span class="pre">const</span> <span class="pre">pair&lt;T,T&gt;&amp;</span> <span class="pre">p</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">distance(p.first,p.second)</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">size_t</span> <span class="pre">N</span> <span class="pre">&gt;</span>
<span class="pre">size_t</span> <span class="pre">size(</span> <span class="pre">const</span> <span class="pre">T</span> <span class="pre">(&amp;a)[N]</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">N</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">struct</span> <span class="pre">range_iterator;</span></tt></p>
<ul class="simple">
<li>description: A TransformationTrait that defines the
iterator of a range</li>
<li>definition of <tt class="docutils literal"><span class="pre">type</span></tt>: <tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">decltype(</span> <span class="pre">begin(*ptr)</span> <span class="pre">)</span> <span class="pre">type;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">struct</span> <span class="pre">range_reverse_iterator;</span></tt></p>
<ul class="simple">
<li>description: A TransformationTrait that defines the
reverse iterator of a range</li>
<li>definition of <tt class="docutils literal"><span class="pre">type</span></tt>: <tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">reverse_iterator&lt;</span> <span class="pre">typename</span> <span class="pre">range_iterator&lt;T&gt;:type</span> <span class="pre">&gt;</span> <span class="pre">type;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">struct</span> <span class="pre">range_value;</span></tt></p>
<ul class="simple">
<li>description: A TransformationTrait that defines the
value type of the iterators of a range</li>
<li>definition of <tt class="docutils literal"><span class="pre">type</span></tt>: <tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">typename</span> <span class="pre">iterator_traits&lt;</span> <span class="pre">typename</span> <span class="pre">range_iterator&lt;T&gt;::type</span> <span class="pre">&gt;::value_type</span> <span class="pre">type;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">struct</span> <span class="pre">range_difference;</span></tt></p>
<ul class="simple">
<li>description: A TransformationTrait that defines the
difference type of the iterators of a range</li>
<li>definition of <tt class="docutils literal"><span class="pre">type</span></tt>: <tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">typename</span> <span class="pre">iterator_traits&lt;</span> <span class="pre">decltype(</span> <span class="pre">begin(*ptr)</span> <span class="pre">)</span> <span class="pre">&gt;::difference_type</span> <span class="pre">type;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">struct</span> <span class="pre">range_size;</span></tt></p>
<ul class="simple">
<li>description: A TransformationTrait that defines the
size type of the iterators of a range</li>
<li>definition of <tt class="docutils literal"><span class="pre">type</span></tt>: <tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">decltype(</span> <span class="pre">size(*ptr)</span> <span class="pre">)</span> <span class="pre">type;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">typename</span> <span class="pre">range_reverse_iterator&lt;T&gt;::type</span> <span class="pre">rbegin(</span> <span class="pre">T&amp;&amp;</span> <span class="pre">t</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">decltype(</span> <span class="pre">rbegin(t)</span> <span class="pre">)(end(t))</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">rend(</span> <span class="pre">T&amp;&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">rbegin(t)</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">decltype(</span> <span class="pre">rbegin(t)</span> <span class="pre">)(begin(t))</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">typename</span> <span class="pre">range_iterator&lt;const</span> <span class="pre">T&gt;::type</span> <span class="pre">const_begin(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">begin(t)</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">const_end(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">const_begin(t)</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">end(t)</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">typename</span> <span class="pre">range_reverse_iterator&lt;const</span> <span class="pre">T&gt;::type</span> <span class="pre">const_rbegin(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">rbegin(t)</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">const_rend(</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">t</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">decltype(</span> <span class="pre">const_rbegin(t)</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li>returns: <tt class="docutils literal"><span class="pre">rend(t)</span></tt></li>
</ul>
</div>
<div class="section" id="discussion">
<h2><a class="toc-backref" href="#id24" name="discussion">3.4&nbsp;&nbsp;&nbsp;Discussion</a></h2>
<ol class="arabic">
<li><p class="first">The above TransformationTraits differ slightly
from those currently in Boost.Range. In particular,
Boost.Range had both <tt class="docutils literal"><span class="pre">range_iterator</span></tt> and 
<tt class="docutils literal"><span class="pre">range_const_iterator</span></tt> which were <em>unaffected</em> by
the const-ness of the template argument. Expericence
showed, however, that you rarely want the iterator
not to follow the constness of the argument and so
the two traits have been combined into one.
(The same comment applies to <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt>).</p>
</li>
<li><p class="first">Boost.Range currently treats arrays and character arrays differently,
but that functionality has been deprecated and is therefore not
part of this proposal. After lengthy discussion on the Boost Dev. list,
it was decided that this functionality was actually a problem in generic
code.</p>
</li>
<li><p class="first">In a discussion on the Boost Dev. list, the names <tt class="docutils literal"><span class="pre">const_begin()/const_end()</span></tt>
and <tt class="docutils literal"><span class="pre">const_rbegin()/const_rend()</span></tt> were preferred
to the names <tt class="docutils literal"><span class="pre">cbegin()/cend()</span></tt> and <tt class="docutils literal"><span class="pre">crbegin()/crend()</span></tt>
suggested by Walter Brown in <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1674.pdf">n1674</a>.</p>
</li>
<li><p class="first">The core functionality means that the following types
conforms to the range concept:</p>
<ul class="simple">
<li>standard containers (including <tt class="docutils literal"><span class="pre">tr1::array</span></tt>)</li>
<li>pairs of iterators</li>
<li>built-in arrays</li>
</ul>
<p>One might consider supporting additional types like tuples.</p>
</li>
<li><p class="first">If the use of the TransformationTraits seems to verbose,
we might consider abbreviation like:</p>
<pre class="literal-block">
namespace rng
{ 
    template&lt; class T &gt;
    using iterator = typename range_iterator&lt;T&gt;::type;
}
</pre>
<p>using template aliases.</p>
</li>
<li><p class="first">Should we add a <tt class="docutils literal"><span class="pre">range_category</span></tt> TransformationTrait?</p>
</li>
</ol>
</div>
</div>
<div class="section" id="additions-to-existing-library-components-part-2">
<h1><a class="toc-backref" href="#id25" name="additions-to-existing-library-components-part-2">4&nbsp;&nbsp;&nbsp;Additions to existing library components (Part 2)</a></h1>
<div class="section" id="overloaded-algorithms">
<h2><a class="toc-backref" href="#id26" name="overloaded-algorithms">4.1&nbsp;&nbsp;&nbsp;Overloaded algorithms</a></h2>
<div class="section" id="algorithm-and-numeric">
<h3><a class="toc-backref" href="#id27" name="algorithm-and-numeric">4.1.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt> and <tt class="docutils literal docutils literal"><span class="pre">&lt;numeric&gt;</span></tt></a></h3>
<p>For all iterator-based
algorithms it is proposed to add additional
overloads that take a range whenever two
iterators is expected. For quite some algorithms
(e.g. <tt class="docutils literal"><span class="pre">adjacent_find()</span></tt>, <tt class="docutils literal"><span class="pre">mismatch()</span></tt>, <tt class="docutils literal"><span class="pre">equal()</span></tt>, <tt class="docutils literal"><span class="pre">search_n()</span></tt> etc.)
this will lead to ambiguities in a language
without concepts. Therefore it is suggested that the
overloaded algorithms are provided in namespace <tt class="docutils literal"><span class="pre">std::rng</span></tt>
(see also this <a class="reference" href="#rng-discussion">discussion</a>).</p>
<p>The following should be added to chapter 17:</p>
<blockquote>
<p>For all iterator based algorithms described in 20.4.4, 25.1-3 and 26.4 it
holds that</p>
<blockquote>
<ul>
<li><p class="first">for all algorithms of the form:</p>
<pre class="literal-block">
template&lt; class Iterator, ... &gt; 
return-type algo( Iterator first, Iterator last, ... )
</pre>
<p>a range-based version is placed in namespace <tt class="docutils literal"><span class="pre">std::rng</span></tt> of the form:</p>
<pre class="literal-block">
template&lt; class Range, ... &gt;
return-type algo( Range&amp;&amp; r, ... )
</pre>
</li>
</ul>
</blockquote>
<p>which forwards to the algorithm in namespace <tt class="docutils literal"><span class="pre">std</span></tt> using unqualified calls to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>. (<strong>Remark</strong>: the return type specified with <tt class="docutils literal"><span class="pre">return-type</span></tt> the same in both the iterator-based and the range-based functions.)</p>
<blockquote>
<ul>
<li><p class="first">for all algorithms of the form:</p>
<pre class="literal-block">
template&lt; class Iterator, class Iterator2, ... &gt;
return-type algo( Iterator first, Iterator last, Iterator2 first2, Iterator2 last2, ... )
</pre>
<p>a range-based version is placed in namespace <tt class="docutils literal"><span class="pre">std::rng</span></tt> of the form:</p>
<pre class="literal-block">
template&lt; class Range, class Range2, ... &gt;
return-type algo( Range&amp;&amp; r, Range2&amp;&amp; r2, ... )
</pre>
<p>which forwards to the algorithm in namespace <tt class="docutils literal"><span class="pre">std</span></tt> using unqualified calls
to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>.</p>
</li>
</ul>
</blockquote>
<p>For range-based algorithms described above it
holds that</p>
<blockquote>
<ul>
<li><p class="first">for all algorithms taking an output iterator of the form</p>
<pre class="literal-block">
template&lt; ..., class OutIter, ... &gt;
return-type algo( ..., OutIter, ... )
</pre>
<p>a range-based version of the form:</p>
<pre class="literal-block">
template&lt; class Sequence, ... &gt;
CopyableRange algo( ... )
</pre>
<p>is added.</p>
</li>
</ul>
</blockquote>
</blockquote>
</div>
</div>
<div class="section" id="new-member-functions">
<h2><a class="toc-backref" href="#id28" name="new-member-functions">4.2&nbsp;&nbsp;&nbsp;New member functions</a></h2>
<p>For the classes <tt class="docutils literal"><span class="pre">basic_string</span></tt>,
<tt class="docutils literal"><span class="pre">deque</span></tt>, <tt class="docutils literal"><span class="pre">list</span></tt>, <tt class="docutils literal"><span class="pre">vector</span></tt>, <tt class="docutils literal"><span class="pre">map</span></tt>, <tt class="docutils literal"><span class="pre">multimap</span></tt>, <tt class="docutils literal"><span class="pre">set</span></tt>
and <tt class="docutils literal"><span class="pre">multiset</span></tt> it holds that</p>
<blockquote>
<ul>
<li><p class="first">the following new members are added:</p>
<pre class="literal-block">
const_iterator         const_begin() const;
const_iterator         const_end() const;
const_reverse_iterator const_rbegin() const; 
const_reverse_iterator const_rend() const;   
</pre>
</li>
<li><p class="first">for all member-functions of the form:</p>
<pre class="literal-block">
template&lt; class Iterator &gt; 
return-type fun( Iterator first, Iterator last )
</pre>
<p>a range-based version is added of the form:</p>
<pre class="literal-block">
template&lt; class Range &gt;
return-type fun( const Range&amp; r )
</pre>
<p>which forwards to the iterator-based
version via unqualified calls to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>.</p>
</li>
<li><p class="first">for all member-functions of the form:</p>
<pre class="literal-block">
template&lt; class Iterator &gt; 
return-type fun( ..., Iterator first, Iterator last )
</pre>
<p>a range-based version is added of the form:</p>
<pre class="literal-block">
template&lt; class Range &gt;
return-type fun( ..., const Range&amp; r )
</pre>
<p>which forwards to the iterator-based
version via unqualified calls to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>.</p>
</li>
</ul>
</blockquote>
<!-- For the classes ``deque``, ``list``, ``vector``, ``map``, ``multimap``, ``set``
and ``multiset`` it holds that for all functions of the form::

           template< class Range >
       return-type fun( const Range& r )

           template< class Range >
       return-type fun( ..., const Range& r )
       
we also add members of the form::

           template< class Range >
       return-type fun( ..., Range&& r )
       
           template< class Range >
       return-type fun( ..., Range&& r )

if ``fun`` is either ``assign`` or ``insert``.
(**Remark:** these member functions can be much more efficient than the ``const Range&`` 
counterparts by moving the
source directly into the target or by move-constructing each new element.) -->
</div>
<div class="section" id="tr1-and-other-proposals">
<h2><a class="toc-backref" href="#id29" name="tr1-and-other-proposals">4.3&nbsp;&nbsp;&nbsp;Tr1 and other proposals</a></h2>
<p>It is suggested that all 
algorithms and containers described in
tr1 and other proposals adopt the
two version approach described above.</p>
</div>
<div class="section" id="id9">
<h2><a class="toc-backref" href="#id30" name="id9">4.4&nbsp;&nbsp;&nbsp;Discussion</a></h2>
<ol class="arabic simple">
<li>Should constructers that take two iterators also be accompanied
by a range-based constructor? This will make it easy to copy
eg. a <tt class="docutils literal"><span class="pre">vector</span></tt> to a <tt class="docutils literal"><span class="pre">deque</span></tt>. 
Making the constructor do the right thing is getting complicated, though.</li>
</ol>
<ol class="arabic simple" id="rng-discussion" start="2">
<li>Putting every algorithm in namespace <tt class="docutils literal"><span class="pre">std::rng</span></tt> is somewhat
controversial. Maybe we should consider <tt class="docutils literal"><span class="pre">enable_if</span></tt>-like
disambiguiting instead to give users the easiest-to-use
library. Of course, with concepts in the language, there is
no problem anymore.</li>
</ol>
<!-- 3. All the new member functions that overload existing function can potentially
lead to ambiguity.  -->
<ol class="arabic simple" start="3">
<li>We might one to reconsider on a case-by-case basis if the return type
of range-based algothms can be changed for the better. For example, 
<tt class="docutils literal"><span class="pre">remove()</span></tt> might return the removed range so it is easy to pass this
to <tt class="docutils literal"><span class="pre">erase()</span></tt> in a container.</li>
</ol>
</div>
</div>
<div class="section" id="range-utilities-part-3">
<h1><a class="toc-backref" href="#id31" name="range-utilities-part-3">5&nbsp;&nbsp;&nbsp;Range utilities (Part 3)</a></h1>
<p>Outside the core functionality, <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost.Range</a> supplies 
a few handy utility-classes for using iterator views:</p>
<ul class="simple">
<li><a class="reference" href="#range">range</a></li>
<li><a class="reference" href="#sub-range">sub_range</a></li>
</ul>
<p>Overloaded operators are provided s.t. comparisons 
between view-objects and container-objects are easy. 
For example:</p>
<pre class="literal-block">
string s = ...;
sub_range&lt;string&gt; sub = find( s, ... );
if( sub == string(&quot;foo&quot;) )
{ 
   sub[0] = 'b'; 
   assert( sub == string(&quot;boo&quot;) );
}
</pre>
<div class="section" id="range">
<h2><a class="toc-backref" href="#id32" name="range">5.1&nbsp;&nbsp;&nbsp;Range</a></h2>
<p>The class template <tt class="docutils literal"><span class="pre">range</span></tt> is templated on
an iterator and hence very generic.</p>
<div class="section" id="synopsis">
<h3><a class="toc-backref" href="#id33" name="synopsis">5.1.1&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
<pre class="literal-block">
namespace std
{
    template&lt; class Iter &gt;
    class range
    {
    public: // Forward Range types
        typedef typename iterator_traits&lt;Iter&gt;::value_type       value_type;
        typedef typename iterator_traits&lt;Iter&gt;::reference        reference;
        typedef typename iterator_traits&lt;Iter&gt;::difference_type  difference_type;
        typedef typename iterator_traits&lt;Iter&gt;::size_type        size_type;
        typedef Iter                                             iterator;
        typedef Iter                                             const_iterator;

    public: // construction, assignment
        range();
        
        template&lt; class Iter2 &gt;
        range( Iter2 begin, Iter2 end );
                    
        template&lt; class Rng &gt;
        range( Rng&amp;&amp; r );
  
        template&lt; class Rng &gt;
        range&amp; operator=( Rng&amp;&amp; r );

    public: // Forward Range functions
        iterator  begin() const;
        iterator  end() const;
        size_type size() const;
        bool      empty() const;
        
    public: // convenience
        operator    <em>unspecified_bool_type()</em> const;
        bool        equal( const range&amp; ) const;
        reference   front() const;
        reference   back() const;
        reference   operator[]( size_type at ) const;
        void        advance_begin( difference_type n );
        void        advance_end( difference_type n );
    
    private:
        Iter first; // exposition only
        Iter last;  // exposition only    
    };
    
    // stream output
    template&lt; class Iter, class T, class Traits &gt;
    std::basic_ostream&lt;T,Traits&gt;&amp; 
    operator&lt;&lt;( std::basic_ostream&lt;T,Traits&gt;&amp; Os,
                const range&lt;ForwardTraversalIterator&gt;&amp; r );

    // comparison
    template&lt; class Iter, class Iter2 &gt;
    bool operator==( const range&lt;Iter&gt;&amp; l, const range&lt;Iter2&gt;&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator==( const range&lt;Iter&gt;&amp; l, const Rng&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator==( const Rng&amp; l, const range&lt;Iter&gt;&amp; r );

    template&lt; class Iter, class Iter2 &gt;
    bool operator!=( const range&lt;Iter&gt;&amp; l, const range&lt;Iter2&gt;&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator!=( const range&lt;Iter&gt;&amp; l, const Rng&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator!=( const Rng&amp; l, const range&lt;Iter&gt;&amp; r );

    template&lt; class Iter, class Iter2 &gt;
    bool operator&lt;( const range&lt;Iter&gt;&amp; l, const range&lt;Iter2&gt;&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator&lt;( const range&lt;Iter&gt;&amp; l, const Rng&amp; r );

    template&lt; class Iter, class Rng &gt;
    bool operator&lt;( const Rng&amp; l, const range&lt;Iter&gt;&amp; r );
 
    // external construction
    template&lt; class Iter &gt;
    range&lt; Iter &gt;
    make_range( Iter Begin, Iter End );
       
    template&lt; class Rng &gt;
    auto make_range( Rng&amp;&amp; r ) -&gt; range&lt; decltype( begin(r) ) &gt;;

    template&lt; class Rng &gt;
    auto make_range( Rng&amp;&amp; r, typename range_difference&lt;Range&gt;::type advance_begin,
                     typename range_difference&lt;Range&gt;::type advance_end ) -&gt; range&lt; decltype( begin(r) ) &gt;;
               
    template&lt; class CopyableRng, class Rng &gt;      
    CopyableRng copy_range( const Rng&amp; r );

}
</pre>
</div>
<div class="section" id="specification">
<h3><a class="toc-backref" href="#id34" name="specification">5.1.2&nbsp;&nbsp;&nbsp;Specification</a></h3>
<p>The template argument <tt class="docutils literal"><span class="pre">Iter</span></tt> must be a model of <tt class="docutils literal"><span class="pre">ForwardTraversalIterator</span></tt>.</p>
<p><strong>Construction, assignment</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">range()</span></tt></p>
<ul class="simple">
<li><strong>Effects</strong>: Constructs an object of class <tt class="docutils literal"><span class="pre">range</span></tt>.</li>
<li><strong>Remarks</strong>: The stored iterators are singular.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter2</span> <span class="pre">&gt;</span>
<span class="pre">range(</span> <span class="pre">Iter2</span> <span class="pre">begin,</span> <span class="pre">Iter2</span> <span class="pre">end</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">Iter2</span></tt> is convertible to <tt class="docutils literal"><span class="pre">Iter</span></tt>.</li>
<li><strong>Effects</strong>: Constructs an object of class <tt class="docutils literal"><span class="pre">range</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">range(</span> <span class="pre">Rng&amp;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: The iterator type of <tt class="docutils literal"><span class="pre">Rng</span></tt> is convertible to <tt class="docutils literal"><span class="pre">Iter</span></tt>.</li>
<li><strong>Effects</strong>: Constructs an object of class <tt class="docutils literal"><span class="pre">range</span></tt> using
unqualified calls to <tt class="docutils literal"><span class="pre">begin(r)</span></tt> and <tt class="docutils literal"><span class="pre">end(r)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">range&amp;</span> <span class="pre">operator=(</span> <span class="pre">Rng&amp;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: The iterator type of <tt class="docutils literal"><span class="pre">Rng</span></tt> is convertible to <tt class="docutils literal"><span class="pre">Iter</span></tt>.</li>
<li><strong>Postcondition</strong>: <tt class="docutils literal"><span class="pre">begin()</span> <span class="pre">==</span> <span class="pre">begin(r)</span> <span class="pre">&amp;&amp;</span> <span class="pre">end()</span> <span class="pre">==</span> <span class="pre">end(r)</span></tt>.</li>
</ul>
</blockquote>
<p><strong>Forward Range functions</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">iterator</span>&nbsp; <span class="pre">begin()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">first</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">iterator</span>&nbsp; <span class="pre">end()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">last</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">size()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">[begin(),end())</span></tt> is a valid range.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">std::distance(begin(),end())</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">empty()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> are not singular.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">begin()</span> <span class="pre">==</span> <span class="pre">end()</span></tt>.</li>
</ul>
</blockquote>
<p><strong>Convenience</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">operator</span></tt> <em>unspecified_bool_type()</em> <tt class="docutils literal"><span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Returns</strong>: a value convertible to <tt class="docutils literal"><span class="pre">bool</span></tt> indicating
whether <tt class="docutils literal"><span class="pre">empty()</span></tt> is true.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">equal(</span> <span class="pre">const</span> <span class="pre">range&amp;</span> <span class="pre">r</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> are not singular.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">begin()</span> <span class="pre">==</span> <span class="pre">r.begin()</span> <span class="pre">&amp;&amp;</span> <span class="pre">end()</span> <span class="pre">==</span> <span class="pre">r.end()</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">front()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">begin()</span></tt> is dereferenceable.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">*begin()</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">reference</span>&nbsp;&nbsp; <span class="pre">back()</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">--end()</span></tt> is dereferenceable.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">*--end()</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">at</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">Iter</span></tt> models a RandomAccessIterator.</li>
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">at</span> <span class="pre">&lt;</span> <span class="pre">size()</span></tt>.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">*(begin()</span> <span class="pre">+</span> <span class="pre">at)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">advance_begin(</span> <span class="pre">difference_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Effects</strong>: <tt class="docutils literal"><span class="pre">advance(first,n)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">advance_end(</span> <span class="pre">difference_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Effects</strong>: <tt class="docutils literal"><span class="pre">advance(last,n)</span></tt>.</li>
</ul>
</blockquote>
<p><strong>Stream output</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">class</span> <span class="pre">Traits</span> <span class="pre">&gt;</span>
<span class="pre">std::basic_ostream&lt;T,Traits&gt;&amp;</span></tt> <span class="html"><br></span>
<tt class="docutils literal"><span class="pre">operator&lt;&lt;(</span> <span class="pre">std::basic_ostream&lt;T,Traits&gt;&amp;</span> <span class="pre">os,</span>
<span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Effects</strong>: <tt class="docutils literal"><span class="pre">copy(</span> <span class="pre">r.begin(),</span> <span class="pre">r.end(),</span> <span class="pre">std::ostream_iterator&lt;Elem&gt;(os));</span> <span class="pre">return</span> <span class="pre">Os;</span></tt>.</li>
</ul>
</blockquote>
<p><strong>Comparison</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Iter2</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator==(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter2&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator==(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator==(</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">l</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> are valid ranges.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">equal(l,r)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Iter2</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator!=(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter2&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator!=(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator!=(</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">l</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> are valid ranges.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">!(</span> <span class="pre">l</span> <span class="pre">==</span> <span class="pre">r</span> <span class="pre">)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Iter2</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator&lt;(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter2&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator&lt;(</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">bool</span> <span class="pre">operator&lt;(</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">l,</span> <span class="pre">const</span> <span class="pre">range&lt;Iter&gt;&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">l</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> are valid ranges.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">lexicographical_compare(l,r)</span></tt>.</li>
</ul>
</blockquote>
<p><strong>External construction</strong>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iter</span> <span class="pre">&gt;</span>
<span class="pre">range&lt;Iter&gt;</span> <span class="pre">make_range(</span> <span class="pre">Iter</span> <span class="pre">begin,</span> <span class="pre">Iter</span> <span class="pre">end</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">range&lt;Iter&gt;(begin,end)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">make_range(</span> <span class="pre">Rng&amp;&amp;</span> <span class="pre">r</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">range&lt;</span> <span class="pre">decltype(</span> <span class="pre">begin(r)</span> <span class="pre">)</span> <span class="pre">&gt;;</span></tt></p>
<ul class="simple">
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">range&lt;</span> <span class="pre">decltype(</span> <span class="pre">begin(r)</span> <span class="pre">)</span> <span class="pre">&gt;(r)</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span>
<span class="pre">auto</span> <span class="pre">make_range(</span> <span class="pre">Rng&amp;&amp;</span> <span class="pre">r,</span> <span class="pre">typename</span> <span class="pre">range_difference&lt;Rng&gt;::type</span> <span class="pre">N,</span>
<span class="pre">typename</span> <span class="pre">range_difference&lt;Rng&gt;::type</span> <span class="pre">M</span> <span class="pre">)</span> <span class="pre">-&gt;</span> <span class="pre">range&lt;</span> <span class="pre">decltype(</span> <span class="pre">begin(r)</span> <span class="pre">)</span> <span class="pre">&gt;;</span></tt></p>
<ul class="simple">
<li><strong>Effects</strong>: <tt class="docutils literal"><span class="pre">range&lt;</span> <span class="pre">decltype(</span> <span class="pre">begin(r)</span> <span class="pre">)</span> <span class="pre">&gt;</span> <span class="pre">tmp(r);</span> <span class="pre">tmp.advance_begin(N);</span> <span class="pre">tmp.advance_end(M);</span> <span class="pre">return</span> <span class="pre">tmp;</span></tt></li>
</ul>
<p><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">CopyableRng,</span> <span class="pre">class</span> <span class="pre">Rng</span> <span class="pre">&gt;</span> <span class="pre">CopyableRng</span> <span class="pre">copy_range(</span> <span class="pre">const</span> <span class="pre">Rng&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><strong>Precondition</strong>:<ul>
<li>The value-type of <tt class="docutils literal"><span class="pre">Rng</span></tt> is convertible to the value-type of <tt class="docutils literal"><span class="pre">CopyableRng</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">CopyableRng</span></tt> models a CopyableRange.</li>
</ul>
</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">CopyableRng(begin(r),end(r))</span></tt>.</li>
</ul>
</blockquote>
</div>
</div>
<div class="section" id="sub-range">
<h2><a class="toc-backref" href="#id35" name="sub-range">5.2&nbsp;&nbsp;&nbsp;Sub_range</a></h2>
<p>The class template <tt class="docutils literal"><span class="pre">sub_range</span></tt> is templated on
another Range and so can propagate constness because
it can infer what the associated <tt class="docutils literal"><span class="pre">const_iterator</span></tt> is.
Besides that it is exactly like <tt class="docutils literal"><span class="pre">range</span></tt>.</p>
<div class="section" id="id10">
<h3><a class="toc-backref" href="#id36" name="id10">5.2.1&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
<pre class="literal-block">
template&lt; class Rng &gt;
class sub_range 
{
public: 
    typedef typename range_iterator&lt;Rng&gt;::type        iterator;
    typedef typename range_iterator&lt;const Rng&gt;::type  const_iterator;
    
    <em>The remaining typedefs as in 'range&lt;iterator&gt;'</em>

public: // construction, assignment
    template&lt; class Iter &gt;
    sub_range( Iter begin, Iter end );

    template&lt; class Rng2 &gt;
    sub_range( Rng2&amp;&amp; r );
     
    template&lt; class Rng2 &gt;
    sub_range&amp; operator=( Rng2&amp;&amp; r );

public:  // Forward Range functions 
    iterator        begin();
    const_iterator  begin() const;
    iterator        end();
    const_iterator  end() const;    
    
public: // convenience 
    value_type&amp;       front();
    const value_type&amp; front() const;
    value_type&amp;       back();
    const value_type&amp; back() const;
    // for Random Access Range only: 
    value_type&amp;       operator[]( size_type at );
    const value_type&amp; operator[]( size_type at ) const;

    <em>rest of interface as if inherited from 'range&lt;iterator&gt;'</em>
};
</pre>
</div>
<div class="section" id="id11">
<h3><a class="toc-backref" href="#id37" name="id11">5.2.2&nbsp;&nbsp;&nbsp;Specification</a></h3>
<p><tt class="docutils literal"><span class="pre">Rng</span></tt> must model a ForwardRange.</p>
<p>All the functions are like the ones from <tt class="docutils literal"><span class="pre">range</span></tt>.</p>
</div>
</div>
<div class="section" id="id12">
<h2><a class="toc-backref" href="#id38" name="id12">5.3&nbsp;&nbsp;&nbsp;Discussion</a></h2>
<ul class="simple">
<li>In Boost <tt class="docutils literal"><span class="pre">range</span></tt> is called <tt class="docutils literal"><span class="pre">iterator_range</span></tt>, but
it seems unnecessary to say we are dealing with iterators.</li>
</ul>
<!--  -->
<ul class="simple">
<li>The Boost versions of <tt class="docutils literal"><span class="pre">range</span></tt> and <tt class="docutils literal"><span class="pre">sub_range</span></tt> gives
well-defined behavior even when the stored iterators are
singular. This behavior have been removed from the proposal
as it means an object is 3 words instead of 2 words.
Furthermore, it seems of little use to make the singularity
of a range be different than singularity of its iterators.</li>
</ul>
<!--  -->
<ul class="simple">
<li>The helper function <tt class="docutils literal"><span class="pre">copy_range()</span></tt> is useful generic 
libraries when a third-party type does not provide
a constructor that takes two iterators. A version
of <tt class="docutils literal"><span class="pre">copy_range()</span></tt> may then be found via ADL.</li>
</ul>
</div>
</div>
<div class="section" id="range-adapters-part-4">
<h1><a class="toc-backref" href="#id39" name="range-adapters-part-4">6&nbsp;&nbsp;&nbsp;Range adapters (Part 4)</a></h1>
<p>The last part of this proposal covers range adapters.
These little helper classes has the following benefits:</p>
<ul class="simple">
<li>adapters are easily composable via <tt class="docutils literal"><span class="pre">operator|()</span></tt>,</li>
</ul>
<!--  -->
<ul class="simple">
<li>the user can completely avoid naming the types of iterators and ranges---everything
is deduced in function calls.</li>
</ul>
<p>The adapters can all be build on top off iterator adapters although
the exact nature of these have been left unspecified. <tt class="docutils literal"><span class="pre">operator|()</span></tt>
is simply a short name for what would normally be called 
a <tt class="docutils literal"><span class="pre">make_XX()</span></tt> function, though <tt class="docutils literal"><span class="pre">operator|()</span></tt> is much easier
to read---especially when applied several times.</p>
<p>Eric Niebler's <a class="reference" href="http://boost-sandbox.sourceforge.net/vault/index.php?action=downloadfile&amp;filename=range_ex.zip&amp;directory=eric_niebler&amp;">range_ex</a> code implements some of these
adapters.</p>
<div class="section" id="id14">
<h2><a class="toc-backref" href="#id40" name="id14">6.1&nbsp;&nbsp;&nbsp;Specification</a></h2>
<p>In the following <tt class="docutils literal"><span class="pre">fwdRng</span></tt> is an expression of a type that models
ForwardRange, <tt class="docutils literal"><span class="pre">biRng</span></tt> is an expression of a type that models
BidirectionalRange, <tt class="docutils literal"><span class="pre">rndRng</span></tt> is an expression of a type that models
RandomAccessRange, <tt class="docutils literal"><span class="pre">pred</span></tt> is an expression of a type that models
UnaryPredicate, <tt class="docutils literal"><span class="pre">biPred</span></tt> is an expression of a type that models
BinaryPredicate, <tt class="docutils literal"><span class="pre">fun</span></tt> is an expression of type that models
UnaryFunction. Furthermore, <tt class="docutils literal"><span class="pre">n</span></tt> and <tt class="docutils literal"><span class="pre">m</span></tt> are 
integer expressions corresponding in type to the 
size-type of the range in question.</p>
<p>General requirements:</p>
<ol class="arabic simple">
<li>Applying <tt class="docutils literal"><span class="pre">operator|()</span></tt> to
a range <tt class="docutils literal"><span class="pre">R</span></tt> (always left argument) and a range adapter
<tt class="docutils literal"><span class="pre">RA</span></tt> (always right argument) yields a new range type 
conforming to the same range concept as <tt class="docutils literal"><span class="pre">R</span></tt>.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="2">
<li>The return-type of <tt class="docutils literal"><span class="pre">operator|()</span></tt> is otherwise unspecified.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="3">
<li><tt class="docutils literal"><span class="pre">operator|()</span></tt> is found by ADL because a range adapter is
implemented in namespace <tt class="docutils literal"><span class="pre">std</span></tt>.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="4">
<li><tt class="docutils literal"><span class="pre">operator|()</span></tt> is used to add new behavior lazily and never
modifies its left argument.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="5">
<li>All iterators extracted from the left argument are extracted using 
unqualified calls to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="6">
<li>In addition to the throw-clauses below,
<tt class="docutils literal"><span class="pre">operator|()</span></tt> may throw exceptions as a result of copying iterators.</li>
</ol>
<p>Valid expressions:</p>
<ol class="arabic simple">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::filtered(</span> <span class="pre">pred</span> <span class="pre">)</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: The value-type of the range is convertible to
the argument type of <tt class="docutils literal"><span class="pre">pred</span></tt>.</li>
<li><strong>Postcondition</strong>: For all elements <tt class="docutils literal"><span class="pre">x</span></tt> in the returned range, <tt class="docutils literal"><span class="pre">pred(x)</span></tt>
is true.</li>
<li><strong>Throws</strong>: Whatever the copy-constructor of <tt class="docutils literal"><span class="pre">pred</span></tt> might throw.</li>
</ul>
</blockquote>
<ol class="arabic simple">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::adjacent_filtered(</span> <span class="pre">biPred</span> <span class="pre">)</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: The value-type of the range is convertible to
the argument types of <tt class="docutils literal"><span class="pre">biPred</span></tt>.</li>
<li><strong>Postcondition</strong>: For all adjacent elements <tt class="docutils literal"><span class="pre">[x,y]</span></tt> 
in the returned range, <tt class="docutils literal"><span class="pre">biPred(x,y)</span></tt> is true.</li>
<li><strong>Throws</strong>: Whatever the copy-constructor of <tt class="docutils literal"><span class="pre">biPred</span></tt> might throw.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="2">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::transformed(</span> <span class="pre">fun</span> <span class="pre">)</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: The value-type of the range is convertible to
the argument type of <tt class="docutils literal"><span class="pre">fun</span></tt>.</li>
<li><strong>Postcondition</strong>: For all elements <tt class="docutils literal"><span class="pre">x</span></tt> in the returned range, 
<tt class="docutils literal"><span class="pre">x</span></tt> is the result of <tt class="docutils literal"><span class="pre">fun(y)</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is the corresponding
element in the original range.</li>
<li><strong>Throws</strong>: Whatever the copy-constructor of <tt class="docutils literal"><span class="pre">fun</span></tt> might throw.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="3">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::indirected</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: The value-type of the range defines unary
<tt class="docutils literal"><span class="pre">operator*()</span></tt></li>
<li><strong>Postcondition</strong>: For all elements <tt class="docutils literal"><span class="pre">x</span></tt> in the returned range, 
<tt class="docutils literal"><span class="pre">x</span></tt> is the result of <tt class="docutils literal"><span class="pre">*y</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is the corresponding
element in the original range.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="4">
<li><tt class="docutils literal"><span class="pre">biRng</span> <span class="pre">|</span> <span class="pre">std::reversed</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Returns</strong>: A range whose iterators behave as if they were
the original iterators wrapped in <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt>.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="5">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::map_values</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition:</strong> The value-type of the range is an instantiation
of <tt class="docutils literal"><span class="pre">std::pair</span></tt>.</li>
<li><strong>Postcondition</strong>: For all elements <tt class="docutils literal"><span class="pre">x</span></tt> in the returned range, 
<tt class="docutils literal"><span class="pre">x</span></tt> is the result of <tt class="docutils literal"><span class="pre">y.second</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is the corresponding
element in the original range.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="6">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::map_keys</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition:</strong> The value-type of the range is an instantiation
of <tt class="docutils literal"><span class="pre">std::pair</span></tt>.</li>
<li><strong>Postcondition</strong>: For all elements <tt class="docutils literal"><span class="pre">x</span></tt> in the returned range, 
<tt class="docutils literal"><span class="pre">x</span></tt> is the result of <tt class="docutils literal"><span class="pre">y.first</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is the corresponding
element in the original range.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="7">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::moved</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Returns</strong>: A range whose iterators behave as if they were
the original iterators wrapped in <tt class="docutils literal"><span class="pre">move_iterator</span></tt>.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="8">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::uniqued</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: The value-type of the range is comparable with <tt class="docutils literal"><span class="pre">operator==()</span></tt>.</li>
<li><strong>Postcondition</strong>: For all adjacent elements <tt class="docutils literal"><span class="pre">[x,y]</span></tt> in the returned range,
<tt class="docutils literal"><span class="pre">x==y</span></tt> is false.</li>
</ul>
</blockquote>
<ol class="arabic simple" start="9">
<li><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::sliced(n,m)</span></tt></li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>: <tt class="docutils literal"><span class="pre">0&lt;=n</span> <span class="pre">&amp;&amp;</span> <span class="pre">n</span> <span class="pre">&lt;=</span> <span class="pre">m</span> <span class="pre">&amp;&amp;</span> <span class="pre">m</span> <span class="pre">&lt;</span> <span class="pre">size(fwdRng)</span></tt>.</li>
<li><strong>Returns</strong>: <tt class="docutils literal"><span class="pre">make_range(fwdRng,n,m)</span></tt>.</li>
</ul>
</blockquote>
<ol class="arabic" start="10">
<li><p class="first"><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::tokenized(</span> <span class="pre">regex</span> <span class="pre">)</span></tt></p>
<p><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::tokenized(</span> <span class="pre">regex,</span> <span class="pre">i</span> <span class="pre">)</span></tt></p>
<p><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::tokenized(</span> <span class="pre">regex,</span> <span class="pre">rndRng</span> <span class="pre">)</span></tt></p>
<p><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::tokenized(</span> <span class="pre">regex,</span> <span class="pre">i,</span> <span class="pre">flags</span> <span class="pre">)</span></tt></p>
<p><tt class="docutils literal"><span class="pre">fwdRng</span> <span class="pre">|</span> <span class="pre">std::tokenized(</span> <span class="pre">regex,</span> <span class="pre">rndRng,</span> <span class="pre">flags</span> <span class="pre">)</span></tt></p>
</li>
</ol>
<blockquote>
<ul class="simple">
<li><strong>Precondition</strong>:<ul>
<li>Let <tt class="docutils literal"><span class="pre">T</span></tt> denote <tt class="docutils literal"><span class="pre">typename</span> <span class="pre">range_value&lt;</span> <span class="pre">decltype(fwdRng)</span> <span class="pre">&gt;::type</span></tt>, then
<tt class="docutils literal"><span class="pre">regex</span></tt> has the type <tt class="docutils literal"><span class="pre">basic_regex&lt;T&gt;</span></tt> or the type <tt class="docutils literal"><span class="pre">basic_string&lt;T&gt;</span></tt> or is 
implicitly convertible to one of these types.</li>
<li><tt class="docutils literal"><span class="pre">i</span></tt> has the type <tt class="docutils literal"><span class="pre">int</span></tt>.</li>
<li>the value-type of <tt class="docutils literal"><span class="pre">rndRng</span></tt> is <tt class="docutils literal"><span class="pre">int</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">flags</span></tt> has the type <tt class="docutils literal"><span class="pre">regex_constants::syntax_option_type</span></tt>.</li>
</ul>
</li>
<li><strong>Returns</strong>: A range whose iterators behave as if they were
the original iterators wrapped in <tt class="docutils literal"><span class="pre">regex_token_iterator</span></tt>.
The first iterator in the range would be constructed by 
forwarding all the arguments of <tt class="docutils literal"><span class="pre">tokenized()</span></tt> to the
<tt class="docutils literal"><span class="pre">regex_token_iterator</span></tt> constructor.</li>
<li><strong>Throws</strong>: Whatever constructing and copying equivalent <tt class="docutils literal"><span class="pre">regex_token_iterator</span></tt>s
might throw.</li>
</ul>
</blockquote>
</div>
<div class="section" id="id15">
<h2><a class="toc-backref" href="#id41" name="id15">6.2&nbsp;&nbsp;&nbsp;Discussion</a></h2>
<ul class="simple">
<li>Should we provide additional range adapters? Can anybody
come up with more?</li>
</ul>
<!--  -->
<ul class="simple">
<li>Would <tt class="docutils literal"><span class="pre">adjacent_transformed()</span></tt> be a candidate?</li>
</ul>
</div>
</div>
<div class="section" id="acknowledgements">
<h1><a class="toc-backref" href="#id42" name="acknowledgements">7&nbsp;&nbsp;&nbsp;Acknowledgements</a></h1>
<p>Thanks to Howard Hinnant, Dietmar Kuehl and Walter Brown for
their constructive and brutally honest feedback. 
The range adapters presented in this proposal is based
on ideas developed by Eric Niebler.</p>
<!-- ############################################### -->
<!-- ################## Links ###################### -->
<!-- ############################################### -->
<!-- ========= -->
<!-- Footnotes -->
<!-- ========= -->
<!-- ############################################### -->
<!-- ################## Footnotes ################## -->
<!-- ############################################### -->
</div>
</div>
</body>
</html>
