Commit 119dbb1f by Jerry Quinn Committed by Jerry Quinn

stl_algo.h (includes, [...]): Document.

2003-07-15  Jerry Quinn  <jlquinn@optonline.net>

	* include/bits/stl_algo.h (includes, set_union, set_intersection,
        set_difference, set_symmetric_difference, max_element, min_element,
        next_permutation, prev_permutation, find_first_of, find_end):
        Document.
	* include/bits/stl_algobase.h (copy,copy_backward):  Clarify overlap
        restrictions in docs.
	* include/bits/stl_heap.h (push_heap, pop_heap, make_heap, sort_heap):
        Document.
	* docs/doxygen/doxygroups.cc (setoperations):  New group.

From-SVN: r69387
parent 284f19bf
2003-07-15 Jerry Quinn <jlquinn@optonline.net> 2003-07-15 Jerry Quinn <jlquinn@optonline.net>
* include/bits/stl_algo.h (includes, set_union, set_intersection,
set_difference, set_symmetric_difference, max_element, min_element,
next_permutation, prev_permutation, find_first_of, find_end):
Document.
* include/bits/stl_algobase.h (copy,copy_backward): Clarify overlap
restrictions in docs.
* include/bits/stl_heap.h (push_heap, pop_heap, make_heap, sort_heap):
Document.
* docs/doxygen/doxygroups.cc (setoperations): New group.
2003-07-15 Jerry Quinn <jlquinn@optonline.net>
* include/bits/basic_string.h: Document public functions. * include/bits/basic_string.h: Document public functions.
* docs/doxygen/TODO: Update c21 todo. * docs/doxygen/TODO: Update c21 todo.
......
...@@ -202,6 +202,14 @@ relation. Rather, it partitions the range. ...@@ -202,6 +202,14 @@ relation. Rather, it partitions the range.
*/ */
// // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // //
/** @addtogroup setoperations Set operation algorithms
These algorithms are common set operations performed on sequences that are
already sorted.
The number of comparisons will be linear.
*/
// // // // // // // // // // // // // // // // // // // // // // // //
// // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // //
/* * @addtogroup groupname description of group /* * @addtogroup groupname description of group
......
...@@ -319,8 +319,11 @@ namespace std ...@@ -319,8 +319,11 @@ namespace std
* This inline function will boil down to a call to @c memmove whenever * This inline function will boil down to a call to @c memmove whenever
* possible. Failing that, if random access iterators are passed, then the * possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler * loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling). If the input range and the output * optimizations such as unrolling). Result may not be contained within
* range overlap, then the copy_backward function should be used instead. * [first,last); the copy_backward function should be used instead.
*
* Note that the end of the output range is permitted to be contained
* within [first,last).
*/ */
template<typename _InputIterator, typename _OutputIterator> template<typename _InputIterator, typename _OutputIterator>
inline _OutputIterator inline _OutputIterator
...@@ -443,9 +446,9 @@ namespace std ...@@ -443,9 +446,9 @@ namespace std
/** /**
* @brief Copies the range [first,last) into result. * @brief Copies the range [first,last) into result.
* @param first An input iterator. * @param first A bidirectional iterator.
* @param last An input iterator. * @param last A bidirectional iterator.
* @param result An output iterator. * @param result A bidirectional iterator.
* @return result - (first - last) * @return result - (first - last)
* *
* The function has the same effect as copy, but starts at the end of the * The function has the same effect as copy, but starts at the end of the
...@@ -454,6 +457,9 @@ namespace std ...@@ -454,6 +457,9 @@ namespace std
* possible. Failing that, if random access iterators are passed, then the * possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler * loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling). * optimizations such as unrolling).
*
* Result may not be in the range [first,last). Use copy instead. Note
* that the start of the output range may overlap [first,last).
*/ */
template <typename _BI1, typename _BI2> template <typename _BI1, typename _BI2>
inline _BI2 inline _BI2
......
...@@ -79,6 +79,15 @@ namespace std ...@@ -79,6 +79,15 @@ namespace std
*(__first + __holeIndex) = __value; *(__first + __holeIndex) = __value;
} }
/**
* @brief Push an element onto a heap.
* @param first Start of heap.
* @param last End of heap + element.
* @ingroup heap
*
* This operation pushes the element at last-1 onto the valid heap over the
* range [first,last-1). After completion, [first,last) is a valid heap.
*/
template<typename _RandomAccessIterator> template<typename _RandomAccessIterator>
inline void inline void
push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last) push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
...@@ -112,6 +121,17 @@ namespace std ...@@ -112,6 +121,17 @@ namespace std
*(__first + __holeIndex) = __value; *(__first + __holeIndex) = __value;
} }
/**
* @brief Push an element onto a heap using comparison functor.
* @param first Start of heap.
* @param last End of heap + element.
* @param comp Comparison functor.
* @ingroup heap
*
* This operation pushes the element at last-1 onto the valid heap over the
* range [first,last-1). After completion, [first,last) is a valid heap.
* Compare operations are performed using comp.
*/
template<typename _RandomAccessIterator, typename _Compare> template<typename _RandomAccessIterator, typename _Compare>
inline void inline void
push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last, push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,
...@@ -161,6 +181,15 @@ namespace std ...@@ -161,6 +181,15 @@ namespace std
std::__adjust_heap(__first, _Distance(0), _Distance(__last - __first), __value); std::__adjust_heap(__first, _Distance(0), _Distance(__last - __first), __value);
} }
/**
* @brief Pop an element off a heap.
* @param first Start of heap.
* @param last End of heap.
* @ingroup heap
*
* This operation pops the top of the heap. The elements first and last-1
* are swapped and [first,last-1) is made into a heap.
*/
template<typename _RandomAccessIterator> template<typename _RandomAccessIterator>
inline void inline void
pop_heap(_RandomAccessIterator __first, _RandomAccessIterator __last) pop_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
...@@ -208,6 +237,17 @@ namespace std ...@@ -208,6 +237,17 @@ namespace std
__value, __comp); __value, __comp);
} }
/**
* @brief Pop an element off a heap using comparison functor.
* @param first Start of heap.
* @param last End of heap.
* @param comp Comparison functor to use.
* @ingroup heap
*
* This operation pops the top of the heap. The elements first and last-1
* are swapped and [first,last-1) is made into a heap. Comparisons are
* made using comp.
*/
template<typename _RandomAccessIterator, typename _Compare> template<typename _RandomAccessIterator, typename _Compare>
inline void inline void
pop_heap(_RandomAccessIterator __first, pop_heap(_RandomAccessIterator __first,
...@@ -221,6 +261,14 @@ namespace std ...@@ -221,6 +261,14 @@ namespace std
std::__pop_heap(__first, __last - 1, __last - 1, _ValueType(*(__last - 1)), __comp); std::__pop_heap(__first, __last - 1, __last - 1, _ValueType(*(__last - 1)), __comp);
} }
/**
* @brief Construct a heap over a range.
* @param first Start of heap.
* @param last End of heap.
* @ingroup heap
*
* This operation makes the elements in [first,last) into a heap.
*/
template<typename _RandomAccessIterator> template<typename _RandomAccessIterator>
void void
make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last) make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
...@@ -246,6 +294,16 @@ namespace std ...@@ -246,6 +294,16 @@ namespace std
} }
} }
/**
* @brief Construct a heap over a range using comparison functor.
* @param first Start of heap.
* @param last End of heap.
* @param comp Comparison functor to use.
* @ingroup heap
*
* This operation makes the elements in [first,last) into a heap.
* Comparisons are made using comp.
*/
template<typename _RandomAccessIterator, typename _Compare> template<typename _RandomAccessIterator, typename _Compare>
inline void inline void
make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last, make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,
...@@ -272,6 +330,14 @@ namespace std ...@@ -272,6 +330,14 @@ namespace std
} }
} }
/**
* @brief Sort a heap.
* @param first Start of heap.
* @param last End of heap.
* @ingroup heap
*
* This operation sorts the valid heap in the range [first,last).
*/
template<typename _RandomAccessIterator> template<typename _RandomAccessIterator>
void void
sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last) sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
...@@ -286,6 +352,16 @@ namespace std ...@@ -286,6 +352,16 @@ namespace std
std::pop_heap(__first, __last--); std::pop_heap(__first, __last--);
} }
/**
* @brief Sort a heap using comparison functor.
* @param first Start of heap.
* @param last End of heap.
* @param comp Comparison functor to use.
* @ingroup heap
*
* This operation sorts the valid heap in the range [first,last).
* Comparisons are made using comp.
*/
template<typename _RandomAccessIterator, typename _Compare> template<typename _RandomAccessIterator, typename _Compare>
void void
sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last, sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment