This is the mail archive of the
gcc-bugs@gcc.gnu.org
mailing list for the GCC project.
libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
- From: snyder at fnal dot gov
- To: gcc-gnats at gcc dot gnu dot org
- Date: Sat, 22 Feb 2003 16:06:52 -0600
- Subject: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
- Reply-to: snyder at fnal dot gov
>Number: 9811
>Category: libstdc++
>Synopsis: incorrect documentation for std::map::lower_bound, etc.
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: unassigned
>State: open
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Sat Feb 22 22:16:00 UTC 2003
>Closed-Date:
>Last-Modified:
>Originator: scott snyder
>Release: 3.4 20030218 (experimental)
>Organization:
<organization of PR author (multiple lines)>
>Environment:
System: Linux karma 2.4.19-emp_2419p5a829i #1 Tue Sep 3 17:42:17 EST 2002 i686 unknown
Architecture: i686
<machine, os, target, libraries (multiple lines)>
host: i686-pc-linux-gnu
build: i686-pc-linux-gnu
target: i686-pc-linux-gnu
configured with: ../gcc/configure --prefix=/usr/local/gcc --enable-threads=posix --enable-long-long
>Description:
I noticed some problems with the documentation for the lower_bound, etc.
methods for std::map and std::multimap.
Here's an example, for std::map::lower_bound:
/**
* @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.
*
* 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.
*/
First of all, the description in @return is inconsistent with
what's described in the paragraph below, for the case where the
value being looked up is not found: the first says that end() is
returned; the second says that the function returns an iterator
to the next element past where the value being looked up would
have been. I believe that the second of those is correct.
Second, the description states that this function is useful only
for multimaps. However, that's not true. It would be true if
the erroneous behavior that the @return section described
(always returning end() if x isn't found) was what actually happend;
however, with the actual behavior, this method is useful even
for maps. (If you want to find the first key greater than some
probe value, for example, where the probe might not actually
exist in the map.)
The corresponding documentation for std::multimap also has the first
of these problems (though not the second :) ).
>How-To-Repeat:
n/a
>Fix:
2003-02-21 Scott Snyder <snyder at fnal dot gov>
* 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.
Index: libstdc++-v3/include/bits/stl_map.h
===================================================================
RCS file: /cvsroot/gcc/gcc/libstdc++-v3/include/bits/stl_map.h,v
retrieving revision 1.16
diff -u -p -c -r1.16 stl_map.h
*** libstdc++-v3/include/bits/stl_map.h 23 Dec 2002 17:36:24 -0000 1.16
--- libstdc++-v3/include/bits/stl_map.h 22 Feb 2003 22:04:46 -0000
*************** namespace std
*** 496,508 ****
/**
* @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.
*
! * 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.
*/
iterator
lower_bound(const key_type& __x) { return _M_t.lower_bound(__x); }
--- 496,508 ----
/**
* @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 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
! * 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); }
*************** namespace std
*** 511,522 ****
* @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.
*
! * 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().
*/
const_iterator
lower_bound(const key_type& __x) const { return _M_t.lower_bound(__x); }
--- 511,522 ----
* @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
! * 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
! * 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); }
*************** namespace std
*** 524,532 ****
/**
* @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.
*/
iterator
upper_bound(const key_type& __x) { return _M_t.upper_bound(__x); }
--- 524,531 ----
/**
* @brief Finds the end of a subsequence matching given key.
* @param x Key of (key, value) pair to be located.
! * @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); }
*************** namespace std
*** 534,543 ****
/**
* @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.
*/
const_iterator
upper_bound(const key_type& __x) const
--- 533,540 ----
/**
* @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 first iterator
! * greater than key, or end().
*/
const_iterator
upper_bound(const key_type& __x) const
*************** namespace std
*** 549,562 ****
* @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 only makes sense for multimaps.
*/
pair<iterator,iterator>
equal_range(const key_type& __x)
--- 546,559 ----
* @return Pair of iterators that possibly points to the subsequence
* matching given key.
*
! * 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 probably only makes sense for multimaps.
*/
pair<iterator,iterator>
equal_range(const key_type& __x)
*************** namespace std
*** 568,581 ****
* @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 only makes sense for multimaps.
*/
pair<const_iterator,const_iterator>
equal_range(const key_type& __x) const
--- 565,578 ----
* @return Pair of read-only (constant) iterators that possibly points to
* the subsequence matching given key.
*
! * 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 probably only makes sense for multimaps.
*/
pair<const_iterator,const_iterator>
equal_range(const key_type& __x) const
Index: libstdc++-v3/include/bits/stl_multimap.h
===================================================================
RCS file: /cvsroot/gcc/gcc/libstdc++-v3/include/bits/stl_multimap.h,v
retrieving revision 1.16
diff -u -p -r1.16 stl_multimap.h
--- libstdc++-v3/include/bits/stl_multimap.h 23 Dec 2002 17:36:24 -0000 1.16
+++ libstdc++-v3/include/bits/stl_multimap.h 22 Feb 2003 22:05:02 -0000
@@ -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); }
>Release-Note:
>Audit-Trail:
>Unformatted: