Re: [boost] Some points concerning the boost.date_time lib

From: Jeff Garland (jeff_at_[hidden])
Date: 2003-11-03 09:21:05

On Mon, 03 Nov 2003 10:39:55 +0100, Daniel Spangenberg wrote
> Hello boosters, Hello Jeff Garland,
> 
> After working somewhat with the 1.30 boost version of the date time
> library during this weekend I stumbled about the following points:
> 
> 1)  I was really missing the usual assignment operators += and -= for
> the
> arithmetic of ptime and date_duration/time_duration, like e.g.
> 
> ptime& ptime::operator+=(date_duration);
> ptime& ptime::operator-=(time_duration);
> time_duration& time_duration::operator+=(time_duration);
> date_duration& date_duration::operator-=(date_duration);
> date& date::operator+=(date_duration);
> 
> Is this just an oversight? Although it would require a bunch of further

This is a reasonable request.  Will add it to the list.
 
> 2) I really think, that accessor methods for milliseconds, microseconds
> and nanoseconds should be made available for the time_duration class. See
> also point (3) which is related to this one.

This will be in the 1.31 release (in the current CVS).  Methods are called
total_milliseconds, total_microseconds, and total_nanoseconds.

> 3) To my opinion the name fractional_seconds is misleading, even 
> worse that the usually found symbol fs in the source code can be 
> misread as femtoseconds. Do I correctly understand, that the actual 
> meaning of fractional_seconds does depend on the current resolution? 

Yes, it depends on how the library is compiled.  This allows for users with
lower resolution needs to compile things to use less storage for the time
representations (64 instead of 96 bits).  As for the fs that can be lengthened
to be clearer although I'd bet you are one of the few people that have heard
of femtoseconds!

> If so, this means, that I cannot see on the first sight, how much 
> time the fourth argument of the c'tor
> 
> time_duration(hour_type hours, min_type minutes, sec_type seconds=0,
>    fractional_seconds_type frac_sec = 0);
> 
> actually means. The same problem arises for the member function
> fractional_seconds(), from whichs result I cannot conclude from 
> the code how much time it stands for.

I agree that this is not the prefered way for users to specify sub-second
resolutions.  This is why there are all the 'count-based' constructors:
milliseconds, nanoseconds, etc.

> I think the main problem arises from the "backward" reading effect of
> fractional_seconds. This has the effect that a value of 3 
> fractional_seconds() does not show the distance of this 3 from 
> the decimal point in expressions like
> 
> 00:00:00.300000
> 
> or
> 
> 00:00:00.000003

Ok.

> Normal users are known of the concept of milliseconds which have a fixed
> relation to seconds and other date/time components, but 
> fractional_seconds(),although parallelly providable in the above 
> mentioned c'tor, have not.

I agree that this is a bit tricky, but the alternative is to rewrite the set
of constructor parameters for every change in the representable resolution. 
And with the addition of the total_milliseconds, etc methods the need to use
fractional_seconds should be quite rare.

> 4) As far as I know of, the formula used inside the header
> c_local_time_adjuster.hpp
> 
> std::time_t t2 = dd.days()*86400 + td.hours()*3600 + td.minutes()*60 
> + td.seconds();
> 
> bases on one **possible** implementation of time_t and is not guaranteed
> to work generally (also it should work for those implementations I know
> of).
>
> Since the C standard does **explicitely** not specify the enconding 
> of time_t, we cannot exclude for example, that an implementation 
> uses an arbitrary offset or scaling which would make the above 
> quoted formula meaningless;
> 
> otherwise the need for the function difftime() would not exist.
> The C standard only demands, that time_t  must be of some arithmetic
> type
> capable to represent times and that (time_t)(-1) is an valid expression.

Wow.  I sure hope no one revises any of the C libraries in practice to take
advantage of this -- it would be chaos for the users that depend on this
behavior.  Even so, I can look into using difftime....

> 5) I think the documentation misses the creator microsec in
> ..date_time/doc/class_time_duration.html

Yep. Will add.

> Besides these critics I would like to say that I think that
> boost.datetime library is a very nice and valuable tool to work 
> with and I want to thank you, Jeff Garland specifically, for this 
> contribution!

Sure, and thanks for your feedback -- that's how it gets better :-)

Jeff