D2: std.algorithm.find, but get part before what you were searching for

[Lars T. Kyllingstad]

Jonathan M Davis wrote:
> Lars T. Kyllingstad wrote:
> 
>> Jonathan M Davis wrote:
>>> std.algorithm.find() returns the rest of the range starting at what you
>>> were searching for (or an empty range if it wasn't in the given range).
>>> Is there a function in phobos which does a find but returns everything
>>> _before_ what you're searching for?
>>>
>>> I can't find one that will do that, and I don't see an obvious way of
>>> combining functions to get it. Naturally, I'll roll my own function for
>>> it if I have to, but if there's already a way to do it in phobos
>>> semi-cleanly, I'd probably prefer to do that. So, I'm enquiring as to
>>> whether anyone here knows of such a function or combination of functions.
>>> Thanks.
>>>
>>> - Jonathan M Davis
>>
>> Would std.algorithm.until() be what you're looking for?
>>
>>    http://www.digitalmars.com/d/2.0/phobos/std_algorithm.html#until
>>
>> -Lars
> 
> Hmm. I'd thought that I'd looked at that one and determined that it didn't 
> do what I was looking for, but on another inspection of it, it does look 
> like until() will do the job. It has the potential downside that unlike 
> find, it cannot take multiple ranges to be found, but in my case (and 
> probably most cases), that's not an issue. Thanks. Maybe this is what I get 
> for coding late at night...

I think the problem is the description:

   "Lazily iterates range until value sentinel is found, at which
    point it stops."

It doesn't say anything about returning the range up to that point.  You 
have to look at the example to see what it does.


> On a side note, it would be great if we could figure out a way to make the 
> docs more user-friendly - especially in std.algorithm. The functions are 
> great, and they're really versatile, but that seems to come at the cost of 
> incredibly nasty signatures. It can make it hard to find the function itself 
> among all of its parameters and its return type (especially the return 
> type). Right now, I'd expect it to scare a fair number of potential users 
> away. What the best solution would be, I don't know (perhaps making it so 
> that it lists information on the function without its signature and then 
> lists the signature at the end, or maybe we could find some way to give an 
> abstracted signature which gave the basic idea without all of the details), 
> but right now std.algorthm is definitely scary-looking. It's got great 
> stuff, but the docs could definitely use some improvement.

I agree.  There are several things which could be done:

   1. Alphabetical sorting of the list of functions at the top of the 
page.  This has already been implemented by Adam D. Ruppe and will be 
published with the next DMD release, AFAIK.

   2. Better separation of elements that share a doc comment.  until() 
is a great example:  You have to look more than twice at the signature 
to see that it is actually three signatures -- one struct and two functions.

   3. It's sometimes unclear which symbols are members of a class/struct 
and which are module-level symbols.  Tango's API documentation is better 
in this regard, since it has the symbol tree on the left-hand side of 
the page.

-Lars