re PR libstdc++/9811 (incorrect documentation for std::map::lower_bound, etc.)

2003-02-25  Scott Snyder  <snyder@fnal.gov>

	PR libstdc++/9811
	* include/bits/stl_map.h (lower_bound, upper_bound, equal_range):
	Correct documentation.
	* include/bits/stl_multimap.h (lower_bound, upper_bound,
	equal_range): Likewise.

From-SVN: r63396

3 files changed, 56 insertions, 50 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 158f4b2..acab22f 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,11 @@
+2003-02-25  Scott Snyder  <snyder@fnal.gov>
+
+	PR libstdc++/9811
+	* include/bits/stl_map.h (lower_bound, upper_bound, equal_range):
+	Correct documentation.
+	* include/bits/stl_multimap.h (lower_bound, upper_bound,
+	equal_range): Likewise.
+
 2003-02-24  Paolo Carlini  <pcarlini@unitus.it>
 
 	PR libstdc++/9825
diff --git a/libstdc++-v3/include/bits/stl_map.h b/libstdc++-v3/include/bits/stl_map.h
index adb2e9a..853ef3e 100644
--- a/libstdc++-v3/include/bits/stl_map.h
+++ b/libstdc++-v3/include/bits/stl_map.h
@@ -496,13 +496,13 @@ namespace std
     /**
      *  @brief Finds the beginning of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return  Iterator pointing to first element matching given key, or
-     *           end() if not found.
+     *  @return  Iterator pointing to first element equal to or greater
+     *           than key, or end().
      *
-     *  This function is useful only with multimaps.  It returns the first
-     *  element of a subsequence of elements that matches the given key.  If
-     *  unsuccessful it returns an iterator pointing to the first element that
-     *  has a greater value than given key or end() if no such element exists.
+     *  This function returns the first element of a subsequence of elements
+     *  that matches the given key.  If unsuccessful it returns an iterator
+     *  pointing to the first element that has a greater value than given key
+     *  or end() if no such element exists.
     */
     iterator
     lower_bound(const key_type& __x) { return _M_t.lower_bound(__x); }
@@ -511,12 +511,12 @@ namespace std
      *  @brief Finds the beginning of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
      *  @return  Read-only (constant) iterator pointing to first element
-     *           matching given key, or end() if not found.
+     *           equal to or greater than key, or end().
      *
-     *  This function is useful only with multimaps.  It returns the first
-     *  element of a subsequence of elements that matches the given key.  If
-     *  unsuccessful the iterator will point to the next greatest element or,
-     *  if no such greater element exists, to end().
+     *  This function returns the first element of a subsequence of elements
+     *  that matches the given key.  If unsuccessful it returns an iterator
+     *  pointing to the first element that has a greater value than given key
+     *  or end() if no such element exists.
     */
     const_iterator
     lower_bound(const key_type& __x) const { return _M_t.lower_bound(__x); }
@@ -524,9 +524,8 @@ namespace std
     /**
      *  @brief Finds the end of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return Iterator pointing to last element matching given key.
-     *
-     *  This function only makes sense with multimaps.
+     *  @return Iterator pointing to the first element
+     *          greater than key, or end().
     */
     iterator
     upper_bound(const key_type& __x) { return _M_t.upper_bound(__x); }
@@ -534,10 +533,8 @@ namespace std
     /**
      *  @brief Finds the end of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return  Read-only (constant) iterator pointing to last element matching
-     *           given key.
-     *
-     *  This function only makes sense with multimaps.
+     *  @return  Read-only (constant) iterator pointing to first iterator
+     *           greater than key, or end().
     */
     const_iterator
     upper_bound(const key_type& __x) const
@@ -549,14 +546,14 @@ namespace std
      *  @return  Pair of iterators that possibly points to the subsequence
      *           matching given key.
      *
-     *  This function returns a pair of which the first
-     *  element possibly points to the first element matching the given key
-     *  and the second element possibly points to the last element matching the
-     *  given key.  If unsuccessful the first element of the returned pair will
-     *  contain an iterator pointing to the next greatest element or, if no such
-     *  greater element exists, to end().
+     *  This function is equivalent to
+     *  @code
+     *    std::make_pair(c.lower_bound(val),
+     *                   c.upper_bound(val))
+     *  @endcode
+     *  (but is faster than making the calls separately).
      *
-     *  This function only makes sense for multimaps.
+     *  This function probably only makes sense for multimaps.
     */
     pair<iterator,iterator>
     equal_range(const key_type& __x)
