[boost] [date_time] fractional_seconds: documentation suggestions

From: Caleb Epstein (caleb.epstein_at_[hidden])
Date: 2005-06-08 11:35:31

I think the specification of "fractional_seconds" in the time_duration
class is unclear.  Using the multi-argument constructor, and passing
1000 for the 4th argument, am I specifying milliseconds? Microseconds?
Does it depend on the compile-time resolution of the class?  If so
(which is my suspicion), then using the 4-argument form of the ctor
can lead to incorrect results if the resolution is changed.  That
seems like a bad thing.

Looking at the implementation, I can see that I can divide the result
of fractional_seconds() by the return value of ticks_per_second() to
get a floating point value < 1.0, but I think that this should be more
clearly spelled out in the section:

doc/html/date_time/posix_time.html#date_time.posix_time.time_duration

I'm not sure of the wording, but something like:

*Construction*

Mention that fractional_seconds depends on the compile-time resolution
of the time_duration.  I'd personally suggest it not be used and that
the count-based construction be used instead.

*Accessors Section*

<tr>
<td>static long ticks_per_second()</td>
<td>The number of ticks per second.  This is the resolution of the
time_duration class</td>
<td>long ticks_per_sec = time_duration::ticks_per_second();</td>

<tr>
<td>long fractional_seconds() const</td>
<td>Get the number of fractional seconds.  The return value will be in
the range [0, ticks_per_second())</td>
<td>
  time_duration td(1,2,3, 1000); td.fractional_seconds() --> 1000 <br/>
  double subsec = td.fractional_seconds() /
time_duration::ticks_per_second () --> 0.001 (?)
</td>

Is this reasonable?

-- 
Caleb Epstein
caleb dot epstein at gmail dot com