123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223 |
- <?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">
- <!-- Copyright (c) 2002-2006 Pavol Droba.
- Subject to the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
- -->
- <section id="string_algo.design" last-revision="$Date$">
- <title>Design Topics</title>
- <using-namespace name="boost"/>
- <using-namespace name="boost::algorithm"/>
- <section id="string_algo.string">
- <title>String Representation</title>
- <para>
- As the name suggest, this library works mainly with strings. However, in the context of this library,
- a string is not restricted to any particular implementation (like <code>std::basic_string</code>),
- rather it is a concept. This allows the algorithms in this library to be reused for any string type,
- that satisfies the given requirements.
- </para>
- <para>
- <emphasis role="bold">Definition:</emphasis> A string is a
- <ulink url="../../libs/range/index.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
- <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 is sufficient for our library
- </para>
- <para>
- Second requirement defines the way in which the characters are stored in the string. Algorithms in
- this library work with an assumption that copying a character is cheaper then allocating extra
- storage to cache results. This is a natural assumption for common character types. Algorithms will
- work even if this requirement is not satisfied, however at the cost of performance degradation.
- <para>
- </para>
- In addition some algorithms have additional requirements on the string-type. Particularly, it is required
- that an algorithm can create a new string of the given type. In this case, it is required that
- the type satisfies the sequence (Std §23.1.1) requirements.
- </para>
- <para>
- In the reference and also in the code, requirement on the string type is designated by the name of
- template argument. <code>RangeT</code> means that the basic range requirements must hold.
- <code>SequenceT</code> designates extended sequence requirements.
- </para>
- </section>
-
- <section id="string_algo.sequence_traits">
- <title>Sequence Traits</title>
- <para>
- The major difference between <code>std::list</code> and <code>std::vector</code> is not in the interfaces
- they provide, but rather in the inner details of the class and the way how it performs
- various operations. The problem is that it is not possible to infer this difference from the
- definitions of classes without some special mechanism.
- However, some algorithms can run significantly faster with the knowledge of the properties
- of a particular container.
- </para>
- <para>
- Sequence traits allow one to specify additional properties of a sequence container (see Std.§32.2).
- These properties are then used by algorithms to select optimized handling for some operations.
- The sequence traits are declared in the header
- <headername>boost/algorithm/string/sequence_traits.hpp</headername>.
- </para>
- <para>
- In the table C denotes a container and c is an object of C.
- </para>
- <table>
- <title>Sequence Traits</title>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Trait</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><classname>has_native_replace<C></classname>::value</entry>
- <entry>Specifies that the sequence has std::string like replace method</entry>
- </row>
- <row>
- <entry><classname>has_stable_iterators<C></classname>::value</entry>
- <entry>
- Specifies that the sequence has stable iterators. It means,
- that operations like <code>insert</code>/<code>erase</code>/<code>replace</code>
- do not invalidate iterators.
- </entry>
- </row>
- <row>
- <entry><classname>has_const_time_insert<C></classname>::value</entry>
- <entry>
- Specifies that the insert method of the sequence has
- constant time complexity.
- </entry>
- </row>
- <row>
- <entry><classname>has_const_time_erase<C></classname>::value</entry>
- <entry>
- Specifies that the erase method of the sequence has constant time complexity
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- Current implementation contains specializations for std::list<T> and
- std::basic_string<T> from the standard library and SGI's std::rope<T> and std::slist<T>.
- </para>
- </section>
- <section id="string_algo.find">
- <title>Find Algorithms</title>
- <para>
- Find algorithms have similar functionality to <code>std::search()</code> algorithm. They provide a different
- interface which is more suitable for common string operations.
- Instead of returning just the start of matching subsequence they return a range which is necessary
- when the length of the matching subsequence is not known beforehand.
- This feature also allows a partitioning of the input sequence into three
- parts: a prefix, a substring and a suffix.
- </para>
- <para>
- Another difference is an addition of various searching methods besides find_first, including find_regex.
- </para>
- <para>
- It the library, find algorithms are implemented in terms of
- <link linkend="string_algo.finder_concept">Finders</link>. Finders are used also by other facilities
- (replace,split).
- For convenience, there are also function wrappers for these finders to simplify find operations.
- </para>
- <para>
- Currently the library contains only naive implementation of find algorithms with complexity
- O(n * m) where n is the size of the input sequence and m is the size of the search sequence.
- There are algorithms with complexity O(n), but for smaller sequence a constant overhead is
- rather big. For small m << n (m by magnitude smaller than n) the current implementation
- provides acceptable efficiency.
- Even the C++ standard defines the required complexity for search algorithm as O(n * m).
- It is possible that a future version of library will also contain algorithms with linear
- complexity as an option
- </para>
- </section>
- <section id="string_algo.replace">
- <title>Replace Algorithms</title>
- <para>
- The implementation of replace algorithms follows the layered structure of the library. The
- lower layer implements generic substitution of a range in the input sequence.
- This layer takes a <link linkend="string_algo.finder_concept">Finder</link> object and a
- <link linkend="string_algo.formatter_concept">Formatter</link> object as an input. These two
- functors define what to replace and what to replace it with. The upper layer functions
- are just wrapping calls to the lower layer. Finders are shared with the find and split facility.
- </para>
- <para>
- As usual, the implementation of the lower layer is designed to work with a generic sequence while
- taking advantage of specific features if possible
- (by using <link linkend="string_algo.sequence_traits">Sequence traits</link>)
- </para>
- </section>
- <section id="string_algo.split">
- <title>Find Iterators & Split Algorithms</title>
- <para>
- Find iterators are a logical extension of the <link linkend="string_algo.find">find facility</link>.
- Instead of searching for one match, the whole input can be iteratively searched for multiple matches.
- The result of the search is then used to partition the input. It depends on the algorithms which parts
- are returned as the result. They can be the matching parts (<classname>find_iterator</classname>) of the parts in
- between (<classname>split_iterator</classname>).
- </para>
- <para>
- In addition the split algorithms like <functionname>find_all()</functionname> and <functionname>split()</functionname>
- can simplify the common operations. They use a find iterator to search the whole input and copy the
- matches they found into the supplied container.
- </para>
- </section>
- <section id="string_algo.exception">
- <title>Exception Safety</title>
- <para>
- The library requires that all operations on types used as template
- or function arguments provide the <emphasis>basic exception-safety guarantee</emphasis>.
- In turn, all functions and algorithms in this library, except where stated
- otherwise, will provide the <emphasis>basic exception-safety guarantee</emphasis>.
- In other words:
- The library maintains its invariants and does not leak resources in
- the face of exceptions. Some library operations give stronger
- guarantees, which are documented on an individual basis.
- </para>
-
- <para>
- Some functions can provide the <emphasis>strong exception-safety guarantee</emphasis>.
- That means that following statements are true:
- <itemizedlist>
- <listitem>
- If an exception is thrown, there are no effects other than those
- of the function
- </listitem>
- <listitem>
- If an exception is thrown other than by the function, there are no effects
- </listitem>
- </itemizedlist>
- This guarantee can be provided under the condition that the operations
- on the types used for arguments for these functions either
- provide the strong exception guarantee or do not alter the global state .
- </para>
- <para>
- In the reference, under the term <emphasis>strong exception-safety guarantee</emphasis>, we mean the
- guarantee as defined above.
- </para>
- <para>
- For more information about the exception safety topics, follow this
- <ulink url="http://www.boost.org/more/generic_exception_safety.html">link</ulink>
- </para>
- </section>
- </section>
|