public inbox for gcc-prs@sourceware.org
help / color / mirror / Atom feed
* libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
@ 2003-02-22 22:16 snyder
0 siblings, 0 replies; 3+ messages in thread
From: snyder @ 2003-02-22 22:16 UTC (permalink / raw)
To: gcc-gnats
>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:
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
@ 2003-02-25 6:36 Phil Edwards
0 siblings, 0 replies; 3+ messages in thread
From: Phil Edwards @ 2003-02-25 6:36 UTC (permalink / raw)
To: nobody; +Cc: gcc-prs
The following reply was made to PR libstdc++/9811; it has been noted by GNATS.
From: Phil Edwards <phil@jaj.com>
To: snyder@fnal.gov
Cc: gcc-gnats@gcc.gnu.org, gcc-patches@gcc.gnu.org
Subject: Re: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
Date: Tue, 25 Feb 2003 01:27:18 -0500
On Sat, Feb 22, 2003 at 04:06:52PM -0600, snyder@fnal.gov wrote:
> 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.
Thanks, this is in now.
--
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace. We seek
not your counsel, nor your arms. Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen. - Samuel Adams
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: libstdc++/9811: incorrect documentation for std::map::lower_bound, etc.
@ 2003-02-25 6:28 pme
0 siblings, 0 replies; 3+ messages in thread
From: pme @ 2003-02-25 6:28 UTC (permalink / raw)
To: gcc-bugs, gcc-prs, nobody, snyder
Synopsis: incorrect documentation for std::map::lower_bound, etc.
State-Changed-From-To: open->closed
State-Changed-By: pme
State-Changed-When: Tue Feb 25 06:28:20 2003
State-Changed-Why:
User thoughtfully supplied a patch. :-)
http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=9811
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2003-02-25 6:36 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2003-02-22 22:16 libstdc++/9811: incorrect documentation for std::map::lower_bound, etc snyder
2003-02-25 6:28 pme
2003-02-25 6:36 Phil Edwards
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).