@@ -568,14 +565,14 @@ namespace std
      *  @return  Pair of read-only (constant) iterators that possibly points to
      *           the subsequence matching given key.
      *
-     *  This function returns a pair of which the first
-     *  element possibly points to the first element matching the given key
-     *  and the second element possibly points to the last element matching the
-     *  given key.  If unsuccessful the first element of the returned pair will
-     *  contain an iterator pointing to the next greatest element or, if no such
-     *  a greater element exists, to end().
+     *  This function is equivalent to
+     *  @code
+     *    std::make_pair(c.lower_bound(val),
+     *                   c.upper_bound(val))
+     *  @endcode
+     *  (but is faster than making the calls separately).
      *
-     *  This function only makes sense for multimaps.
+     *  This function probably only makes sense for multimaps.
     */
     pair<const_iterator,const_iterator>
     equal_range(const key_type& __x) const
diff --git a/libstdc++-v3/include/bits/stl_multimap.h b/libstdc++-v3/include/bits/stl_multimap.h
index 7b18d46..f35e3a2 100644
--- a/libstdc++-v3/include/bits/stl_multimap.h
+++ b/libstdc++-v3/include/bits/stl_multimap.h
@@ -479,8 +479,8 @@ namespace std
     /**
      *  @brief Finds the beginning of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return  Iterator pointing to first element matching given key, or
-     *           end() if not found.
+     *  @return  Iterator pointing to first element equal to or greater
+     *           than key, or end().
      *
      *  This function returns the first element of a subsequence of elements
      *  that matches the given key.  If unsuccessful it returns an iterator
@@ -494,7 +494,7 @@ namespace std
      *  @brief Finds the beginning of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
      *  @return  Read-only (constant) iterator pointing to first element
-     *           matching given key, or end() if not found.
+     *           equal to or greater than key, or end().
      *
      *  This function returns the first element of a subsequence of elements
      *  that matches the given key.  If unsuccessful the iterator will point
@@ -507,7 +507,8 @@ namespace std
     /**
      *  @brief Finds the end of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return Iterator pointing to last element matching given key.
+     *  @return Iterator pointing to the first element
+     *          greater than key, or end().
     */
     iterator
     upper_bound(const key_type& __x) { return _M_t.upper_bound(__x); }
@@ -515,8 +516,8 @@ namespace std
     /**
      *  @brief Finds the end of a subsequence matching given key.
      *  @param  x  Key of (key, value) pair to be located.
-     *  @return  Read-only (constant) iterator pointing to last element matching
-     *           given key.
+     *  @return  Read-only (constant) iterator pointing to first iterator
+     *           greater than key, or end().
     */
     const_iterator
     upper_bound(const key_type& __x) const { return _M_t.upper_bound(__x); }
@@ -527,12 +528,12 @@ namespace std
      *  @return  Pair of iterators that possibly points to the subsequence
      *           matching given key.
      *
-     *  This function returns a pair of which the first
-     *  element possibly points to the first element matching the given key
-     *  and the second element possibly points to the last element matching the
-     *  given key.  If unsuccessful the first element of the returned pair will
-     *  contain an iterator pointing to the next greatest element or, if no such
-     *  greater element exists, to end().
+     *  This function is equivalent to
+     *  @code
+     *    std::make_pair(c.lower_bound(val),
+     *                   c.upper_bound(val))
+     *  @endcode
+     *  (but is faster than making the calls separately).
     */
     pair<iterator,iterator>
     equal_range(const key_type& __x) { return _M_t.equal_range(__x); }
@@ -543,12 +544,12 @@ namespace std
      *  @return  Pair of read-only (constant) iterators that possibly points to
      *           the subsequence matching given key.
      *
-     *  This function returns a pair of which the first
-     *  element possibly points to the first element matching the given key
-     *  and the second element possibly points to the last element matching the
-     *  given key.  If unsuccessful the first element of the returned pair will
-     *  contain an iterator pointing to the next greatest element or, if no such
-     *  a greater element exists, to end().
+     *  This function is equivalent to
+     *  @code
+     *    std::make_pair(c.lower_bound(val),
+     *                   c.upper_bound(val))
+     *  @endcode
+     *  (but is faster than making the calls separately).
     */
     pair<const_iterator,const_iterator>
     equal_range(const key_type& __x) const { return _M_t.equal_range(__x); }