First draft of Boost.Algorithm documentation; more to come

[SVN r77326]

Author: mclow

doc/Jamfile.v2

@@ -0,0 +1,46 @@
+# Boost.Algorithm
+#
+# Copyright (c) 2010-2012 Marshall Clow
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+
+# Quickbook
+# -----------------------------------------------------------------------------
+
+import os ;
+
+using quickbook ;
+using doxygen ;
+using boostbook ;
+
+local BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
+
+doxygen autodoc 
+    : 
+        [ glob ../../../boost/algorithm/*.hpp ../../../boost/algorithm/searching/*.hpp ]
+    : 
+       <doxygen:param>"PREDEFINED=\"BOOST_ALGORITHM_DOXYGEN=1\""
+       <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
+    ; 
+
+
+xml algorithm : algorithm.qbk ;
+
+# path-constant boost-images : $(BOOST_ROOT)/doc/src/images ;
+
+boostbook standalone
+  :
+    algorithm
+  :
+    <dependency>autodoc 
+    <xsl:param>boost.root=$(BOOST_ROOT)
+    <xsl:param>"boost.doxygen.reftitle=Boost.Algorithms C++ Reference"
+    <xsl:param>chapter.autolabel=0
+    <xsl:param>chunk.section.depth=8
+    <xsl:param>toc.section.depth=2
+    <xsl:param>toc.max.depth=2
+    <xsl:param>generate.section.toc.level=1
+  ;

doc/algorithm.qbk

@@ -0,0 +1,68 @@
+[library The Boost Algorithm Library
+    [quickbook 1.5]
+    [id algorithm]
+    [dirname algorithm]
+    [purpose Library of useful algorithms]
+    [category algorithms]
+    [authors [Clow, Marshall]]
+    [copyright 2010-2012 Marshall Clow]
+    [source-mode c++]
+    [license
+		Distributed under the Boost Software License, Version 1.0.
+		(See accompanying file LICENSE_1_0.txt or copy at
+		[@http://www.boost.org/LICENSE_1_0.txt])
+    ]
+]
+
+[section Description and Rationale]
+
+Boost.Algorithm is a collection of general purpose algorithms. While Boost contains many libraries of data structures, there is no single library for general purpose algorithms. Even though the algorithms are generally useful, many tend to be thought of as "too small" for Boost.
+
+An implementation of Boyer-Moore searching, for example, might take a developer a week or so to implement, including test cases and documentation. However, scheduling a review to include that code into Boost might take several months, and run into resistance because "it is too small". Nevertheless, a library of tested, reviewed, documented algorithms can make the developer's life much easier, and that is the purpose of this library.
+
+[heading Future plans]
+
+I will be soliciting submissions from other developers, as well as looking through the literature for existing algorithms to include. The Adobe Source Library, for example, contains many useful algorithms that already have documentation and test cases. Knuth's _The Art of Computer Programming_ is chock-full of algorithm descriptions, too. 
+
+My goal is to run regular algorithm reviews, similar to the Boost library review process, but with smaller chunks of code. 
+
+[heading Dependencies]
+
+Boost.Algorithm uses Boost.Range, Boost.Assert, Boost.Array, Boost.TypeTraits, and Boost.StaticAssert.
+
+
+[heading Acknowledgements]
+
+Thanks to all the people who have reviewed this library and made suggestions for improvements. Steven Watanabe and Sean Parent, in particular, have provided a great deal of help.
+
+[endsect]
+
+[/ include toc.qbk]
+
+
+[section:Searching Searching Algorithms]
+[include boyer_moore.qbk]
+[include boyer_moore_horspool.qbk]
+[include knuth_morris_pratt.qbk]
+[endsect]
+
+[section:CXX11 C++11 Algorithms]
+[include all_of.qbk]
+[include any_of.qbk]
+[include none_of.qbk]
+[include one_of.qbk]
+[include ordered-hpp.qbk]
+[include is_partitioned.qbk]
+[include partition_point.qbk]
+[endsect]
+
+[section:Misc Other Algorithms]
+[include clamp-hpp.qbk]
+[include hex.qbk]
+[endsect]
+
+
+
+[xinclude autodoc.xml]
+
+

doc/all_of.qbk

@@ -0,0 +1,89 @@
+[/ File all_of.qbk]
+
+[section:all_of all_of]
+
+[/license
+Copyright (c) 2010-2012 Marshall Clow
+
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+The header file 'boost/algorithm/cxx11/all_of.hpp' contains four variants of a single algorithm, `all_of`. The algorithm tests all the elements of a sequence and returns true if they all share a  property.
+
+The routine `all_of` takes a sequence and a predicate. It will return true if the predicate returns true when applied to every element in the sequence. 
+
+The routine `all_of_equal` takes a sequence and a value. It will return true if every element in the sequence compares equal to the passed in value.
+
+Both routines come in two forms; the first one takes two iterators to define the range. The second form takes a single range parameter, and uses Boost.Range to traverse it.
+
+
+[heading interface]
+
+The function `all_of` returns true if the predicate returns true for every item in the sequence.  There are two versions; one takes two iterators, and the other takes a range.
+
+``
+namespace boost { namespace algorithm {
+template<typename InputIterator, typename Predicate>
+	bool all_of ( InputIterator first, InputIterator last, Predicate p );
+template<typename Range, typename Predicate> 
+	bool all_of ( const Range &r, Predicate p );
+}}
+``
+
+The function `all_of_equal` is similar to `all_of`, but instead of taking a predicate to test the elements of the sequence, it takes a value to compare against.
+
+``
+namespace boost { namespace algorithm {
+template<typename InputIterator, typename V>
+	bool all_of_equal ( InputIterator first, InputIterator last, V const &val );
+template<typename Range, typename V> 
+	bool all_of_equal ( const Range &r, V const &val );
+}}
+``
+
+[heading Examples]
+
+Given the container `c` containing `{ 0, 1, 2, 3, 14, 15 }`, then
+``
+bool isOdd ( int i ) { return i % 2 == 1; }
+bool lessThan10 ( int i ) { return i < 10; }
+
+using boost::algorithm;
+all_of ( c, isOdd ) --> false
+all_of ( c.begin (), c.end (), lessThan10 ) --> false
+all_of ( c.begin (), c.begin () + 3, lessThan10 ) --> true
+all_of ( c.end (), c.end (), isOdd ) --> true  // empty range
+all_of_equal ( c, 3 ) --> false
+all_of_equal ( c.begin () + 3, c.begin () + 4, 3 ) --> true
+all_of_equal ( c.begin (), c.begin (), 99 ) --> true  // empty range
+``
+
+[heading Iterator Requirements]
+
+`all_of` and `all_of_equal` work on all iterators except output iterators.
+
+[heading Complexity]
+
+All of the variants of `all_of` and `all_of_equal` run in ['O(N)] (linear) time; that is, they compare against each element in the list once. If any of the comparisons fail, the algorithm will terminate immediately, without examining the remaining members of the sequence.
+
+[heading Exception Safety]
+
+All of the variants of `all_of` and `all_of_equal` take their parameters by value or const reference, and do not depend upon any global state. Therefore, all the routines in this file provide the strong exception guarantee.
+
+[heading Notes]
+
+* The routine `all_of` is part of the C++11 standard. When compiled using a C++11 implementation, the implementation from the standard library will be used.
+
+* `all_of` and `all_of_equal` both return true for empty ranges, no matter what is passed to test against. When there are no items in the sequence to test, they all satisfy the condition to be tested against.
+
+* The second parameter to `all_of_value` is a template parameter, rather than deduced from the first parameter (`std::iterator_traits<InputIterator>::value_type`) because that allows more flexibility for callers, and takes advantage of built-in comparisons for the type that is pointed to by the iterator.  The function is defined to return true if, for all elements in the sequence, the expression `*iter == val` evaluates to true (where `iter` is an iterator to each element in the sequence)
+
+[endsect]
+
+[/ File all_of.qbk
+Copyright 2011 Marshall Clow
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).
+]
+

doc/any_of.qbk

@@ -0,0 +1,89 @@
+[/ File any_of.qbk]
+
+[section:any_of any_of]
+
+[/license
+Copyright (c) 2010-2012 Marshall Clow
+
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+The header file 'boost/algorithm/cxx11/any_of.hpp' contains four variants of a single algorithm, `any_of`. The algorithm tests the elements of a sequence and returns true if any of the elements has a  particular property.
+
+The routine `any_of` takes a sequence and a predicate. It will return true if the predicate returns true for any element in the sequence. 
+
+The routine `any_of_equal` takes a sequence and a value. It will return true if any element in the sequence compares equal to the passed in value.
+
+Both routines come in two forms; the first one takes two iterators to define the range. The second form takes a single range parameter, and uses Boost.Range to traverse it.
+
+
+[heading interface]
+
+The function `any_of` returns true if the predicate returns true any item in the sequence.  There are two versions; one takes two iterators, and the other takes a range.
+
+``
+namespace boost { namespace algorithm {
+template<typename InputIterator, typename Predicate>
+	bool any_of ( InputIterator first, InputIterator last, Predicate p );
+template<typename Range, typename Predicate> 
+	bool any_of ( const Range &r, Predicate p );
+}}
+``
+
+The function `any_of_equal` is similar to `any_of`, but instead of taking a predicate to test the elements of the sequence, it takes a value to compare against.
+
+``
+namespace boost { namespace algorithm {
+template<typename InputIterator, typename V>
+	bool any_of_equal ( InputIterator first, InputIterator last, V const &val );
+template<typename Range, typename V> 
+	bool any_of_equal ( const Range &r, V const &val );
+}}
+``
+
+[heading Examples]
+
+Given the container `c` containing `{ 0, 1, 2, 3, 14, 15 }`, then
+``
+bool isOdd ( int i ) { return i % 2 == 1; }
+bool lessThan10 ( int i ) { return i < 10; }
+
+using boost::algorithm;
+any_of ( c, isOdd ) --> true
+any_of ( c.begin (), c.end (), lessThan10 ) --> true
+any_of ( c.begin () + 4, c.end (), lessThan10 ) --> false
+any_of ( c.end (), c.end (), isOdd ) --> false  // empty range
+any_of_equal ( c, 3 ) --> true
+any_of_equal ( c.begin (), c.begin () + 3, 3 ) --> false
+any_of_equal ( c.begin (), c.begin (), 99 ) --> false  // empty range
+``
+
+[heading Iterator Requirements]
+
+`any_of` and `any_of_equal` work on all iterators except output iterators.
+
+[heading Complexity]
+
+All of the variants of `any_of` and `any_of_equal` run in ['O(N)] (linear) time; that is, they compare against each element in the list once. If any of the comparisons succeed, the algorithm will terminate immediately, without examining the remaining members of the sequence.
+
+[heading Exception Safety]
+
+All of the variants of `any_of` and `any_of_equal` take their parameters by value or const reference, and do not depend upon any global state. Therefore, all the routines in this file provide the strong exception guarantee.
+
+[heading Notes]
+
+* The routine `any_of` is part of the C++11 standard. When compiled using a C++11 implementation, the implementation from the standard library will be used.
+
+* `any_of` and `any_of_equal` both return false for empty ranges, no matter what is passed to test against. 
+
+* The second parameter to `any_of_value` is a template parameter, rather than deduced from the first parameter (`std::iterator_traits<InputIterator>::value_type`) because that allows more flexibility for callers, and takes advantage of built-in comparisons for the type that is pointed to by the iterator.  The function is defined to return true if, for any element in the sequence, the expression `*iter == val` evaluates to true (where `iter` is an iterator to each element in the sequence)
+
+[endsect]
+
+[/ File any_of.qbk
+Copyright 2011 Marshall Clow
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).
+]
+

doc/boyer_moore.qbk

@@ -0,0 +1,93 @@
+[/ QuickBook Document version 1.5 ]
+
+[section:BoyerMoore Boyer-Moore Search]
+
+[/license
+
+Copyright (c) 2010-2012 Marshall Clow
+
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+[heading Overview]
+
+The header file 'boyer_moore.hpp' contains an an implementation of the Boyer-Moore algorithm for searching sequences of values. 
+
+The Boyer–Moore string search algorithm is a particularly efficient string searching algorithm, and it has been the standard benchmark for the practical string search literature. The Boyer-Moore algorithm was invented by Bob Boyer and J. Strother Moore, and published in the October 1977 issue of the Communications of the ACM , and a copy of that article is available at [@http://www.cs.utexas.edu/~moore/publications/fstrpos.pdf].
+
+The Boyer-Moore algorithm uses two precomputed tables to give better performance than a naive search. These tables depend on the pattern being searched for, and give the Boyer-Moore algorithm larger a memory footprint and startup costs than a simpler algorithm, but these costs are recovered quickly during the searching process, especially if the pattern is longer than a few elements.
+
+However, the Boyer-Moore algorithm cannot be used with comparison predicates like `std::search`.
+
+Nomenclature: I refer to the sequence being searched for as the "pattern", and the sequence being searched in as the "corpus".
+
+For flexibility, the Boyer-Moore algorithm has has two interfaces; an object-based interface and a procedural one. The object-based interface builds the tables in the constructor, and uses operator () to perform the search. The procedural interface builds the table and does the search all in one step. If you are going to be searching for the same pattern in multiple corpora, then you should use the object interface, and only build the tables once.
+
+Here is the object interface:
+``
+template <typename patIter>
+class boyer_moore {
+public:
+    boyer_moore ( patIter first, patIter last );
+    ~boyer_moore ();
+    
+    template <typename corpusIter>
+    corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last );
+    };
+``
+
+and here is the corresponding procedural interface:
+
+``
+template <typename patIter, typename corpusIter>
+corpusIter boyer_moore_search ( 
+        corpusIter corpus_first, corpusIter corpus_last, 
+        patIter pat_first, patIter pat_last );
+``
+
+Each of the functions is passed two pairs of iterators. The first two define the corpus and the second two define the pattern. Note that the two pairs need not be of the same type, but they do need to "point" at the same type. In other words, `patIter::value_type` and `curpusIter::value_type` need to be the same type.
+
+The return value of the function is an iterator pointing to the start of the pattern in the corpus. If the pattern is not found, it returns the end of the corpus (`corpus_last`).
+
+[heading Performance]
+
+The execution time of the Boyer-Moore algorithm, while still linear in the size of the string being searched, can have a significantly lower constant factor than many other search algorithms: it doesn't need to check every character of the string to be searched, but rather skips over some of them. Generally the algorithm gets faster as the pattern being searched for becomes longer. Its efficiency derives from the fact that with each unsuccessful attempt to find a match between the search string and the text it is searching, it uses the information gained from that attempt to rule out as many positions of the text as possible where the string cannot match.
+
+[heading Memory Use]
+
+The algorithm allocates two internal tables. The first one is proportional to the length of the pattern; the second one has one entry for each member of the "alphabet" in the pattern. For (8-bit) character types, this table contains 256 entries.
+
+[heading Complexity]
+
+The worst-case performance to find a pattern in the corpus is ['O(N)] (linear) time; that is, proportional to the length of the corpus being searched. In general, the search is sub-linear; not every entry in the corpus need be checked.
+
+[heading Exception Safety]
+
+Both the object-oriented and procedural versions of the Boyer-Moore algorithm take their parameters by value and do not use any information other than what is passed in. Therefore, both interfaces provide the strong exception guarantee.
+
+[heading Notes]
+
+* When using the object-based interface, the pattern must remain unchanged for during the searches; i.e, from the time the object is constructed until the final call to operator () returns.
+
+* The Boyer-Moore algorithm requires random-access iterators for both the pattern and the corpus.
+
+[heading Customization points] 
+
+The Boyer-Moore object takes a traits template parameter which enables the caller to customize how one of the precomputed tables is stored. This table, called the skip table, contains (logically) one entry for every possible value that the pattern can contain. When searching 8-bit character data, this table contains 256 elements. The traits class defines the table to be used. 
+
+The default traits class uses a `boost::array` for small 'alphabets' and a `tr1::unordered_map` for larger ones.  The array-based skip table gives excellent performance, but could be prohibitively large when the "alphabet" of elements to be searched grows. The unordered_map based version only grows as the number of unique elements in the pattern, but makes many more heap allocations, and gives slower lookup performance. 
+
+To use a different skip table, you should define your own skip table object and your own traits class, and use them to instantiate the Boyer-Moore object. The interface to these objects is described TBD.
+
+
+[endsect]
+
+[/ File boyer_moore.qbk
+Copyright 2011 Marshall Clow
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).
+]
+