Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/range/doc/intro.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
  • Property svn:executable set to *
File size: 14.1 KB
RevLine 
[12]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2
3<html>
4<head>
5    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6    <title>Boost.Range Introduction </title>
7    <link rel="stylesheet" href="style.css" type="text/css">
8</head>
9
10    <body>
11
12    <table border="0" >
13        <tr>
14            <td ><img src="../../../boost.png" border="0" ></td>
15            <td ><h1 align="center">Boost.Range</h1></td>
16        </tr>
17    </table>
18
19    <h2>Introduction</h2>
20    <p>
21    Generic algorithms have so far been specified in terms of two or more
22    iterators. Two iterators would together form a range of values that the
23    algorithm could work on. This leads to a very general interface, but also
24    to a somewhat clumsy use of the algorithms with redundant specification
25    of container names. Therefore we would like to raise the abstraction level
26    for algorithms so they specify their interface in terms of <a
27    href=range.html>Ranges</a> as much as possible.
28    </p>
29
30    <p>
31    The most common form of ranges we are used to work with is standard library
32    containers. However, one
33    often finds it desirable to extend that code to work with other types that
34    offer
35    enough functionality to satisfy the needs of the generic code
36    <i>if a suitable layer of indirection is applied </i>.  For
37    example, raw arrays are often suitable for use with generic code that
38    works with containers, provided a suitable adapter is used. Likewise, null
39    terminated strings can be treated as containers of characters, if suitably
40    adapted.
41    </p>
42
43    <p>
44     This library therefore provides the means to adapt standard-like
45     containers,
46    null terminated strings, <code>std::pairs</code> of iterators, and raw
47    arrays (and more), such that the same generic code can work with them all.
48The basic idea is to add another layer of indirection using <a
49href="../../mpl/doc/refmanual/metafunction.html">metafunctions</a> and
50free-standing functions so syntactic and/or semantic differences can be removed.
51</p>
52
53    <p  >
54    The main advantages are
55    <ul  >
56        <li  >
57            simpler implementation and specification of generic range algorithms
58        </li>
59        <li  >
60            more flexible, compact and maintainable client code
61        </li>
62        <li  >
63            correct handling of null-terminated strings
64            <p>
65            <b>Warning:</b><i> support for null-terminated strings is deprecated and will
66              disappear in the next Boost release (1.34). </i>
67             </p>
68        </li>
69        <li  >
70        safe use of built-in arrays (for legacy code; why else would you use
71        built-in arrays?) </li>
72
73    </ul>
74    </p>
75    <p  >
76    Below are given a small example (the complete example can be found <a href="../test/algorithm_example.cpp" target="_self" >here</a>
77    ):
78    <blockquote>
79        <pre  >
80<span class=comment>
81    //
82    // example: extracting bounds in a generic algorithm
83    //
84    </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;
85    </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
86    </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>)
87    </span><span class=special>{
88       </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>);
89    </span><span class=special>}
90
91    </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;
92    </span><span class=keyword>inline </span><span class=keyword>typename </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_const_iterator</span><span class=special>&lt; </span><span
93class=identifier>ForwardReadableRange </span><span class=special>&gt;::</span><span class=identifier>type
94    </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>)
95    </span><span class=special>{
96       </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>);
97    </span><span class=special>}
98
99    </span><span class=comment>//
100    // replace first value and return its index
101    //
102    </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;
103    </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
104    </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>)
105    </span><span class=special>{
106       </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>);
107
108       </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>)
109           </span><span class=special>*</span><span class=identifier>found </span><span class=special>= </span><span class=identifier>replacement</span><span class=special>;
110       </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>);
111    </span><span class=special>}
112
113    </span><span class=comment>//
114    // usage
115    //
116    </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>;
117    </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>;
118    </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>};
119    </span>
120    <span class=identifier>my_vector</span><span class=special>.</span><span
121class=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>
122    </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>;
123    </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>),
124                                                </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>);
125    </span><span class=keyword>char  </span><span class=identifier>str_val</span><span class=special>[] </span><span class=special>= </span><span class=string>&quot;a string&quot;</span><span class=special>;
126    </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>;
127
128    </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>);
129    </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>);
130    </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=literal>'a'</span><span class=special>, </span><span class=literal>'b' </span><span class=special>);
131</span>
132    <span class=comment>// prints '3', '5' and '0'     </span>
133    </pre>
134    </blockquote>
135
136    By using the free-standing functions and <a
137href="../../mpl/doc/refmanual/metafunction.html">metafunctions</a>, the code automatically
138    works for all the types supported by this library; now and in the future.
139Notice that we have to
140    provide two version of <code  >find()</code> since we cannot forward a non-const
141    rvalue with reference arguments (see this article about  <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_self" >The
142    Forwarding Problem</a> ).
143
144    </p>
145
146
147    <hr>
148    <p>
149    (C) Copyright Thorsten Ottosen 2003-2004
150    </p>
151
152    <br>
153    <br>
154    <br>
155    <br>
156    <br>
157    <br>
158    <br>
159    <br>
160    <br>
161    <br>
162    <br>
163    <br>
164
165
166    </body>
167</html>
168
Note: See TracBrowser for help on using the repository browser.