forked from boostorg/algorithm
Documents updated to reflect collection traits removal
[SVN r28274]
This commit is contained in:
Pavol Droba
@ -21,7 +21,6 @@ doxygen autodoc
|
||||
[ glob ../../../../boost/algorithm/string/iterator_range.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/sequence_traits.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/std_containers_traits.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/collection_traits.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/concept.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/compare.hpp ]
|
||||
[ glob ../../../../boost/algorithm/string/constants.hpp ]
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
17
string/doc/release_notes.xml
Normal file
17
string/doc/release_notes.xml
Normal file
@ -0,0 +1,17 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<section id="string_algo.release_notes" last-revision="$Date$">
|
||||
<title>Release Notes</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">1.32</emphasis></para>
|
||||
<para>Initial release in Boost</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">1.33</emphasis></para>
|
||||
<para>Internal version of collection traits removed, library adapted to Boost.Range</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
@ -33,6 +33,7 @@
|
||||
|
||||
<title>Boost String Algorithms Library</title>
|
||||
<xi:include href="intro.xml"/>
|
||||
<xi:include href="release_notes.xml"/>
|
||||
<xi:include href="usage.xml"/>
|
||||
<xi:include href="quickref.xml"/>
|
||||
<xi:include href="design.xml"/>
|
||||
|
||||
@ -46,10 +46,10 @@
|
||||
<code>to_lower(str1)</code>, than <code>to_lower(str1.begin(), str1.end())</code>.
|
||||
</para>
|
||||
<para>
|
||||
The magic of <link linkend="string_algo.collection_traits">collection_traits</link>
|
||||
The magic of <ulink url="../../libs/range/index.html">Boost.Range</ulink>
|
||||
provides a uniform way of handling different string types.
|
||||
If there is a need to pass a pair of iterators,
|
||||
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
|
||||
<ulink url="../../libs/range/doc/utility_class.html"><code>boost::iterator_range</code></ulink>
|
||||
can be used to package iterators into a structure with a compatible interface.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -200,16 +200,16 @@
|
||||
</programlisting>
|
||||
<para>
|
||||
We have used <functionname>find_last()</functionname> to search the <code>text</code> for "ll".
|
||||
The result is given in the <link linkend="string_algo.iterator_range"><code>iterator_range</code></link>.
|
||||
The result is given in the <ulink url="../../libs/range/doc/utility_class.html"><code>boost::iterator_range</code></ulink>.
|
||||
This range delimits the
|
||||
part of the input which satisfies the find criteria. In our example it is the last occurrence of "ll".
|
||||
|
||||
As we can see, input of the <functionname>find_last()</functionname> algorithm can be also
|
||||
char[] because this type is supported by
|
||||
<link linkend="string_algo.collection_traits">collection_traits</link>.
|
||||
<ulink linkend="../../libs/range/doc/index.html">Boost.Range</ulink>.
|
||||
|
||||
The following lines transform the result. Notice that
|
||||
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link> has familiar
|
||||
<ulink url="../../libs/range/doc/utility_class.html"><code>boost::iterator_range</code></ulink> has familiar
|
||||
<code>begin()</code> and <code>end()</code> methods, so it can be used like any other STL container.
|
||||
Also it is convertible to bool therefore it is easy to use find algorithms for a simple containment checking.
|
||||
</para>
|
||||
@ -256,7 +256,7 @@
|
||||
the find iterator allows us to iterate over the substrings matching the specified criteria.
|
||||
This facility is using the <link linkend="string_algo.finder_concept">Finder</link> to incrementally
|
||||
search the string.
|
||||
Dereferencing a find iterator yields an <link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
|
||||
Dereferencing a find iterator yields an <ulink url="../../libs/range/doc/utility_class.html"><code>boost::iterator_range</code></ulink>
|
||||
object, that delimits the current match.
|
||||
</para>
|
||||
<para>
|
||||
@ -274,7 +274,7 @@
|
||||
It!=string_find_iterator();
|
||||
++It)
|
||||
{
|
||||
cout << copy_iterator_range<std::string>(*It) << endl;
|
||||
cout << copy_range<std::string>(*It) << endl;
|
||||
}
|
||||
|
||||
// Output will be:
|
||||
@ -288,7 +288,7 @@
|
||||
It!=string_find_iterator();
|
||||
++It)
|
||||
{
|
||||
cout << copy_iterator_range<std::string>(*It) << endl;
|
||||
cout << copy_range<std::string>(*It) << endl;
|
||||
}
|
||||
|
||||
// Output will be:
|
||||
|
||||
Reference in New Issue
Block a user