feedc0de/boost_range
1
0
Fork 0
forked from boostorg/range
Code Pull Requests Activity
Files
067b63da8ebbb810afb2bf3947dafb5a1e36eb0c
boost_range/doc/html/range/introduction.html
Neil Groves 067b63da8e Boost.Range improved push_front algorithm unit test. Updated documentation. 
[SVN r61145]
2010-04-08 19:09:34 +00:00

155 lines
17 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Introduction</title>
<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Range 2.0">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Range 2.0">
<link rel="prev" href="../index.html" title="Chapter&#160;1.&#160;Range 2.0">
<link rel="next" href="concepts.html" title="Range Concepts">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" title="Introduction">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="range.introduction"></a><a class="link" href="introduction.html" title="Introduction">Introduction</a>
</h2></div></div></div>
<p>
Generic algorithms have so far been specified in terms of two or more iterators.
Two iterators would together form a range of values that the algorithm could
work on. This leads to a very general interface, but also to a somewhat clumsy
use of the algorithms with redundant specification of container names. Therefore
we would like to raise the abstraction level for algorithms so they specify
their interface in terms of <a class="link" href="concepts.html" title="Range Concepts">Ranges</a> as
much as possible.
</p>
<p>
The most common form of ranges used throughout the C++ community are standard
library containers. When writing algorithms however, one often finds it desirable
for the algorithm to accept other types that offer enough functionality to
satisfy the needs of the generic code <span class="bold"><strong><span class="emphasis"><em>if a
suitable layer of indirection is applied</em></span></strong></span> . For example,
raw arrays are often suitable for use with generic code that works with containers,
provided a suitable adapter is used. Likewise, null terminated strings can
be treated as containers of characters, if suitably adapted.
</p>
<p>
This library therefore provides the means to adapt standard-like containers,
null terminated strings, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pairs</span></code> of
iterators, and raw arrays (and more), such that the same generic code can work
with them all. The basic idea is to add another layer of indirection using
<a href="../../../../../libs/mpl/doc/refmanual/metafunction.html" target="_top">metafunctions</a>
and free-standing functions so syntactic and/or semantic differences can be
removed.
</p>
<p>
The main advantages are
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
simpler implementation and specification of generic range algorithms
</li>
<li class="listitem">
more flexible, compact and maintainable client code
</li>
<li class="listitem">
safe use of built-in arrays (for legacy code; why else would you use built-in
arrays?)
</li>
</ul></div>
<p>
Below are given a small example (the complete example can be found <a href="http://www.boost.org/libs/range/test/algorithm_example.cpp" target="_top">here</a>
):
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">//
</span><span class="comment">// example: extracting bounds in a generic algorithm
</span><span class="comment">//
</span><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">ForwardReadableRange</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">&gt;</span>
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="identifier">ForwardReadableRange</span> <span class="special">&gt;::</span><span class="identifier">type</span>
<span class="identifier">find</span><span class="special">(</span> <span class="identifier">ForwardReadableRange</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">value</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">find</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">),</span> <span class="identifier">value</span> <span class="special">);</span>
<span class="special">}</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">ForwardReadableRange</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">&gt;</span>
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="keyword">const</span> <span class="identifier">ForwardReadableRange</span> <span class="special">&gt;::</span><span class="identifier">type</span>
<span class="identifier">find</span><span class="special">(</span> <span class="keyword">const</span> <span class="identifier">ForwardReadableRange</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">value</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">find</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">),</span> <span class="identifier">value</span> <span class="special">);</span>
<span class="special">}</span>
<span class="comment">//
</span><span class="comment">// replace first value and return its index
</span><span class="comment">//
</span><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">ForwardReadableWriteableRange</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">&gt;</span>
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_size</span><span class="special">&lt;</span> <span class="identifier">ForwardReadableWriteableRange</span> <span class="special">&gt;::</span><span class="identifier">type</span>
<span class="identifier">my_generic_replace</span><span class="special">(</span> <span class="identifier">ForwardReadableWriteableRange</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">replacement</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="identifier">ForwardReadableWriteableRange</span> <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">found</span> <span class="special">=</span> <span class="identifier">find</span><span class="special">(</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">value</span> <span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">found</span> <span class="special">!=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">)</span> <span class="special">)</span>
<span class="special">*</span><span class="identifier">found</span> <span class="special">=</span> <span class="identifier">replacement</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">c</span> <span class="special">),</span> <span class="identifier">found</span> <span class="special">);</span>
<span class="special">}</span>
<span class="comment">//
</span><span class="comment">// usage
</span><span class="comment">//
</span><span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">my_vector</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">values</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">,</span><span class="number">9</span> <span class="special">};</span>
<span class="identifier">my_vector</span><span class="special">.</span><span class="identifier">assign</span><span class="special">(</span> <span class="identifier">values</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span> <span class="identifier">values</span> <span class="special">)</span> <span class="special">);</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">iterator</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">,</span><span class="identifier">iterator</span><span class="special">&gt;</span> <span class="identifier">my_view</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">my_vector</span> <span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">my_vector</span> <span class="special">)</span> <span class="special">+</span> <span class="identifier">N</span> <span class="special">);</span>
<span class="keyword">char</span> <span class="identifier">str_val</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"a string"</span><span class="special">;</span>
<span class="keyword">char</span><span class="special">*</span> <span class="identifier">str</span> <span class="special">=</span> <span class="identifier">str_val</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">my_generic_replace</span><span class="special">(</span> <span class="identifier">my_vector</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">2</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">my_generic_replace</span><span class="special">(</span> <span class="identifier">my_view</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">2</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">my_generic_replace</span><span class="special">(</span> <span class="identifier">str</span><span class="special">,</span> <span class="char">'a'</span><span class="special">,</span> <span class="char">'b'</span> <span class="special">);</span>
<span class="comment">// prints '3', '5' and '0'
</span></pre>
<p>
</p>
<p>
By using the free-standing functions and <a href="../../../../../libs/mpl/doc/refmanual/metafunction.html" target="_top">metafunctions</a>,
the code automatically works for all the types supported by this library; now
and in the future. Notice that we have to provide two versions of <code class="computeroutput"><span class="identifier">find</span><span class="special">()</span></code> since
we cannot forward a non-const rvalue with reference arguments (see this article
about <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_top">The
Forwarding Problem</a> ).
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003 -2010 Thorsten Ottosen, Neil Groves<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
View Git Blame Copy Permalink