-Of course, there are many factors that affect the performance of an algorithm.
-The number of comparison is only one, but also branch prediction, pipelining,
-locality of reference (affects cache efficiency), etc. In practice,
-we observe that when the iterator type is a pointer,
-boost::minmax_element
-is only a tad slower than
-std::min_element, and is even faster
-than
-boost::first_min_last_max_element! This is even more true
-for slower iterators (list<>::iterator or
-map<>iterator
-for instance). The following experiments were conducted on a Pentium III
-500 Mhz running Linux and compiled with g++, version 2.95.2, flags -O3.
-In the tables, we use different distributions: Identical means that
-all the elements are identical, 2-valued means that we replace the
-second half of the identical elements by a distinct element, increasing
-means that all the elements are distinct and in increasing order, decreasing
-is the reverse, and random is produced by random_shuffle.
-
-The program that created these tables is included in the distribution,
-under minmax_timer.cpp
-
-
-
-
vector<int>::iterator
-
-
Identical
-
-
2-valued
-
-
Increasing
-
-
Decreasing
-
-
Random
-
-
-
-
std::min_element
-
-
23.26M/s
-
-
23.26M/s
-
-
23.15M/s
-
-
22.94M/s
-
-
22.94M/s
-
-
-
-
std::max_element
-
-
23.26M/s
-
-
23.26M/s
-
-
23.15M/s
-
-
22.94M/s
-
-
22.62M/s
-
-
-
-
boost::first_min_element
-
-
23.15M/s
-
-
23.04M/s
-
-
23.04M/s
-
-
22.94M/s
-
-
22.83M/s
-
-
-
-
boost::last_min_element
-
-
23.26M/s
-
-
23.26M/s
-
-
23.26M/s
-
-
22.83M/s
-
-
16.23M/s
-
-
-
-
boost::first_max_element
-
-
23.15M/s
-
-
23.26M/s
-
-
23.15M/s
-
-
23.04M/s
-
-
22.93M/s
-
-
-
-
boost::last_max_element
-
-
23.26M/s
-
-
23.15M/s
-
-
23.15M/s
-
-
22.94M/s
-
-
16.18M/s
-
-
-
-
boost::minmax_element
-
-
21.83M/s
-
-
21.83M/s
-
-
21.83M/s
-
-
21.55M/s
-
-
17.79M/s
-
-
-
-
boost::first_min_last_max_element
-
-
18.52M/s
-
-
18.38M/s
-
-
18.38M/s
-
-
18.94M/s
-
-
16.29M/s
-
-
-
-
boost::last_min_first_max_element
-
-
20.08M/s
-
-
20.83M/s
-
-
20.75M/s
-
-
19.76M/s
-
-
15.87M/s
-
-
-
-
boost::last_min_last_max_element
-
-
18.66M/s
-
-
19.69M/s
-
-
19.69M/s
-
-
19.23M/s
-
-
15.77M/s
-
-
-
Number of elements per second for standard vector
-container iterators
-
-
-
-
-
list<int>::iterator
-
-
Identical
-
-
2-valued
-
-
Increasing
-
-
Decreasing
-
-
Random
-
-
-
-
std::min_element
-
-
5.8M/s
-
-
5.8M/s
-
-
5.80M/s
-
-
5.73M/s
-
-
5.73M/s
-
-
-
-
std::max_element
-
-
5.81M/s
-
-
5.81M/s
-
-
5.78M/s
-
-
5.73M/s
-
-
5.75M/s
-
-
-
-
boost::first_min_element
-
-
5.81M/s
-
-
5.81M/s
-
-
5.79M/s
-
-
5.75M/s
-
-
5.73M/s
-
-
-
-
boost::last_min_element
-
-
5.81M/s
-
-
5.80M/s
-
-
5.79M/s
-
-
5.73M/s
-
-
5.03M/s
-
-
-
-
boost::first_max_element
-
-
5.81M/s
-
-
5.80M/s
-
-
5.78M/s
-
-
5.74M/s
-
-
5.73M/s
-
-
-
-
boost::last_max_element
-
-
5.81M/s
-
-
5.80M/s
-
-
5.79M/s
-
-
5.73M/s
-
-
5.07M/s
-
-
-
-
boost::minmax_element
-
-
5.68M/s
-
-
5.80M/s
-
-
5.66M/s
-
-
5.74M/s
-
-
5.30M/s
-
-
-
-
boost::first_min_last_max_element
-
-
5.79M/s
-
-
5.81M/s
-
-
5.78M/s
-
-
5.73M/s
-
-
5.04M/s
-
-
-
-
boost::last_min_first_max_element
-
-
5.69M/s
-
-
5.79M/s
-
-
5.69M/s
-
-
5.73M/s
-
-
4.84M/s
-
-
-
-
boost::last_min_last_max_element
-
-
5.61M/s
-
-
5.79M/s
-
-
5.64M/s
-
-
5.74M/s
-
-
4.75M/s
-
-
-
Runtimes for standard list container iterators
-
-
-
-
-
multiset<int>::iterator
-
-
Identical
-
-
2-valued
-
-
Increasing
-
-
Decreasing
-
-
Random
-
-
-
-
std::min_element
-
-
4.03M/s
-
-
4.04M/s
-
-
4.02M/s
-
-
4.04M/s
-
-
2.97M/s
-
-
-
-
std::max_element3.007M
-
-
4.02M/s
-
-
4.02M/s
-
-
4.01M/s
-
-
4.02M/s
-
-
2.96M/s
-
-
-
-
boost::first_min_element
-
-
4.01M/s
-
-
4.04M/s
-
-
4.03M/s
-
-
4.04M/s
-
-
3.01M/s
-
-
-
-
boost::last_min_element
-
-
4.03M/s
-
-
4.04M/s
-
-
4.04M/s
-
-
4.04M/s
-
-
3.00M/s
-
-
-
-
boost::first_max_element
-
-
4.04M/s
-
-
4.04M/s
-
-
4.04M/s
-
-
4.06M/s
-
-
3.01M/s
-
-
-
-
boost::last_max_element
-
-
4.04M/s
-
-
4.04M/s
-
-
4.03M/s
-
-
4.04M/s
-
-
3.00M/s
-
-
-
-
boost::minmax_element
-
-
3.98M/s
-
-
3.99M/s
-
-
3.98M/s
-
-
3.99M/s
-
-
3.00M/s
-
-
-
-
boost::first_min_last_max_element
-
-
3.99M/s
-
-
3.98M/s
-
-
3.97M/s
-
-
3.99M/s
-
-
2.99M/s
-
-
-
-
boost::last_min_first_max_element
-
-
3.97M/s
-
-
3.98M/s
-
-
3.96M/s
-
-
3.98M/s
-
-
3.00M/s
-
-
-
-
boost::last_min_last_max_element
-
-
4.00M/s
-
-
4.00M/s
-
-
4.00M/s
-
-
4.02M/s
-
-
2.97M/s
-
-
-
Runtimes for standard set/multiset container iterators
The minmax library is composed of two headers, <boost/algorithm/minmax.hpp>
-and <boost/algorithm/minmax_element.hpp>.
-(See rationale.)
-The problem solved by this library is that simultaneous min and max
-computation requires
-only one comparison, but using std::min and std::max
-forces two comparisons. Worse, to compute the minimum and
-maximum elements of a range of n elements requires only
-3n/2+1 comparisons, instead of the 2n (in two passes)
-forced by std::min_element and std::max_element.
-I always thought it is a waste to have to call two functions to compute the
-extent of a range, performing two passes over the input, when one should
-be enough. The present library solves both problems.
-
-
The first file implements the function templates
-minmax
-as straightforward extensions of the C++
-standard. As it returns a pair of const&, we must use the Boost.tuple library to construct such
-pairs. (Please note: the intent is not to fix the known defaults of
-std::min
-and std::max, but to add one more algorithms that combines both; see the
-rationale.)
-
-
The second file implements the function templates
-minmax_element. In a
-second part, it also proposes variants that can usually not be computed by
-the minmax algorithm, and which are more flexible in case some elements are equal.
-Those variants could have been also provided with policy-based design,
-but I ruled against that (see rationale).
-
-
-
If you are interested about
-performance,
-you will see that minmax_element is just slightly less efficient
-than a single min_element or max_element, and thus
-twice as efficient as two separate calls to min_element and
-max_element. From a
-theoretical standpoint,
-all the minmax_element functions perform at most
-3n/2+1
-comparisons and exactly n increments of the
-ForwardIterator.
-
-In addition, there are a bunch of extensions which specify
-which element(s) you want to pick in case of equal elements. They are:
-
-
first_min_element and last_min_element
-
first_max_element and last_max_element
-
first_min_first_max_element,
-first_min_last_max_element,
-last_min_first_max_element, and
-last_min_last_max_element
-
-I won't bore you with the complete synopsis, they have exactly the same
-declaration as their corresponding _element function. Still,
-you can find the complete synopsis here.
-
-
-
-
The minmax_element is semantically equivalent to first_min_first_max_element.
-
First_min_element and first_max_element find the smallest
-and largest elements in the range [first, last). If there are
-several instance of these elements, the first one is returned. They are
-identical to
-std::min_element and std::max_elementand
-are only included in this library for symmetry.
-
Last_min_element and last_max_element find the smallest
-and largest elements in the range [first, last). They are almost
-identical to
-std::min_element and std::max_element, except
-that they return the last instance of the largest element (and not the
-first, as first_min_element and last_max_element would).
-
The family of algorithms comprising first_min_first_max_element,
-first_min_first_max_element,
-first_min_first_max_element,
-and first_min_first_max_element can be described generically as
-follows (using which and
-what for first
-or last): which_min_what_max_element finds
-the (first or last, according to which) smallest element
-and the (first or last, according to what) largest element
-in the range
-[first, last). The first version is semantically
-equivalent to:
-
-Minmax performs a single comparison and is otherwise of constant complexity.
-The use of boost::tuple<T const&> prevents copy
-constructors in case the arguments are passed by reference.
-
The complexity of all the other algorithms is linear. They all perform
-exactly n increment operations, and zero comparisons if [first,last)
-is empty, otherwise :
-
-
-all the min_element and max_element variants perform
-exactly(n-1) comparisons,
-
-
-minmax_element , first_min_first_max_element, and last_min_last_max_element
-perform at most 3(n/2)-1 comparisons if n is even and
-non-zero, and at most 3(n/2)+1 if n is odd,
-[2]
-
-
-first_min_last_max_element, and last_min_first_max_element
-perform exactly 3n/2-2 comparisons if n is even and non-zero,
-and at most 3(n/2) if n is odd,
-[3]
-
-where n is the number of elements in [first,last).
-
-
-
-
-[1] We do not support
-idioms such as tie(a,b)=minmax(a,b)
-to order two elements a, b, although this would have
-the desired effect if we returned a reference instead of a constant
-reference. The reason is that two unnecessary assignments are
-performed if a and b are in order. It is better to stick to if (b<a)
-swap(a,b) to achieve that effect.
-
[2] These algorithms always
-perform at least 3n/2-2 comparisons, which is a lower bound on
-the number of comparisons in any case (Cormen, Leiserson, Rivest: "Introduction
-to Algorithms", section 9.1, Exercise 9.1-). The algorithms essentially compare
-the elements in pairs, performing 1 comparison for the first two elements,
-then 3 comparisons for each remaining pair of elements (one to order the
-elements and one for updating each the minimum and and the maximum). When
-the number of elements is odd, the last one needs to be compared to the
-current minimum and also to the current maximum. In addition, for minmax,
-in cases where equality of the two members in the pair could occur, and
-the update stores the second, we save the first to check at the end if
-the update should have stored the first (in case of equality). It's hard
-to predict if the last comparison is performed or not, hence the at most
-in both cases.
-
[3] These algorithms always
-perform at least 3n/2-2 comparisons, which is a lower bound on
-the number of comparisons in any case. The method is the same as in note
-[2]
-above, and like above, when the number of elements is odd, the last one
-needs to be compared to the current minimum and also to the current maximum.
-We can avoid the latter comparison if the former is successful, hence the
-at
-most instead of exactly in the odd case.
-
-
-
-
In a first version of the library, I proposed _if versions of
-all the algorithms (well, not all, because that would be too much).
-However, there is simply no reason to do so, and all the versions I had
-were just as fast implemented using the excellent
-<boost/iterator_adaptors.hpp> library. Namely, a call to
-min_element_if(first, last, pred) would be just as well
-implemented by:
-
- // equivalent to min_element_if(first, last, pred)
- min_element(boost::make_filter_iterator(first, last, pred),
- boost::make_filter_iterator(last, last, pred));
-
-Arguably, the min_element_if version is somewhat shorter, but
-the overhead of iterator adaptors is not large, and they get rid of a
-lot of code (think of all the combinations between first/last and
-doubling them with _if variants!).
-
-
Discussion: about std::max_element
-
This rationale is somewhat historical, but explains why there are all
-these first/last_min/max_element functions.
-
The C++ standard mandates that std::min_element and std::max_element
-return the first instance of the smallest and largest elements (as opposed
-to, say, the last). This arbitrary choice has some consistency: In the
-case of v of type vector<int>, for instance, it is true that std::min_element(v.begin(),v.end(),std::less<int>())
-== std::max_element(v.begin(),v.end(),std::greater<int>()).
-
There is of course nothing wrong with this: it's simply a matter of
-choice. Yet another way to specify min_element and max_element is to define
-them as the first and the last elements if the range was stably sorted.
-(The stable sort is necessary to disambiguate between iterators
-that have the same value.) In that case, min should return the first instance
-and max should return the last. Then, both functions are related by
-reverse_iterator(std::first_min_element(v.begin(),v.end(),std::less<int>()))
-==
-std::last_max_element(v.rbegin(),v.rend(),std::greater<int>()).
-This definition is subtly different from the previous one.
-
The definition problem surfaces when one tries to design a minmax_element,
-using the procedure proposed in (Cormen, Leiserson, Rivest: "Introduction
-to Algorithms", section 9.1). It should be possible to derive an
-algorithm using only 3n/2 comparisons if [first,last) has
-n
-elements, but if one tries to write a function called first_min_first_max_element()
-which returns both std::min_element and std::max_element
-in a pair, the trivial implementation does not work. The problem, rather
-subtly, is about equal elements: I had to think for a while to find a
-way to perform only three
-comparisons per pair and return the first min and first max elements.
-For a long time, it seemed any
-attempts at doing so would consume four comparisons per pair in the worst
-case. This implementation achieves three.
-
It is not possible (or even desirable) to change the meaning of
-max_element,
-but it is still beneficial to provide a function called minmax_element,
-which returns a pair of min_element and max_element.
-Although it is easy enough to call min_element and max_element,
-this performs
-2(n-1) comparisons, and necessitates two
-passes over the input. In contrast,
-minmax_element will perform
-the fewer comparisons and perform a single pass over the input.
-The savings can be significant when the iterator type is not a raw pointer,
-or even is just a model of the InputIterator concept (although in that
-case the interface would have to be
-changed, as the return type could not be copied, so one could e.g.
-return a value).
-
In order to benefit from all the variants of the algorithm, I propose
-to introduce both first_min_element and last_min_element,
-and their counterparts first_max_element and last_max_element.
-Then I also propose all the variants algorithms: first_min_last_max_element
-and last_min_first_max_element, which perform only at most 3n/2
-comparisons, and only a single pass on the input. In fact, it can be proven
-that computing minmax requires at least 3(n/2)-2 comparisons in
-any instance of the problem (Cormen, Leiserson, Rivest, 2nd edition, section
-9.1). The implementation I give does not perform unnecessary comparisons
-(whose result could have been computed by transitivity from previous
-comparisons).
-
It appears that first_min_last_max_element may be just a tad
-slower than
-first_min_element alone, still much less than first_min_element
-and
-last_max_element called separately. [2]
-
-
Why algorithms and not accumulators?
-
The minmax algorithms are useful in computing the extent of a range.
-In computer graphics, we need a bounding box of a set of objects.
-In that case the need for a single pass is even more stringent
-as all three directions must be done at once. Food for thoughts: there
-is matter for a nice generic programming library with stackable update_min
-and update_max function objects which store a reference to the
-min_resultand
-max_result variables, in conjunction with the for_each
-algorithm).
-
I believe many standard sequential algorithms could be reformulated
-with accumulators (and many others, such as in statistics, expectation /
-variance / etc.). It seems that there is room for another library, but I
-do not see it competing with minmax, rather extending several algorithms
-(including minmax) to the accumulator framework. However, I felt it is
-beyond the scope of this library to provide such accumulators.
-My students in CS903 (Polytechnic Univ., http://photon.poly.edu/~hbr/cs903/)
-who had minmax_element as an assignment helped clarify the issues,
-and also come up with the optimum number of comparisons for first_min_last_max_element.
-The identification of the issue surrounding max_element is solely
-my own.
-
One minmax_element implementation, which performs 3(n/2)+O(log
-n) comparisons on the average when the elements are random_shuffled,
-was suggested by my student Marc Glisse. The current one, which performs
-3(n/2)+1
-comparisons in the worst case, was suggested by John Iacono.
-
Finally, Matthew Wilson and Jeremy Siek contributed pre-review
-comments, while Gennadiy Rozental, John Maddock, Craig Henderson, Gary
-Powell participated in the review of the library, managed by Thomas
-Witt. In particular, Gennadiy suggested a factorization of the code;
-while I haven't followed it all the way, his suggestions do make the
-code more readable and still work with older compilers.
-Late after the review, as I finally scrounged to add the library for a
-release, Eric Niebler noted the bad behavior of std::pair for
-minmax and suggested to use Boost.tuple instead.
-All my thanks for the excellent advice and reviews from all.
-
- Notation
-
-
-
- F
- A type that is a model of Finder
-
-
- Fmt
- A type that is a model of Formatter
-
-
- Iter
-
- Iterator Type
-
-
-
- f
- Object of type F
-
-
- fmt
- Object of type Fmt
-
-
- i,j
- Objects of type Iter
-
-
-
-
-
-
-
- Finder Concept
-
-
- Finder is a functor which searches for an arbitrary part of a container.
- The result of the search is given as an iterator_range
- delimiting the selected part.
-
-
-
- Valid Expressions
-
-
-
- Expression
- Return Type
- Effects
-
-
-
-
- f(i,j)
- Convertible to iterator_range<Iter>
- Perform the search on the interval [i,j) and returns the result of the search
-
-
-
-
-
-
- Various algorithms need to perform a search in a container and a Finder is a generalization of such
- search operations that allows algorithms to abstract from searching. For instance, generic replace
- algorithms can replace any part of the input, and the Finder is used to select the desired one.
-
-
- Note, that it is only required that the finder works with a particular iterator type. However,
- a Finder operation can be defined as a template, allowing the Finder to work with any iterator.
-
-
- Examples
-
-
-
-
- Finder implemented as a class. This Finder always returns the whole input as a match. operator()
- is templated, so that the finder can be used on any iterator type.
-
-
-struct simple_finder
-{
- template<typename ForwardIteratorT>
- boost::iterator_range<ForwardIterator> operator()(
- ForwardIteratorT Begin,
- ForwardIteratorT End )
- {
- return boost::make_range( Begin, End );
- }
-};
-
-
-
- Function Finder. Finder can be any function object. That is, any ordinary function with the
- required signature can be used as well. However, such a function can be used only for
- a specific iterator type.
-
-
-boost::iterator_range<std::string> simple_finder(
- std::string::const_iterator Begin,
- std::string::const_iterator End )
-{
- return boost::make_range( Begin, End );
-}
-
-
-
-
-
-
- Formatter concept
-
-
- Formatters are used by replace algorithms.
- They are used in close combination with finders.
- A formatter is a functor, which takes a result from a Finder operation and transforms it in a specific way.
- The operation of the formatter can use additional information provided by a specific finder,
- for example regex_formatter() uses the match information from
- regex_finder() to format the result of formatter operation.
-
-
-
- Valid Expressions
-
-
-
- Expression
- Return Type
- Effects
-
-
-
-
- fmt(f(i,j))
- A container type, accessible using container traits
- Formats the result of the finder operation
-
-
-
-
-
-
- Similarly to finders, formatters generalize format operations. When a finder is used to
- select a part of the input, formatter takes this selection and performs some formating
- on it. Algorithms can abstract from formating using a formatter.
-
-
- Examples
-
-
-
-
- Formatter implemented as a class. This Formatter does not perform any formating and
- returns the match, repackaged. operator()
- is templated, so that the Formatter can be used on any Finder type.
-
-
-struct simple_formatter
-{
- template<typename FindResultT>
- std::string operator()( const FindResultT& Match )
- {
- std::string Temp( Match.begin(), Match.end() );
- return Temp;
- }
-};
-
-
-
- Function Formatter. Similarly to Finder, Formatter can be any function object.
- However, as a function, it can be used only with a specific Finder type.
-
-
-std::string simple_formatter( boost::iterator_range<std::string::const_iterator>& Match )
-{
- std::string Temp( Match.begin(), Match.end() );
- return Temp;
-}
-
-
-
-
-
-
diff --git a/string/doc/credits.xml b/string/doc/credits.xml
deleted file mode 100644
index ecc11e6..0000000
--- a/string/doc/credits.xml
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-
- Credits
-
- Acknowledgments
-
- The author would like to thank everybody who gave suggestions and comments. Especially valuable
- were the contributions of Thorsten Ottosen, Jeff Garland and the other boost members who participated
- in the review process, namely David Abrahams, Daniel Frey, Beman Dawes, John Maddock, David B.Held, Pavel Vozenilek
- and many other.
-
-
- Additional thanks go to Stefan Slapeta and Toon Knapen, who have been very resourceful in solving various
- portability issues.
-
-
-
diff --git a/string/doc/design.xml b/string/doc/design.xml
deleted file mode 100644
index 2affb7a..0000000
--- a/string/doc/design.xml
+++ /dev/null
@@ -1,216 +0,0 @@
-
-
-
- Design Topics
-
-
-
-
-
- String Representation
-
-
- 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 std::basic_string),
- rather it is a concept. This allows the algorithms in this library to be reused for any string type,
- that satisfies the given requirements.
-
-
- Definition: A string is a
- range of characters accessible in sequential
- ordered fashion. Character is any value type with "cheap" copying and assignment.
-
-
- First requirement of string-type is that it must accessible using
- Boost.Range. This facility allows to access
- the elements inside the string in a uniform iterator-based fashion.
- This is sufficient for our library
-
-
- 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.
-
-
- 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.
-
-
- In the reference and also in the code, requirement on the string type is designated by the name of
- template argument. RangeT means that the basic range requirements must hold.
- SequenceT designates extended sequence requirements.
-
-
-
-
- Sequence Traits
-
-
- The major difference between std::list and std::vector 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.
-
-
- 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
- boost/algorithm/string/sequence_traits.hpp.
-
-
-
- In the table C denotes a container and c is an object of C.
-
-
- Sequence Traits
-
-
-
- Trait
- Description
-
-
-
-
- has_native_replace<C>::value
- Specifies that the sequence has std::string like replace method
-
-
- has_stable_iterators<C>::value
-
- Specifies that the sequence has stable iterators. It means,
- that operations like insert/erase/replace
- do not invalidate iterators.
-
-
-
- has_const_time_insert<C>::value
-
- Specifies that the insert method of the sequence has
- constant time complexity.
-
-
-
- has_const_time_erase<C>::value
-
- Specifies that the erase method of the sequence has constant time complexity
-
-
-
-
-
-
-
- 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>.
-
-
-
- Find Algorithms
-
-
- Find algorithms have similar functionality to std::search() 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.
-
-
- Another difference is an addition of various searching methods besides find_first, including find_regex.
-
-
- It the library, find algorithms are implemented in terms of
- Finders. Finders are used also by other facilities
- (replace,split).
- For convenience, there are also function wrappers for these finders to simplify find operations.
-
-
- 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
-
-
-
- Replace Algorithms
-
-
- 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 Finder object and a
- Formatter 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.
-
-
- 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 Sequence traits)
-
-
-
- Find Iterators & Split Algorithms
-
-
- Find iterators are a logical extension of the find facility.
- 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 (find_iterator) of the parts in
- between (split_iterator).
-
-
- In addition the split algorithms like find_all() and split()
- 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.
-
-
-
- Exception Safety
-
-
- The library requires that all operations on types used as template
- or function arguments provide the basic exception-safety guarantee.
- In turn, all functions and algorithms in this library, except where stated
- otherwise, will provide the basic exception-safety guarantee.
- 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.
-
-
-
- Some functions can provide the strong exception-safety guarantee.
- That means that following statements are true:
-
-
- If an exception is thrown, there are no effects other than those
- of the function
-
-
- If an exception is thrown other than by the function, there are no effects
-
-
- 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 .
-
-
- In the reference, under the term strong exception-safety guarantee, we mean the
- guarantee as defined above.
-
-
- For more information about the exception safety topics, follow this
- link
-
-
-
diff --git a/string/doc/environment.xml b/string/doc/environment.xml
deleted file mode 100644
index aec08e4..0000000
--- a/string/doc/environment.xml
+++ /dev/null
@@ -1,59 +0,0 @@
-
-
-
- Environment
-
- Build
-
- The whole library is provided in headers. Regex variants of some algorithms,
- however, are dependent on the Boost.Regex library. All such algorithms are
- separated in boost/algorithm/string_regex.hpp.
- If this header is used, the application must be linked with the Boost.Regex
- library.
-
-
-
-
- Examples
-
- Examples showing the basic usage of the library can be found in the libs/algorithm/string/example
- directory. There is a separate file for the each part of the library. Please follow the boost
- build guidelines to build examples using the bjam. To successfully build regex examples
- the Boost.Regex library is required.
-
-
-
-
- Tests
-
- A full set of test cases for the library is located in the libs/algorithm/string/test directory.
- The test cases can be executed using the boost build system. For the tests of regular
- expression variants of algorithms, the Boost.Regex library is required.
-
-
-
-
- Portability
-
- The library has been successfully compiled and tested with the following compilers:
-
-
- Microsoft Visual C++ 7.0
- Microsoft Visual C++ 7.1
- GCC 3.2
- GCC 3.3.1
-
-
- See Boost regression tables
- for additional info for a particular compiler.
-
-
- There are known limitation on platforms not supporting partial template specialization.
- Library depends on correctly implemented std::iterator_traits class.
- If a standard library provided with compiler is broken, the String Algorithm Library
- cannot function properly. Usually it implies that primitive pointer iterators are not
- working with the library functions.
-
-
-
diff --git a/string/doc/external_concepts.html b/string/doc/external_concepts.html
deleted file mode 100644
index 7a4a502..0000000
--- a/string/doc/external_concepts.html
+++ /dev/null
@@ -1,38 +0,0 @@
- Concepts and External Concepts
Concepts and External Concepts
Generic programming in C++ is characterized by the use of function and class templates where
- the template parameter(s) must satisfy certain requirements.Often these
- requirements are so important that we give them a name: we call
- such a set of type requirements a concept. We say that a type
- conforms to a concept or that it is a model of a concept if it
- satisfies all of those requirements. The concept can be specified as a set
- of member functions with well-defined semantics
- and a set of nested typedefs with well-defined properties.
Often it much more flexible to provide free-standing functions and typedefs
- which provides the exact same semantics (but a different syntax) as
- specified
- by the concept. This allows generic code to treat different types as if
- they fulfilled the concept. In this case we say that the concept has
- been externalized or that the new requirements constitutes an external
- concept . We say that a type conforms to an external concept
- or that it is a model of an external concept . A concept may exist
- without a corresponding external concept and conversely.
Whenever a concept specifies a member function, the corresponding external
- concept
- must specify a free-standing function of the same name, same return type and
- the same argument list except there is an extra first argument which must
- be of the type (or a reference to that type) that is to fulfill the external
- concept. If the corresonding member function has any cv-qulifiers, the
- first argument must have the same cv-qualifiers. Whenever a concept
- specifies a nested typedef, the corresponding external concept
- specifies a type-generator, that is, a type with a nested typedef
- named type. The type-generator has the name as the nested typedef with
- _of appended.
- The converse relationship of an external concept and its corresponding concept
- also holds.
Example:
A type T fulfills the FooConcept if it
- has the follwing public members:
void T::foo( int ) const;
- int T::bar();
- typedef implementation defined foo_type;
The corresponding external concept is the ExternalFooConcept.
A type T fullfills the ExternalFooConcept if these
- free-standing functions and type-generators exists:
void foo( const T&, int );
- int bar( T& );
- foo_type_of< T >::type;
-
\ No newline at end of file
diff --git a/string/doc/intro.xml b/string/doc/intro.xml
deleted file mode 100644
index f59cd2f..0000000
--- a/string/doc/intro.xml
+++ /dev/null
@@ -1,47 +0,0 @@
-
-
-
- Introduction
-
-
- The String Algorithm Library provides a generic implementation of
- string-related algorithms which are missing in STL. It is an extension
- to the algorithms library of STL and it includes trimming, case conversion,
- predicates and find/replace functions. All of them come in different variants
- so it is easier to choose the best fit for a particular need.
-
-
- The implementation is not restricted to work with a particular container
- (like std::basic_string), rather it is as generic as
- possible. This generalization is not compromising the performance since
- algorithms are using container specific features when it means a performance
- gain.
-
-
-
- Important note: In this documentation we use term string to
- designate a sequence of characters stored in an arbitrary container.
- A string is not restricted to std::basic_string and
- character does not have to be char or wchar_t,
- although these are most common candidates.
-
- Consult the design chapter to see precise specification of
- supported string types.
-
-
- The library interface functions and classes are defined in namespace boost::algorithm, and
- they are lifted into namespace boost via using declaration.
-
-
- The documentation is divided into several sections. For a quick start read the
- Usage section followed by
- Quick Reference.
- The Design Topics,
- Concepts and Rationale
- provide some explanation about the library design and structure an explain how it should be used.
- See the Reference for the complete list of provided utilities
- and algorithms. Functions and classes in the reference are organized by the headers in which they are defined.
- The reference contains links to the detailed description for every entity in the library.
-
-
diff --git a/string/doc/quickref.xml b/string/doc/quickref.xml
deleted file mode 100644
index 51a0114..0000000
--- a/string/doc/quickref.xml
+++ /dev/null
@@ -1,686 +0,0 @@
-
-
-
- Quick Reference
-
-
-
-
-
- Algorithms
-
-
- Case Conversion
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- to_upper
- Convert a string to upper case
-
- to_upper_copy()
-
- to_upper()
-
-
-
- to_lower
- Convert a string to lower case
-
- to_lower_copy()
-
- to_lower()
-
-
-
-
-
-
- Trimming
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- trim_left
- Remove leading spaces from a string
-
- trim_left_copy_if()
-
- trim_left_if()
-
- trim_left_copy()
-
- trim_left()
-
-
-
- trim_right
- Remove trailing spaces from a string
-
- trim_right_copy_if()
-
- trim_right_if()
-
- trim_right_copy()
-
- trim_right()
-
-
-
- trim
- Remove leading and trailing spaces from a string
-
- trim_copy_if()
-
- trim_if()
-
- trim_copy()
-
- trim()
-
-
-
-
-
-
-
- Predicates
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- starts_with
- Check if a string is a prefix of the other one
-
- starts_with()
-
- istarts_with()
-
-
-
- ends_with
- Check if a string is a suffix of the other one
-
- ends_with()
-
- iends_with()
-
-
-
- contains
- Check if a string is contained of the other one
-
- contains()
-
- icontains()
-
-
-
- equals
- Check if two strings are equal
-
- equals()
-
- iequals()
-
-
-
- all
- Check if all elements of a string satisfy the given predicate
-
- all()
-
-
-
-
-
-
- Find algorithms
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- find_first
- Find the first occurrence of a string in the input
-
- find_first()
-
- ifind_first()
-
-
-
- find_last
- Find the last occurrence of a string in the input
-
- find_last()
-
- ifind_last()
-
-
-
- find_nth
- Find the nth (zero-indexed) occurrence of a string in the input
-
- find_nth()
-
- ifind_nth()
-
-
-
- find_head
- Retrieve the head of a string
-
- find_head()
-
-
-
- find_tail
- Retrieve the tail of a string
-
- find_tail()
-
-
-
- find_token
- Find first matching token in the string
-
- find_token()
-
-
-
- find_regex
- Use the regular expression to search the string
-
- find_regex()
-
-
-
- find
- Generic find algorithm
-
- find()
-
-
-
-
-
-
- Erase/Replace
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- replace/erase_first
- Replace/Erase the first occurrence of a string in the input
-
- replace_first()
-
- replace_first_copy()
-
- ireplace_first()
-
- ireplace_first_copy()
-
- erase_first()
-
- erase_first_copy()
-
- ierase_first()
-
- ierase_first_copy()
-
-
-
- replace/erase_last
- Replace/Erase the last occurrence of a string in the input
-
- replace_last()
-
- replace_last_copy()
-
- ireplace_last()
-
- ireplace_last_copy()
-
- erase_last()
-
- erase_last_copy()
-
- ierase_last()
-
- ierase_last_copy()
-
-
-
- replace/erase_nth
- Replace/Erase the nth (zero-indexed) occurrence of a string in the input
-
- replace_nth()
-
- replace_nth_copy()
-
- ireplace_nth()
-
- ireplace_nth_copy()
-
- erase_nth()
-
- erase_nth_copy()
-
- ierase_nth()
-
- ierase_nth_copy()
-
-
-
- replace/erase_all
- Replace/Erase the all occurrences of a string in the input
-
- replace_all()
-
- replace_all_copy()
-
- ireplace_all()
-
- ireplace_all_copy()
-
- erase_all()
-
- erase_all_copy()
-
- ierase_all()
-
- ierase_all_copy()
-
-
-
- replace/erase_head
- Replace/Erase the head of the input
-
- replace_head()
-
- replace_head_copy()
-
- erase_head()
-
- erase_head_copy()
-
-
-
-
- replace/erase_tail
- Replace/Erase the tail of the input
-
- replace_tail()
-
- replace_tail_copy()
-
- erase_tail()
-
- erase_tail_copy()
-
-
-
-
- replace/erase_regex
- Replace/Erase a substring matching the given regular expression
-
- replace_regex()
-
- replace_regex_copy()
-
- erase_regex()
-
- erase_regex_copy()
-
-
-
-
- replace/erase_regex_all
- Replace/Erase all substrings matching the given regular expression
-
- replace_all_regex()
-
- replace_all_regex_copy()
-
- erase_all_regex()
-
- erase_all_regex_copy()
-
-
-
-
- find_format
- Generic replace algorithm
-
- find_format()
-
- find_format_copy()
-
- find_format_all()
-
- find_format_all_copy()()
-
-
-
-
-
-
- Split
-
-
-
- Algorithm name
- Description
- Functions
-
-
-
-
- find_all
- Find/Extract all matching substrings in the input
-
- find_all()
-
- ifind_all()
-
- find_all_regex()
-
-
-
- split
- Split input into parts
-
- split()
-
- split_regex()
-
-
-
-
-
-
-
- Finders and Formatters
-
-
- Finders
-
-
-
- Finder
- Description
- Generators
-
-
-
-
- first_finder
- Search for the first match of the string in an input
-
- first_finder()
-
-
-
- last_finder
- Search for the last match of the string in an input
-
- last_finder()
-
-
-
- nth_finder
- Search for the nth (zero-indexed) match of the string in an input
-
- nth_finder()
-
-
-
- head_finder
- Retrieve the head of an input
-
- head_finder()
-
-
-
- tail_finder
- Retrieve the tail of an input
-
- tail_finder()
-
-
-
- token_finder
- Search for a matching token in an input
-
- token_finder()
-
-
-
- range_finder
- Do no search, always returns the given range
-
- range_finder()
-
-
-
- regex_finder
- Search for a substring matching the given regex
-
- regex_finder()
-
-
-
-
-
-
-
- Formatters
-
-
-
- Formatter
- Description
- Generators
-
-
-
-
- const_formatter
- Constant formatter. Always return the specified string
-
- const_formatter()
-
-
-
- identity_formatter
- Identity formatter. Return unmodified input input
-
- identity_formatter()
-
-
-
- empty_formatter
- Null formatter. Always return an empty string
-
- empty_formatter()
-
-
-
- regex_formatter
- Regex formatter. Format regex match using the specification in the format string
-
- regex_formatter()
-
-
-
-
-
-
-
- Iterators
-
-
- Find Iterators
-
-
-
- Iterator name
- Description
- Iterator class
-
-
-
-
- find_iterator
- Iterates through matching substrings in the input
-
- find_iterator
-
-
-
- split_iterator
- Iterates through gaps between matching substrings in the input
-
- split_iterator
-
-
-
-
-