feedc0de/boost_algorithm
1
0
Fork 0
forked from boostorg/algorithm
Code Pull Requests Activity

Documents updated to reflect collection traits removal

Browse Source 
[SVN r28274]
This commit is contained in:
Pavol Droba
2005-04-15 21:05:00 +00:00
parent 7ad6c08c68
commit 5419d39b2e
5 changed files with 28 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
string/doc/Jamfile.v2
View File

@ -21,7 +21,6 @@ doxygen autodoc
[ glob ../../../../boost/algorithm/string/iterator_range.hpp ] [ glob ../../../../boost/algorithm/string/iterator_range.hpp ]
[ glob ../../../../boost/algorithm/string/sequence_traits.hpp ] [ glob ../../../../boost/algorithm/string/sequence_traits.hpp ]
[ glob ../../../../boost/algorithm/string/std_containers_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/concept.hpp ]
[ glob ../../../../boost/algorithm/string/compare.hpp ] [ glob ../../../../boost/algorithm/string/compare.hpp ]
[ glob ../../../../boost/algorithm/string/constants.hpp ] [ glob ../../../../boost/algorithm/string/constants.hpp ]

161
string/doc/design.xml
View File

@ -18,15 +18,13 @@
</para> </para>
<para> <para>
<emphasis role="bold">Definition:</emphasis> A string is a <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. ordered fashion. Character is any value type with "cheap" copying and assignment.
</para> </para>
<para> <para>
First requirement of string-type is that it must accessible using 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. 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 This is sufficient for our library
</para> </para>
<para> <para>
@ -47,161 +45,6 @@
</para> </para>
</section> </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&lt;&gt;</code>, but
<code>std::pair&lt;&gt;</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&lt;&gt;</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&lt;iterator,iterator&gt;
</listitem>
</itemizedlist>
</para>
<para>
Collection traits support a subset of the container concept (Std &sect;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&lt;C&gt;</classname>::type</entry>
<entry><code>C::value_type</code></entry>
<entry>Type of contained values</entry>
</row>
<row>
<entry><classname>difference_type_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::difference_type</code></entry>
<entry>difference type of the collection</entry>
</row>
<row>
<entry><classname>iterator_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::iterator</code></entry>
<entry>iterator type of the collection</entry>
</row>
<row>
<entry><classname>const_iterator_of&lt;C&gt;</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&lt;C&gt;</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"> <section id="string_algo.sequence_traits">
<title>Sequence Traits</title> <title>Sequence Traits</title>

17
string/doc/release_notes.xml Normal file
View 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>

1
string/doc/string_algo.xml
View File

@ -33,6 +33,7 @@
<title>Boost String Algorithms Library</title> <title>Boost String Algorithms Library</title>
<xi:include href="intro.xml"/> <xi:include href="intro.xml"/>
<xi:include href="release_notes.xml"/>
<xi:include href="usage.xml"/> <xi:include href="usage.xml"/>
<xi:include href="quickref.xml"/> <xi:include href="quickref.xml"/>
<xi:include href="design.xml"/> <xi:include href="design.xml"/>

16
string/doc/usage.xml
View File

@ -46,10 +46,10 @@
<code>to_lower(str1)</code>, than <code>to_lower(str1.begin(), str1.end())</code>. <code>to_lower(str1)</code>, than <code>to_lower(str1.begin(), str1.end())</code>.
</para> </para>
<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. provides a uniform way of handling different string types.
If there is a need to pass a pair of iterators, 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. can be used to package iterators into a structure with a compatible interface.
</para> </para>
</listitem> </listitem>
@ -200,16 +200,16 @@
</programlisting> </programlisting>
<para> <para>
We have used <functionname>find_last()</functionname> to search the <code>text</code> for "ll". 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 This range delimits the
part of the input which satisfies the find criteria. In our example it is the last occurrence of "ll". 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 As we can see, input of the <functionname>find_last()</functionname> algorithm can be also
char[] because this type is supported by 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 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. <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. Also it is convertible to bool therefore it is easy to use find algorithms for a simple containment checking.
</para> </para>
@ -256,7 +256,7 @@
the find iterator allows us to iterate over the substrings matching the specified criteria. 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 This facility is using the <link linkend="string_algo.finder_concept">Finder</link> to incrementally
search the string. 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. object, that delimits the current match.
</para> </para>
<para> <para>
@ -274,7 +274,7 @@
It!=string_find_iterator(); It!=string_find_iterator();
++It) ++It)
{ {
cout &lt;&lt; copy_iterator_range&lt;std::string&gt;(*It) &lt;&lt; endl; cout &lt;&lt; copy_range&lt;std::string&gt;(*It) &lt;&lt; endl;
} }
// Output will be: // Output will be:
@ -288,7 +288,7 @@
It!=string_find_iterator(); It!=string_find_iterator();
++It) ++It)
{ {
cout &lt;&lt; copy_iterator_range&lt;std::string&gt;(*It) &lt;&lt; endl; cout &lt;&lt; copy_range&lt;std::string&gt;(*It) &lt;&lt; endl;
} }
// Output will be: // Output will be: