[Boost-commit] svn:boost r83171 - branches/release/libs/algorithm/doc

Subject: [Boost-commit] svn:boost r83171 - branches/release/libs/algorithm/doc
From: marshall_at_[hidden]
Date: 2013-02-26 17:05:43

Author: marshall
Date: 2013-02-26 17:05:42 EST (Tue, 26 Feb 2013)
New Revision: 83171
URL: http://svn.boost.org/trac/boost/changeset/83171

Log:
more merge failures
Added:
   branches/release/libs/algorithm/doc/gather.qbk   (contents, props changed)

Added: branches/release/libs/algorithm/doc/gather.qbk
==============================================================================
--- (empty file)
+++ branches/release/libs/algorithm/doc/gather.qbk	2013-02-26 17:05:42 EST (Tue, 26 Feb 2013)
@@ -0,0 +1,79 @@
+[/ File gather.qbk]
+
+[section:gather gather]
+
+[/license
+Copyright (c) 2013 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/gather.hpp' contains two variants of a single algorithm, `gather`. 
+
+`gather()` takes a collection of elements defined by a pair of iterators and moves the ones satisfying a predicate to them to a position (called the pivot) within the sequence. The algorithm is stable. The result is a pair of iterators that contains the items that satisfy the predicate.
+
+[heading Interface]
+
+The function `gather` returns a `std::pair` of iterators that denote the elements that satisfy the predicate.  
+
+There are two versions; one takes two iterators, and the other takes a range.
+
+``
+namespace boost { namespace algorithm {
+
+template <typename ForwardIterator, typename Pred>
+std::pair<ForwardIterator,ForwardIterator> 
+gather ( ForwardIterator first, ForwardIterator last, ForwardIterator pivot, Pred pred );
+
+template <typename ForwardRange, typename Pred>
+std::pair<typename boost::range_iterator<ForwardRange>::type, typename boost::range_iterator<ForwardRange>::type>
+gather ( ForwardRange &range, typename boost::range_iterator<ForwardRange>::type pivot, Pred pred );
+
+}}
+``
+
+[heading Examples]
+
+Given an sequence containing:
+``
+0 1 2 3 4 5 6 7 8 9
+``
+
+a call to gather ( arr, arr + 10, arr + 4, IsEven ) will result in:
+
+``
[phone]
+    |---|-----|
+  first |  second
+      pivot
+``
+where `first` and `second` are the fields of the pair that is returned by the call.
+
+
+[heading Iterator Requirements]
+
+`gather` work on all iterators except input or output iterators.
+
+[heading Storage Requirements]
+
+`gather` uses stable_partition, which will attempt to allocate temporary memory, but will work in-situ if there is none available.
+
+[heading Complexity]
+
+If there is sufficient memory available, the run time is linear: `O(N)`
+
+If there is not any memory available, then the run time is `O(N log N)`.
+
+[heading Exception Safety]
+
+[heading Notes]
+
+[endsect]
+
+[/ File gather.qbk
+Copyright 2013 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).
+]
+