On Tuesday, 15 December 2015 at 02:39:16 UTC, Steven
Schveighoffer wrote:
On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
InputRange find(alias pred = "a == b", InputRange,
Element)(InputRange
haystack, Element needle) if (isInputRange!InputRange &&
is(typeof(binaryFun!pred(haystack.front, needle)) : bool));
InputRange find(alias pred, InputRange)(InputRange haystack) if
(isInputRange!InputRange);
R1 find(alias pred = "a == b", R1, R2)(R1 haystack, R2 needle)
if
(isForwardRange!R1 && isForwardRange!R2 &&
is(typeof(binaryFun!pred(haystack.front, needle.front)) :
bool) &&
!isRandomAccessRange!R1);
Tuple!(Range, size_t) find(alias pred = "a == b", Range,
Ranges...)(Range haystack, Ranges needles) if (Ranges.length >
1 &&
is(typeof(startsWith!pred(haystack, needles))));
Range1 find(Range1, alias pred, Range2)(Range1 haystack,
BoyerMooreFinder!(pred, Range2) needle);
If you can decipher this into what find actually will accept,
then you
have more patience than me. I think what I wanted (it's
difficult to
remember) is whether I could pass in a subrange for find to
search for
as the needle. It appears to reject cases where the haystack
is a random
access range and the needle is a range (but it does work).
Heh, looking at the source, I see I was a victim of improper
documentation.
There are 2 additional overloads of find that are NOT
DOCUMENTED.
It's likely that the 2 overloads vary only by constraints, and
that's why they are not documented.
But as a user, again, I shouldn't have to care what the
constraints are specifically.
-Steve
I started exploring D a couple of months ago and I was the
original poster in the reddit thread who sparked this discussion.
While on the topic of documentation I wanted to quickly put in my
thoughts about what frustrated me with the documentation:
- I didn't understand the visual hierarchy for templates at
first. e.g. canFind:
https://dlang.org/phobos/std_algorithm_searching.html#canFind. I
don't remember the exact examples but I had to look at the source
code to understand what this was trying to show me
- Runnable examples would be *so* useful! They're present on the
homepage, why can't the examples provided in the inline docs be
runnable as well?
- Linking types, functions, etc. in the function signatures would
be great *if possible*. e.g.:
bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart,
R2 withThis) if (isInputRange!R1 && isInputRange!R2 &&
is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) :
bool));
Make bool, isInputRange, typeof, and binaryFun all links to their
definitions. If I don't know what "isInputRange" does, do I
really have to go spend more time to figure out where it lives?
- Add another line break between overloaded methods! Having no
separation between lines makes things very difficult to sort out
Here's an imgur album I created to show some suggestions for
function signatures: http://imgur.com/a/njHKI
- Dead links = compile error when compiling documentation? This
was annoying when trying to find out more about OutputRanges. The
only resource I found was on the std.range page in the tee
definition, and the link was dead:
http://dlang.org/phobos/std_range.html#.tee
- Link to where the code is implemented in Phobos at the time of
compilation. e.g. clicking the actual name of "find" could link
me here:
https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498. More than once I found that reading the code was more useful than reading the documentation.
I find that I learn best by reading documentation. Go's
documentation is phenomenal and it's very easy to follow and
understand (yes, I realize this is kind of comparing apples to
oranges in terms of complexity). I don't want to have to have to
read documentation on understanding the documentation.
I'm currently on winter break from university and would love to
help contribute some of these changes if people think they're
useful as well.
