Improving std.algorithm.find

[Jonathan M Davis]

On Monday, July 19, 2010 16:36:57 sybrandy wrote:
> > I think that the problem with find() is not so much find() but it's
> > documentation. In all honesty, anything with a return type like
> > FindResult!(Range, Ranges) is going to scare people off.
> 
> I fully agree.  I had no idea from the documentation what something like
> this was: [1,2,3,4][].  The array documentation doesn't have any
> details, so for the most part I've stayed away from std.algorithm
> because I don't understand the return types very well.  Better
> documentation would help a lot.
> 
> Casey

In most cases, the return types are just ranges, but because they're constructed 
by the algorithm, the algorithm creates its own range type. So, generally, all 
you need to know is that a range is being returned. But even then, you run into 
some issues where you need to do stuff like run the returned range through 
array() to get something useable - depending on what you're doing with it. 
Regardless of the return type though, std.algorithm is definitely a prime example 
of how auto is your friend. That way you often don't have to care all that much 
about what the return type really looks like.

However, the documentation on it is obviously ugly. It really should give the 
programmer exactly what they need to use the function and nothing more. As it 
stands, you have to really want to use it to figure it out. Personally, I think 
that it's well worth it - std.algorithm is fantastic - but the documentation is 
nowhere near as straightforward as it should be (even if using the functions is 
actually pretty straightforward in most cases).

- Jonathan M Davis