On Sunday, 19 November 2017 at 16:02:34 UTC, Jonathan M Davis
wrote:
On Sunday, November 19, 2017 15:01:50 Rumbu via Digitalmars-d
wrote:
On Saturday, 18 November 2017 at 22:46:20 UTC, Jon Degenhardt
Was the documentation on Duration not informative enough, or
did you have trouble finding it from the documentation for the
benchmarking functions, or something else? Simply converting a
Duration to a string gives you what I would have thought would
have been plenty human readable (though obviously not
necessarily what you want in all cases), and it's split and
total functions should make it straightforward to put the
result in some other format if that's what you want. Was the
documentation on those not enough?
1) Finding the documentation for Duration from the documentation
of std.datetime.stopwatch is not quick enough. There is only one
link from the page, and it's near the bottom, with the benchmark
function (which is rarely what I need). Also, aside from the link
at the bottom of the page, no mention of what module it is in.
2) The stopwatch page doesn't describe a Duration, and it also
refers to core.time.MonoTime, plus a discussion that the
"precision of StopWatch differs from system to system. And
references to the depreciated TickDuration
Before one can do anything, one has to parse through all this
material. It's all necessary material for tasks requiring very
high accuracy. However, if what is being timed is inherently
precise only to hundreds or tens of milliseconds, then this is
way more investigation than needs to be done for the task at hand.
3) hecto-nanoseconds is not an especially common unit of measure.
4) Even from the Duration documentation, there aren't many
examples of conversion to other standard units of measure. The
only one I see is converting 12 days to hecto-nanoseconds, which
isn't helpful as an example.
5) The built in conversion to string is one I've never found
useful. Generally, I'm putting a set a values in a table, perhaps
a large table. The output shown is not amenable to this. And yes,
it often needs to be both human and machine readable. For
example, I may read the table into R and plot the values.
Some recommendations:
a) Put a link to the Duration documentation in StopWatch page.
b) Put examples in the StopWatch and Duration sections that
explicitly show how to convert to usecs, milliseconds, and
perhaps seconds in floating point formats. Show this in the
context of printing them.
c) Try to clean up some of the language describing the backward
compatibility vs the newer stuff. It's a bit intertwined. The
language doesn't have to explain the depreciation or justify it,
at least not mixed with the description of the new facilities.
d) Be more explicit in the documentation about tradeoffs of
integer precision used in Duration and floating point accuracy.
That Duration supports this high accuracy without loss of
precision in the face of mathematical operations is a real value,
one worth calling out. However, it's also the case that this high
mathematical precision is not required for many timing use cases,
especially in the printing, but even calculations.
Making this distinction puts the stopwatch facilities more in the
position of being an enabler of good end-user choices and less
trying to prevent end-user mistakes. The reality is, that the
accuracy needs are only known in the context of the timing
measurements being done. The library code does not have enough
information to know. However, providing the user with the
information to make good choices about accuracy representation is
a real benefit.
