public inbox for gcc-prs@sourceware.org help / color / mirror / Atom feed
From: snyder@fnal.gov To: gcc-gnats@gcc.gnu.org Subject: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc. Date: Sat, 22 Feb 2003 22:16:00 -0000 [thread overview] Message-ID: <200302222206.h1MM6q303551@yaphank-clued0.fnal.gov> (raw) >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@fnal.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:
next reply other threads:[~2003-02-22 22:16 UTC|newest] Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top 2003-02-22 22:16 snyder [this message] 2003-02-25 6:28 pme 2003-02-25 6:36 Phil Edwards
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=200302222206.h1MM6q303551@yaphank-clued0.fnal.gov \ --to=snyder@fnal.gov \ --cc=gcc-gnats@gcc.gnu.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).