Proposed new KDateTime class

[David Jarvie]

On Friday 11 Nov 2005 14:58, Benjamin Meyer wrote:
> On Tuesday 08 November 2005 5:00 pm, David Jarvie wrote:
> > Now that the time zone classes have been updated, there is a need to be
> > able to handle date/times which have an associated time zone. I attach a
> > proposed new kdecore class, KDateTime, which represents a date/time with
> > an associated time zone. The aim is to make time zone handling as
> > automatic as possible when manipulating dates and times. Its interface is
> > very similar to QDateTime, but it is not inherited from QDateTime mainly
> > because QDateTime's methods are not virtual.
>
> You don't inherit from QDateTime so I recommend coping the api exactly when
> possible.

I have copied the QDateTime interface as far as possible, but have omitted the 
following methods:

currentDateTime(): I thought that it would be best to leave it to the caller 
to decide whether to specify the actual time zone, or to leave it as the 
default system time zone (which can potentially change).

fromString(): this needs to be added - see other comments in this thread.

timeSpec(): this is replaced by isUTC(), isLocal() and timeZone().

toTimeSpec(): this is replaced by KTimezone::convert().

toLocalTime(): this should be included.

operator<<() and operator>>(): are these needed?

> > The code compiles, but I until I finish the test program is untested.
> > Note that if the new class is committed, the time zone classes will need
> > to be amended to handle the new class.
> >
> > Comments please. (Note that I am going away and won't be able to respond
> > for a few days.)
>
> Header simple comments:
>
> kill the @file, there is no point to it.

Nicholas has since commented on this, so I propose to leave it in.

> remove the _ start and end of the define

Some kdelibs headers use _ before and after the define, others don't. Is there 
any convention?

> timeZone v.s. timezone - one should be picked

I think that the KTimezone classes should really have been called KTimeZone 
etc., since the correct spelling is "time zone", not "timezone". But those 
classes already exist. I've used a capital Z in new method names.

> setTime_t argument can just be "seconds"

OK.

> Should there be an operator= for QDateTime?

I don't think that there should be, to ensure that the caller explicitly sets 
the time zone. It would be too easy to forget about the time zone if 
operator=(QDateTime) was provided. For the same reason, the constructor 
KDateTime(QDateTime) is made explicit.

> The docs look good (from quickly skimming), thank you for taking the time.
> The only think I would think you might want to add an example code usage to
> the class intro.
>
> Can you create an autotest using the qttestlib for the class?

I'll do some example code and an autotest once the interface is finalised.

-- 
David Jarvie.
KAlarm author and maintainer.
http://www.astrojar.org.uk/linux/kalarm.html