mirror of
https://github.com/boostorg/range.git
synced 2025-07-29 20:37:25 +02:00
*** empty log message ***
[SVN r24717]
This commit is contained in:
Thorsten Jørgen Ottosen
17
doc/faq.html
17
doc/faq.html
@ -30,11 +30,15 @@
|
||||
</p>
|
||||
<p>
|
||||
Note that an <a href="utility_class.html#iter_range">iterator_range</a>
|
||||
is somewhat more convenient than a <code>pair</code>. </p>
|
||||
is somewhat more convenient than a <code>pair</code> and that a <a
|
||||
href="utility_class.html#sub_range"><code>sub_range</code></a> do
|
||||
propagate const-ness. </p>
|
||||
|
||||
<li >
|
||||
<i>Why is there not supplied more types or more functions?</i>
|
||||
<p >
|
||||
The library have been kept small because its current interface will serve most
|
||||
The library has been kept small because its current interface will
|
||||
serve most
|
||||
purposes. If and when a genuine need arises for more functionality, it can be
|
||||
implemented.
|
||||
</p>
|
||||
@ -55,9 +59,14 @@ is somewhat more convenient than a <code>pair</code>. </p>
|
||||
Even though we speak of incrementable iterators, it would not make
|
||||
much sense for ranges; for example, we cannot determine the size and
|
||||
emptiness of a range since we cannot even compare
|
||||
its iterators.
|
||||
its iterators.
|
||||
</p>
|
||||
<p>
|
||||
Note also that incrementable iterators are derived from output
|
||||
iterators and so there exist no output range.
|
||||
</p>
|
||||
</li>
|
||||
<!--
|
||||
<li>
|
||||
<i>Should I use qualified syntax, for example
|
||||
<blockquote><pre>
|
||||
@ -100,7 +109,7 @@ is somewhat more convenient than a <code>pair</code>. </p>
|
||||
</blockquote>
|
||||
Cool indeed!
|
||||
</p>
|
||||
|
||||
-->
|
||||
|
||||
</ol>
|
||||
|
||||
|
||||
@ -50,7 +50,7 @@ C++ standard: <blockquote>
|
||||
<ul>
|
||||
<li> Pavol Droba for help with documentation and implementation
|
||||
<li> Pavel Vozenilek for help with porting the library
|
||||
<li> Jonathan Turkanis for help with documentation
|
||||
<li> Jonathan Turkanis and John Torjo for help with documentation
|
||||
<li> Hartmut Kaiser for being review manager
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
@ -18,17 +18,30 @@
|
||||
|
||||
<h2>Introduction</h2>
|
||||
<p>
|
||||
When writing generic code that works with standard library containers, one
|
||||
often finds it desirable to extend that code to work with other types that offer
|
||||
enough functionality to satisfy the needs of the generic code, but in an altered
|
||||
form. For example, raw arrays are often suitable for use with generic code that
|
||||
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
|
||||
href=range.html>Ranges</a> as much as possible.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The most common form of ranges we are used to work with is standard library
|
||||
containers. However, one
|
||||
often finds it desirable to extend that code to work with other types that
|
||||
offer
|
||||
enough functionality to satisfy the needs of the generic code
|
||||
<i>if a suitable layer of indirection is applied </i>. 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 provides the means to adapt standard library
|
||||
This library therefore provides the means to adapt standard-like
|
||||
containers,
|
||||
null terminated strings, <code>std::pairs</code> of iterators, and raw
|
||||
arrays (and more), such that the same generic code can work with them all.
|
||||
@ -51,17 +64,17 @@ free-standing functions so syntactic and/or semantic differences can be removed.
|
||||
The main advantages are
|
||||
<ul >
|
||||
<li >
|
||||
simpler implementation of generic range algorithms
|
||||
simpler implementation and specification of generic range algorithms
|
||||
</li>
|
||||
<li >
|
||||
more flexible client code
|
||||
more flexible, compact and maintainable client code
|
||||
</li>
|
||||
<li >
|
||||
correct handling of null-terminated strings
|
||||
</li>
|
||||
<li >
|
||||
safe use of built-in arrays (for legacy code; why else would you use
|
||||
arrays?) </li>
|
||||
built-in arrays?) </li>
|
||||
|
||||
</ul>
|
||||
</p>
|
||||
@ -112,9 +125,9 @@ class=identifier>ForwardReadableRange </span><span class=special>>::</span><s
|
||||
</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><span class=keyword>typedef </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special><</span><span class=keyword>int</span><span class=special>>::</span><span class=identifier>range_iterator </span><span class=identifier>range_iterator</span><span class=special>;
|
||||
</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special><</span><span class=identifier>range_iterator</span><span class=special>,</span><span class=identifier>range_iterator</span><span class=special>> </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>typedef </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special><</span><span class=keyword>int</span><span class=special>>::</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><</span><span class=identifier>iterator</span><span class=special>,</span><span class=identifier>iterator</span><span class=special>> </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>;
|
||||
|
||||
|
||||
@ -17,28 +17,53 @@
|
||||
</table>
|
||||
|
||||
<h2>Portability</h2><a name="Portability" ></a>
|
||||
<p >
|
||||
Full support for built-in arrays require that the compiler supports class
|
||||
template partial specialization. For non-conforming compilers there might
|
||||
be a chance that it works anyway thanks to workarounds in the type traits
|
||||
library. </p>
|
||||
<p >
|
||||
Notice that some compilers cannot do function template ordering properly. In
|
||||
that case one must rely of <code >result_iterator_of</code> and a
|
||||
single function definition instead of
|
||||
overloaded versions for const and non-const arguments.
|
||||
|
||||
|
||||
So if one cares about old compilers, one should not pass rvalues
|
||||
to the functions.
|
||||
|
||||
<p>
|
||||
A huge effort has been made to port the library to as many compilers as possible.
|
||||
The results of the test-suites can be found <a href="http://boost.sourceforge.net/regression-logs/developer/range.html">here</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A huge effort has been made to port the library to as many compilers as
|
||||
possible. The results of the test-suites can be found
|
||||
<a href="http://boost.sourceforge.net/regression-logs/developer/range.html">here</a>.
|
||||
Full support for built-in arrays require that the compiler supports class
|
||||
template partial specialization. For non-conforming compilers there might be a
|
||||
chance that it works anyway thanks to workarounds in the type traits library.
|
||||
</p>
|
||||
|
||||
<p >
|
||||
Notice also that some compilers cannot do function template ordering properly.
|
||||
In that case one must rely of <a
|
||||
href="boost_range.html#range_result_iterator"><code >range_result_iterator</code></a>
|
||||
and a single function definition instead of overloaded versions for const and
|
||||
non-const arguments.
|
||||
|
||||
So if one cares about old compilers, one should not pass rvalues to the
|
||||
functions.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For maximum portability you should follow these guidelines:
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
do not use built-in arrays
|
||||
<li>
|
||||
do not pass rvalues to <a
|
||||
href="boost_range.html#begin"><code>begin()</code></a>, <a
|
||||
href="boost_range.html#end"><code>end()</code></a> and <a href="utility_class.html#iter_range">
|
||||
<code>iterator_range</code></a> Range constructors and assignment operators,
|
||||
|
||||
<li>
|
||||
do not rely on ADL:
|
||||
<ul>
|
||||
<li>
|
||||
if you overload functions, include that header <i>before</i> the headers in this
|
||||
library,
|
||||
<li>
|
||||
put all overloads in namespace <code>boost</code>,
|
||||
</ul>
|
||||
|
||||
</ol>
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
|
||||
@ -68,8 +68,8 @@
|
||||
</ul>
|
||||
|
||||
|
||||
Because of the second requirement, a Range object must be passed by reference in
|
||||
generic code.
|
||||
Because of the second requirement, a Range object must be passed by
|
||||
(const or non-const) reference in generic code.
|
||||
|
||||
</p>
|
||||
<p>
|
||||
|
||||
@ -54,7 +54,7 @@ corresponding <code>const_iterator</code> is. </p>
|
||||
The intention of the <code>iterator_range</code> class is to encapsulate two
|
||||
iterators so they fulfill the <a
|
||||
href="range.html#forward_range">Forward Range</a> concept. A few other
|
||||
functions are also provided for convenience.
|
||||
functions are also provided for convenience.
|
||||
</p>
|
||||
<p>
|
||||
If the template argument is not a model of Forward Traversal Iterator, one can
|
||||
@ -63,6 +63,16 @@ functions are also provided for convenience.
|
||||
Pass Iterators.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Recall that many default constructed iterators
|
||||
are <i>singular</i> and hence can only be assigned, but not compared or
|
||||
incremented or anything. However, if one creates a default constructed
|
||||
<code>iterator_range</code>, then one
|
||||
can still call all its member functions. This means that the
|
||||
<code>iterator_range</code> will still be usable in many contexts even
|
||||
though the iterators underneath are not.
|
||||
</p>
|
||||
|
||||
<h3>Synopsis</h3>
|
||||
|
||||
<pre>
|
||||
|
||||
Reference in New Issue
Block a user