On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
This is a *good* documentation:
- "Count" is a better name than "walkLength"; every other
programming language will use concepts similar to count, cnt,
length, len.
meh, I like walkLength. I hate it when a innocuous looking little
function does a bunch of expensive work unexpectedly,
"walkLength" really points out the worst case. Also, it's
important to be reminded that is might actually iterate your
range, which the "walk" bit really does, so if it's an inputRange
then say goodbye to your data.
- You don't need to understand computer science terms to find
out what a function does;
A little nudge to understand some important concepts never hurts.
It can sometimes get a bit obscure though, or be too
self-referential (there are probably some non-trivial cycles in
the required knowledge graph).
- If you are really interested about more than finding out the
number of elements, there is a performance hint in the Remarks
section.
Considering that despite the fact my phone can perform billions
of calculations per second but it still takes >2s to open up a
text-editor app (on a good day), it seems worthwhile to point out
performance a little more forcefully than "here's some other
information if you feel like it".
- Links are provided to concepts: even the return type (int)
has a link.
[ ... ]
On the contrary, the D documentation, introduces a bunch of
non-linked concepts, but it tells me that it's possible to
perform O(n) evaluations:
- isInputRange
- isInfiniteRange
- hasLength
- empty
- popFront
We should definitely have more links.
There is no indication what happens if the range is undefined
in D docs. In fact, inconsistent behavior:
- it will return 0 in case of null arrays;
- it will throw AccessViolation for null ranges (or probably
segfault on Linux);
Fair point. I'd love it if phobos range functions treated arrays
100% consistently with custom ranges, but apparently that boat
sailed off in multiple directions at once long ago...
