Improving std.algorithm.find

[sybrandy]

> 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.

That paragraph would have been immensely useful to me a few months ago.
>
> 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).

Agreed.  I'm also a big fan of examples as it's very easy to look at an 
example and get something working.  Then, once you see it work and get 
somewhat of an understanding, you can dig deeper into the details to 
learn more.

Casey