From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17795 invoked by alias); 22 Feb 2003 22:16:01 -0000 Mailing-List: contact gcc-prs-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-prs-owner@gcc.gnu.org Received: (qmail 17771 invoked by uid 71); 22 Feb 2003 22:16:01 -0000 Resent-Date: 22 Feb 2003 22:16:01 -0000 Resent-Message-ID: <20030222221601.17769.qmail@sources.redhat.com> Resent-From: gcc-gnats@gcc.gnu.org (GNATS Filer) Resent-Cc: gcc-prs@gcc.gnu.org, gcc-bugs@gcc.gnu.org Resent-Reply-To: gcc-gnats@gcc.gnu.org, snyder@fnal.gov Received: (qmail 15077 invoked from network); 22 Feb 2003 22:06:53 -0000 Received: from unknown (HELO yaphank-clued0.fnal.gov) (131.225.226.144) by 172.16.49.205 with SMTP; 22 Feb 2003 22:06:53 -0000 Received: from yaphank-clued0.fnal.gov (localhost.localdomain [127.0.0.1]) by yaphank-clued0.fnal.gov (8.11.6/8.11.6) with ESMTP id h1MM6q303551 for ; Sat, 22 Feb 2003 16:06:52 -0600 Message-Id: <200302222206.h1MM6q303551@yaphank-clued0.fnal.gov> Date: Sat, 22 Feb 2003 22:16:00 -0000 From: snyder@fnal.gov Reply-To: snyder@fnal.gov To: gcc-gnats@gcc.gnu.org X-Send-Pr-Version: 3.113 Subject: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc. X-SW-Source: 2003-02/txt/msg01141.txt.bz2 List-Id: >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: >Environment: System: Linux karma 2.4.19-emp_2419p5a829i #1 Tue Sep 3 17:42:17 EST 2002 i686 unknown Architecture: i686 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 * 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 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 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 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 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 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 equal_range(const key_type& __x) const { return _M_t.equal_range(__x); } >Release-Note: >Audit-Trail: >Unformatted: