Bug#196380: libstdc++5-3.3-doc: lower_bound is not well documented

[Victor Porton <porton@ex-code.com>]

On 06-Jun-2003 Phil Edwards wrote:
> On Fri, Jun 06, 2003 at 08:37:13PM +0600, Victor Porton wrote:
>> It is unclear from the API docs whether std::lower_bound if there are no
>> element element "not less than" val.
> 
> That question does not parse.  Could you rephrase please?
> 
> The "brief" description might be helpful you here here, too.
> 
> If you have suggestions, we'd be glad to hear them.

The doc of std::lower_bound says:

[[
Finds the first position in which val could be inserted without changing
the ordering.

Parameters:
    first       An iterator.
    last        Another iterator.
    val         The search term.

Returns:
    An iterator pointing to the first element "not less than" val.
]]

"Returns" clause does not consider the case when there are no elements "not
less than" val in the iterators range.

Please add explicit consideration of this case in the docs.

It is my guess that in the case of no elements "not less than" val the
returned value is "last" because "last" is the iterator value where one can
insert without changing the ordering when there are no elements "not less
than" val.

But it is only a guess from the docs, the return value in the case in
consideration should be stated explicitly in the docs.

Also existing short description of std::lower_bound says that returned
iterator is pointing to an element. "last" may no point to an element (be a
past-the-end iterator). If "last" indeed may be returned, then the phrase
that the returned iterator is pointing to an element should be removed from
the short description or at least explicitly overridden in the long
description (claiming that it is false in some cases (if there are these
cases)).

-- 
Victor Porton (porton@ex-code.com)