forked from boostorg/algorithm
Documents updated to reflect collection traits removal
[SVN r28274]
This commit is contained in:
Pavol Droba
@ -18,15 +18,13 @@
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="bold">Definition:</emphasis> A string is a
|
||||
<ulink url="../../libs/utility/Collection.html">collection</ulink> of characters accessible in sequential
|
||||
<ulink url="../../libs/range/doc/range.html">range</ulink> of characters accessible in sequential
|
||||
ordered fashion. Character is any value type with "cheap" copying and assignment.
|
||||
</para>
|
||||
<para>
|
||||
First requirement of string-type is that it must accessible using
|
||||
<link linkend="string_algo.collection_traits">collection traits</link>. This facility allows to access
|
||||
<ulink url="../../libs/range/index.html">Boost.Range</ulink>. This facility allows to access
|
||||
the elements inside the string in a uniform iterator-based fashion.
|
||||
This requirement is actually less stringent than that of collection concept. It implements
|
||||
an <ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection interface.
|
||||
This is sufficient for our library
|
||||
</para>
|
||||
<para>
|
||||
@ -47,161 +45,6 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
<section id="string_algo.iterator_range">
|
||||
<title><code>iterator_range</code> class</title>
|
||||
|
||||
<para>
|
||||
An <classname>iterator_range</classname> is an encapsulation of a pair of iterators that
|
||||
delimit a sequence (or, a range). This concept is widely used by
|
||||
sequence manipulating algorithms. Although being so useful, there no direct support
|
||||
for it in the standard library (The closest thing is that some algorithms return a pair of iterators).
|
||||
Instead all STL algorithms have two distinct parameters for beginning and end of a range. This design
|
||||
is natural for implementation of generic algorithms, but it forbids to work with a range as a single value.
|
||||
</para>
|
||||
<para>
|
||||
It is possible to encapsulate a range in <code>std::pair<></code>, but
|
||||
<code>std::pair<></code> is an overly generic encapsulation, so it is not best match for a range.
|
||||
For instance, it does not enforce that begin and end iterators be of the same type.
|
||||
</para>
|
||||
<para>
|
||||
Naturally the range concept is heavily used also in this library. During the development of
|
||||
the library, it was discovered, that there is a need for a reasonable encapsulation for it, since
|
||||
core part of the library deals with substring searching algorithms and any such algorithm
|
||||
returns a range delimiting the result of the search. <code>std::pair<></code> was deemed as
|
||||
unsuitable. Therefore the <code>iterator_range</code> was defined.
|
||||
</para>
|
||||
<para>
|
||||
The intention of the <code>iterator_range</code> class is to manage a range as a single value and provide
|
||||
a basic interface for common operations. Its interface is similar to that of a collection.
|
||||
In addition to <code>begin()</code>
|
||||
and <code>end()</code> accessors, it has member functions for checking whether the range is empty,
|
||||
or to determine the size of the range. It also has a set of member typedefs that extract
|
||||
type information from the encapsulated iterators. As such, the interface is compatible with
|
||||
the <link linkend="string_algo.collection_traits">collection traits</link> requirements so
|
||||
it is possible to use this class as a parameter to many algorithms in this library.
|
||||
</para>
|
||||
<para>
|
||||
<classname>iterator_range</classname> will be moved to Boost.Range library in the future
|
||||
releases. The internal version will be deprecated then.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="string_algo.collection_traits">
|
||||
<title>Collection Traits</title>
|
||||
|
||||
<para>
|
||||
Collection traits provide uniform access to different types of
|
||||
<ulink url="../../libs/utility/Collection.html">collections</ulink> .
|
||||
This functionality allows to write generic algorithms which work with several
|
||||
different kinds of collections. For this library it means, that, for instance,
|
||||
many algorithms work with <code>std::string</code> as well as with <code>char[]</code>.
|
||||
This facility implements the
|
||||
<ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection
|
||||
concept.
|
||||
</para>
|
||||
<para>
|
||||
The following collection types are supported:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
Standard containers
|
||||
</listitem>
|
||||
<listitem>
|
||||
Built-in arrays (like int[])
|
||||
</listitem>
|
||||
<listitem>
|
||||
Null terminated strings (this includes char[],wchar_t[],char*, and wchar_t*)
|
||||
</listitem>
|
||||
<listitem>
|
||||
std::pair<iterator,iterator>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
Collection traits support a subset of the container concept (Std §23.1). This subset
|
||||
can be described as an input container concept, e.g. a container with immutable content.
|
||||
Its definition can be found in the header <headername>boost/algorithm/string/collection_traits.hpp</headername>.
|
||||
</para>
|
||||
<para>
|
||||
In the table C denotes a container and c is an object of C.
|
||||
</para>
|
||||
<table>
|
||||
<title>Collection Traits</title>
|
||||
<tgroup cols="3" align="left">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Name</entry>
|
||||
<entry>Standard collection equivalent</entry>
|
||||
<entry>Description</entry>
|
||||
</row>Maeterlinck
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><classname>value_type_of<C></classname>::type</entry>
|
||||
<entry><code>C::value_type</code></entry>
|
||||
<entry>Type of contained values</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><classname>difference_type_of<C></classname>::type</entry>
|
||||
<entry><code>C::difference_type</code></entry>
|
||||
<entry>difference type of the collection</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><classname>iterator_of<C></classname>::type</entry>
|
||||
<entry><code>C::iterator</code></entry>
|
||||
<entry>iterator type of the collection</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><classname>const_iterator_of<C></classname>::type</entry>
|
||||
<entry><code>C::const_iterator</code></entry>
|
||||
<entry>const_iterator type of the collection</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><classname>result_iterator_of<C></classname>::type</entry>
|
||||
<entry></entry>
|
||||
<entry>
|
||||
result_iterator type of the collection. This type maps to <code>C::iterator</code>
|
||||
for mutable collection and <code>C::const_iterator</code> for const collection.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><functionname>begin(c)</functionname></entry>
|
||||
<entry><code>c.begin()</code></entry>
|
||||
<entry>
|
||||
Gets the iterator pointing to the start of the collection.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><functionname>end(c)</functionname></entry>
|
||||
<entry><code>c.end()</code></entry>
|
||||
<entry>
|
||||
Gets the iterator pointing to the end of the collection.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><functionname>size(c)</functionname></entry>
|
||||
<entry><code>c.size()</code></entry>
|
||||
<entry>
|
||||
Gets the size of the collection.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><functionname>empty(c)</functionname></entry>
|
||||
<entry><code>c.empty()</code></entry>
|
||||
<entry>
|
||||
Checks if the collection is empty.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<para>
|
||||
The collection traits are only a temporary part of this library. They will be replaced in the future
|
||||
releases by Boost.Range library. Use of the internal implementation will be deprecated then.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section id="string_algo.sequence_traits">
|
||||
<title>Sequence Traits</title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user