doxygroups.cc: New group on binary searching.

2002-04-17  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/doxygroups.cc:  New group on binary searching.
	* include/bits/stl_algo.h:  Document binary searches and merges.
	* include/bits/stl_deque.h:  The 'map' member is not the 'map' class.

From-SVN: r52453

libstdc++-v3/ChangeLog

 2002-04-17  Phil Edwards  <pme@gcc.gnu.org>
 
+	* docs/doxygen/doxygroups.cc:  New group on binary searching.
+	* include/bits/stl_algo.h:  Document binary searches and merges.
+	* include/bits/stl_deque.h:  The 'map' member is not the 'map' class.
+
+2002-04-17  Phil Edwards  <pme@gcc.gnu.org>
+
 	* docs/doxygen/mainpage.html:  Doxygen logo is now a PNG file.
 	* docs/doxygen/run_doxygen:  Bump required version.
 	* docs/doxygen/user.cfg.in:  Revert accidental change.

libstdc++-v3/docs/doxygen/doxygroups.cc

@@ -179,6 +179,36 @@ char* __cxa_demangle (const char* mangled_name, char* output_buffer,
 } // namespace abi
 
 // // // // // // // // // // // // // // // // // // // // // // // //
+/** @addtogroup binarysearch Binary search algorithms
+These algorithms are variations of a classic binary search.  They all assume
+that the sequence being searched is already sorted.
+
+The number of comparisons will be logarithmic (and as few as possible).
+The number of steps through the sequence will be logarithmic for
+random-access iterators (e.g., pointers), and linear otherwise.
+
+The LWG has passed Defect Report 270, which notes:  <em>The proposed
+resolution reinterprets binary search. Instead of thinking about searching
+for a value in a sorted range, we view that as an important special
+case of a more general algorithm: searching for the partition point in a
+partitioned range.  We also add a guarantee that the old wording did not:
+we ensure that the upper bound is no earlier than the lower bound, that
+the pair returned by equal_range is a valid range, and that the first part
+of that pair is the lower bound.</em>
+
+The actual effect of the first sentence is that a comparison functor
+passed by the user doesn't necessarily need to induce a strict weak ordering
+relation.  Rather, it partitions the range.
+*/
+
+// // // // // // // // // // // // // // // // // // // // // // // //
+
+// // // // // // // // // // // // // // // // // // // // // // // //
+/* * @addtogroup groupname description of group
+placeholder text
+*/
+
+// // // // // // // // // // // // // // // // // // // // // // // //
 
 // vim:et:noai:
 

libstdc++-v3/include/bits/stl_deque.h

@@ -437,7 +437,8 @@ _Deque_base<_Tp,_Alloc>::_M_destroy_nodes(_Tp** __nstart, _Tp** __nfinish)
  *  - size_t      _M_map_size
  *  - iterator    _M_start, _M_finish
  *  
- *  map_size is at least 8.  map is an array of map_size pointers-to-"nodes".
+ *  map_size is at least 8.  %map is an array of map_size pointers-to-"nodes".
+ *  (The name has nothing to do with the std::map class.)
  *  
  *  A "node" has no specific type name as such, but it is referred to as
  *  "node" in this file.  It is a simple array-of-Tp.  If Tp is very large,
@@ -451,18 +452,18 @@ _Deque_base<_Tp,_Alloc>::_M_destroy_nodes(_Tp** __nstart, _Tp** __nfinish)
  *  memory pool.  There are 20 hours left in the year; perhaps I can fix
  *  this before 2002.
  *  
- *  Not every pointer in the map array will point to a node.  If the initial
- *  number of elements in the deque is small, the /middle/ map pointers will
+ *  Not every pointer in the %map array will point to a node.  If the initial
+ *  number of elements in the deque is small, the /middle/ %map pointers will
  *  be valid, and the ones at the edges will be unused.  This same situation
- *  will arise as the map grows:  available map pointers, if any, will be on
- *  the ends.  As new nodes are created, only a subset of the map's pointers
+ *  will arise as the %map grows:  available %map pointers, if any, will be on
+ *  the ends.  As new nodes are created, only a subset of the %map's pointers
  *  need to be copied "outward".
  *
  *  Class invariants:
  * - For any nonsingular iterator i:
- *    - i.node points to a member of the map array.  (Yes, you read that
+ *    - i.node points to a member of the %map array.  (Yes, you read that
  *      correctly:  i.node does not actually point to a node.)  The member of
- *      the map array is what actually points to the node.
+ *      the %map array is what actually points to the node.
  *    - i.first == *(i.node)    (This points to the node (first Tp element).)
  *    - i.last  == i.first + node_size
  *    - i.cur is a pointer in the range [i.first, i.last).  NOTE:
@@ -478,10 +479,10 @@ _Deque_base<_Tp,_Alloc>::_M_destroy_nodes(_Tp** __nstart, _Tp** __nfinish)
  *   that range are uninitialized storage.  Otherwise, [start.cur, start.last)
  *   and [finish.first, finish.cur) are initialized objects, and [start.first,
  *   start.cur) and [finish.cur, finish.last) are uninitialized storage.
- * - [map, map + map_size) is a valid, non-empty range.  
+ * - [%map, %map + map_size) is a valid, non-empty range.  
  * - [start.node, finish.node] is a valid range contained within 
- *   [map, map + map_size).  
- * - A pointer in the range [map, map + map_size) points to an allocated node
+ *   [%map, %map + map_size).  
+ * - A pointer in the range [%map, %map + map_size) points to an allocated node
  *   if and only if the pointer is in the range [start.node, finish.node].
  *
  *  Here's the magic:  nothing in deque is "aware" of the discontiguous storage!