[Boost-commit] svn:boost r84538 - trunk/libs/algorithm/doc

Subject: [Boost-commit] svn:boost r84538 - trunk/libs/algorithm/doc
From: marshall_at_[hidden]
Date: 2013-05-28 15:36:05

Author: marshall
Date: 2013-05-28 15:36:04 EDT (Tue, 28 May 2013)
New Revision: 84538
URL: http://svn.boost.org/trac/boost/changeset/84538

Log:
Added documentation for 'is_permutation'
Added:
   trunk/libs/algorithm/doc/is_permutation.qbk   (contents, props changed)
Text files modified: 
   trunk/libs/algorithm/doc/algorithm.qbk      |     1 +                                       
   trunk/libs/algorithm/doc/is_partitioned.qbk |     2 +-                                      
   2 files changed, 2 insertions(+), 1 deletions(-)

Modified: trunk/libs/algorithm/doc/algorithm.qbk
==============================================================================
--- trunk/libs/algorithm/doc/algorithm.qbk	(original)
+++ trunk/libs/algorithm/doc/algorithm.qbk	2013-05-28 15:36:04 EDT (Tue, 28 May 2013)
@@ -53,6 +53,7 @@
 [include one_of.qbk]
 [include ordered-hpp.qbk]
 [include is_partitioned.qbk]
+[include is_permutation.qbk]
 [include partition_point.qbk]
 [endsect]
 

Modified: trunk/libs/algorithm/doc/is_partitioned.qbk
==============================================================================
--- trunk/libs/algorithm/doc/is_partitioned.qbk	(original)
+++ trunk/libs/algorithm/doc/is_partitioned.qbk	2013-05-28 15:36:04 EDT (Tue, 28 May 2013)
@@ -18,7 +18,7 @@
 
 [heading interface]
 
-The function `is_partitioned` returns true the items in the sequence are separated according to their ability to satisfy the predicate.  There are two versions; one takes two iterators, and the other takes a range.
+The function `is_partitioned` returns true if the items in the sequence are separated according to their ability to satisfy the predicate.  There are two versions; one takes two iterators, and the other takes a range.
 
 ``
 template<typename InputIterator, typename Predicate>

Added: trunk/libs/algorithm/doc/is_permutation.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/algorithm/doc/is_permutation.qbk	2013-05-28 15:36:04 EDT (Tue, 28 May 2013)
@@ -0,0 +1,87 @@
+[/ File is_permutation.qbk]
+
+[section:is_permutation is_permutation ]
+
+[/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 'is_permutation.hpp' contains six variants of a single algorithm, `is_permutation`. The algorithm tests to see if one sequence is a permutation of a second one; in other words, it contains all the same members, possibly in a different order.
+
+The routine `is_permutation` takes two sequences and an (optional) predicate. It returns true if the two sequences contain the same members. If it is passed a predicate, it uses the predicate to compare the elements of the sequence to see if they are the same.
+
+`is_permutation` come in three forms. The first one takes two iterators to define the first range, and the starting iterator of the second range. The second form takes a two iterators to define the first range and two more to define the second range. The third form takes a single range parameter, and uses Boost.Range to traverse it.
+
+
+[heading Interface]
+
+The function `is_permutation` returns true if the two input sequences contain the same elements.  There are six versions; two take three iterators, two take four iterators, and the other two take two ranges.
+
+In general, you should prefer the four iterator versions over the three iterator ones. The three iterator version has to "create" the fourth iterator internally by calling `std::advance(first2, std::distance(first1,last1))`, and if the second sequence is shorter than the first, that's undefined behavior.
+
+``
+template< class ForwardIterator1, class ForwardIterator2 >
+bool is_permutation ( ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2 );
+
+template< class ForwardIterator1, class ForwardIterator2, class BinaryPredicate >
+bool is_permutation ( ForwardIterator1 first1, ForwardIterator1 last1,
+                      ForwardIterator2 first2, BinaryPredicate p );
+
+
+template< class ForwardIterator1, class ForwardIterator2 >
+bool is_permutation ( ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2 );
+
+template< class ForwardIterator1, class ForwardIterator2, class BinaryPredicate >
+bool is_permutation ( ForwardIterator1 first1, ForwardIterator1 last1,
+                      ForwardIterator2 first2, ForwardIterator2 last2,
+                      BinaryPredicate p );
+
+template <typename Range, typename ForwardIterator>
+bool is_permutation ( const Range &r, ForwardIterator first2 );
+
+template <typename Range, typename ForwardIterator, typename BinaryPredicate>
+bool is_permutation ( const Range &r, ForwardIterator first2, BinaryPredicate pred );
+
+``
+
+[heading Examples]
+
+Given the container `c1` containing `{ 0, 1, 2, 3, 14, 15 }`, and `c2` containing `{ 15, 14, 3, 1, 2 }`, then
+``
+is_permutation ( c1.begin(),     c1.end (), c2.begin(), c2.end ()) --> false
+is_permutation ( c1.begin() + 1, c1.end (), c2.begin(), c2.end ()) --> true
+
+is_permutation ( c1.end (), c1.end (), c2.end(), c2.end ()) --> true  // all empty ranges are permutations of each other
+``
+
+[heading Iterator Requirements]
+
+`is_permutation` works on forward iterators or better. 
+
+[heading Complexity]
+
+All of the variants of `is_permutation` run in ['O(N^2)] (quadratic) time; that is, they compare against each element in the list (potentially) N times.  If passed random-access iterators, `is_permutation` can return quickly if the sequences are different sizes.
+
+[heading Exception Safety]
+
+All of the variants of `is_permutation` take their parameters by value, and do not depend upon any global state. Therefore, all the routines in this file provide the strong exception guarantee.
+
+[heading Notes]
+
+* The three iterator versions of the routine `is_permutation` is part of the C++11 standard. When compiled using a C++11 implementation, the implementation from the standard library will be used.
+
+* The four iterator versions of the routine `is_permutation` is part of the proposed C++14 standard. When C++14 standard libraries become available, the implementation should be changed to use the implementation from the standard library (if available).
+
+* `is_permutation` returns true when passed a pair empty ranges, no matter what predicate is passed to test with. 
+
+[endsect]
+
+[/ File is_permutation.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).
+]
+