--Boundary-00=_5LTcDxZX1Rk9UyM
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

On Tuesday 08 Nov 2005 22:52, David Jarvie wrote:
> On Tuesday 08 Nov 2005 22:40, Nicolas Goutte wrote:
> > On Tuesday 08 November 2005 23:00, 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.
> > >
> > > 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.)
> >
> > Do you plan something like QDateTime::toString and QDateTime::fromString
> > for ISO dates, including time zone handling?
> >
> > (Also, I am not sure how flexible such functions need to be, I would need
> > such them for KBabel saving and loading Gettext PO files.)
>
> Yes, it would be a good idea. There would need to be an extension to the
> format codes to be able to specify where and in what format the time zone
> should appear. I suggest that the default format would append the
> abbreviated code for the time zone to the end of the string.

Here's a revised header file for the class, to add those methods.

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

--Boundary-00=_5LTcDxZX1Rk9UyM
Content-Type: text/x-c++hdr;
  charset="iso-8859-1";
  name="kdatetime.h"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="kdatetime.h"

/*
    This file is part of the KDE libraries
    Copyright (c) 2005 David Jarvie <software@astrojar.org.uk>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/

/** @file
 * Date/times with associated time zone
 * @author David Jarvie <software@astrojar.org.uk>.
 */

#ifndef _KDATETIME_H_
#define _KDATETIME_H_

#include <ktimezones.h>
#include "kdelibs_export.h"

class KDateTimePrivate;


/**
 * The KDateTime class represents a date/time with an associated time zone.
 *
 * The associated time zone has three possibilities:
 * - a UTC time zone
 * - a specified KTimezone
 * - a local clock time, using the current system time zone. If the system
 *   time zone changes, the UTC time for the instance will change
 *   correspondingly.
 *
 * @short A date/time with an associated time zone
 * @see KTimezone
 * @author David Jarvie <software@astrojar.org.uk>.
 * @since 4.0
 */
class KDECORE_EXPORT KDateTime
{
  public:
    /**
     * Constructs an invalid date/time using local clock time.
     */
    KDateTime();

    /**
     * Constructs a date/time with associated time zone. The time is
     * set to 00:00:00.
     *
     * @param date date in the time zone @p tz
     * @param tz   time zone, or null to use local clock time
     */
    explicit KDateTime(const QDate &date, const KTimezone *tz = 0);

    /**
     * Constructs a date/time with associated time zone.
     *
     * @param date date in the time zone @p tz
     * @param time time in the time zone @p tz
     * @param tz   time zone, or null to use local clock time
     */
    KDateTime(const QDate &date, const QTime &time, const KTimezone *tz = 0);

    /**
     * Constructs a date/time with associated time zone.
     * If @p dt is specified as a UTC time (i.e. @c dt.timeSpec() is @c Qt::UTC),
     * it is first converted to local time before being stored. The conversion is
     * done using the supplied timezone @p tz, or if that is null, using the
     * current system time zone.
     *
     * @param dt date and time
     * @param tz time zone, or null to use local clock time
     */
    explicit KDateTime(const QDateTime &dt, const KTimezone *tz = 0);

    /**
     *
     * @param date date in the time zone indicated by @p spec
     * @param spec @c Qt::UTC to use UTC time zone, or @c Qt::LocalTime to use
     *             local clock time
     */
    KDateTime(const QDate &date, Qt::TimeSpec spec);

    /**
     * Constructs a date/time expressed in either UTC or local clock time.
     *
     * @param date date in the time zone indicated by @p spec
     * @param time time in the time zone indicated by @p spec
     * @param spec @c Qt::UTC to use UTC time zone, or @c Qt::LocalTime to use
     *             local clock time
     */
    KDateTime(const QDate &date, const QTime &time, Qt::TimeSpec spec);

    /**
     * Constructs a date/time expressed in either UTC or local clock time.
     * If @p dt is given with a different time specification than @p spec (one
     * of @p spec and @c dt.timeSpec() is @c Qt::UTC, and the other is
     * @c Qt::LocalTime), @p dt is first converted to either UTC or local time
     * (as given by @p spec) before being stored. The conversion is done using
     * the current system time zone.
     *
     * @param date date and time
     * @param spec @c Qt::UTC to use UTC time zone, or @c Qt::LocalTime to use
     *             local clock time
     */
    KDateTime(const QDateTime &dt, Qt::TimeSpec spec);

    KDateTime(const KDateTime &other);
    ~KDateTime();

    KDateTime &operator=(const KDateTime &other);

    /**
     * Returns whether the date/time is null.
     *
     * @return @c true if both date and time are null, else @c false
     */
    bool isNull() const;

    /**
     * Returns whether the date/time is valid.
     *
     * @return @c true if both date and time are valid, else @c false
     */
    bool isValid() const;

    /**
     * Returns the date part of the date/time. The value returned should be
     * interpreted in terms of the instance's time zone.
     *
     * @return date value
     */
    QDate date() const;

    /**
     * Returns the time part of the date/time. The value returned should be
     * interpreted in terms of the instance's time zone.
     *
     * @return time value
     */
    QTime time() const;

    /**
     * Returns the date/time component of the instance, ignoring the time
     * zone. The value returned should be interpreted in terms of the
     * instance's time zone.
     *
     * @return date/time
     */
    QDateTime dateTime() const;

    /**
     * Returns the time zone for the date/time. If the date/time is specified
     * as a UTC time, a UTC time zone is always returned.
     *
     * @return time zone, or null if a local clock time
     */
    const KTimezone *timeZone() const;

    /**
     * Returns whether the date/time is a local clock time.
     * @return @c true if local clock time
     */
    bool isLocal() const;

    /**
     * Returns whether the date/time is a UTC time.
     *
     * @return @c true if UTC
     */
    bool isUTC() const;

    /**
     * Converts the time to a UTC time.
     *
     * @return converted time 
     */
    QDateTime toUTC() const;

    /**
     * Converts the time to a UTC time, measured in seconds since 00:00:00 UTC
     * 1st January 1970 (as returned by time(2)).
     *
     * @return converted time, or -1 if the date is out of range for time_t or
     *         @p utcDateTime.timeSpec() is not Qt::UTC 
     */
    uint toTime_t() const;

    /**
     * Sets the date part of the date/time.
     *
     * @param date new date value
     */
    void setDate(const QDate &date);

    /**
     * Sets the time part of the date/time.
     *
     * @param time new time value
     */
    void setTime(const QTime &time);

    /**
     * Sets the stored time to be expressed as either UTC or local clock time.
     * Any previous time zone is forgotten. The stored time value is left
     * unchanged, so that if the time zone or UTC/local clock time indicator has
     * changed, it will now represent a different UTC time.
     *
     * @param spec @c Qt::UTC to use UTC time zone, or @c Qt::LocalTime to use
     *             local clock time
     */
    void setTimeSpec(Qt::TimeSpec spec);

    /**
     * Sets the time zone in which the date/time is expressed.
     * The stored time value is left unchanged, so that if the time zone has
     * changed, it will now represent a different UTC time.
     *
     * @param tz new time zone, or null to change to local clock time
     */
    void setTimeZone(const KTimezone *tz);

    /**
     * Sets the time to a UTC time, measured in seconds since 00:00:00 UTC
     * 1st January 1970 (as returned by time(2)). If the KDateTime instance is
     * expressed in either a time zone or as local clock time, the UTC time is
     * first converted to the instance's time zone (the current system time
     * zone if using local clock time) before being stored.
     *
     * @param secsSince1Jan1970UTC UTC time, measured in seconds since 00:00:00 UTC
     *                             1st January 1970 (as returned by time(2))
     */
    void setTime_t(uint secsSince1Jan1970UTC);

    /**
     * Returns a date/time @p secs seconds later than the stored date/time.
     * The calculation is done in UTC to ensure that clock changes (e.g. daylight
     * savings) in the time zpme do not affect the result. The result is
     * expressed in the same time zone as the original instance.
     *
     * @return resultant date/time
     */
    KDateTime addSecs(int secs) const;

    /**
     * Returns a date/time @p days days later than the stored date/time.
     * The result is expressed in the same time zone as the original instance.
     *
     * @return resultant date/time
     */
    KDateTime addDays(int days) const;

    /**
     * Returns a date/time @p months months later than the stored date/time.
     * The result is expressed in the same time zone as the original instance.
     *
     * @return resultant date/time
     */
    KDateTime addMonths(int months) const;

    /**
     * Returns a date/time @p years years later than the stored date/time.
     * The result is expressed in the same time zone as the original instance.
     *
     * @return resultant date/time
     */
    KDateTime addYears(int years) const;

    /**
     * Calculates the number of days from this date/time to @p dt2.
     * In calculating the result, @p dt2 is first converted to this instance's
     * time zone. The number of days difference is then calculated ignoring
     * the time parts of the two date/times. For example, if this date/time
     * was 13:00 on 1 January 2000, and @p dt2 was 02:00 on 2 January 2000,
     * the result would be 1.
     *
     * @return number of days difference
     */
    int daysTo(const KDateTime &dt2) const;

    /**
     * Returns the number of seconds from this datetime to @p dt2.
     * Before performing the comparison, the two datetimes are converted to UTC
     * to ensure that the result is correct if one of the two datetimes has
     * daylight saving time (DST) and the other doesn't.
     *
     * @param dt2 other date/time
     * @return number of seconds difference
     */
    int secsTo(const KDateTime &dt2) const;

    /**
     * Returns the datetime as a string. The @p format parameter determines the
     * format of the result string. The following codes may be used, in addition
     * to those defined for QDateTime::toString():
     *
     * ZZZ - the abbreviated time zone code, e.g. UTC, EDT, BST.
     * ZZZZ - the name of the time zone, e.g. Europe/London.
     * fff  - the UTC offset of the time zone in hours and minutes, e.g. -2:30.
     *
     * @param format format for the string
     * @return formatted string
     */
    QString toString(const QString &format) const;

    /**
     * Returns the datetime as a string. The @p format parameter determines the
     * format of the result string. The string is that returned by
     * QDateTime::toString(format), with the abbreviated time zone code (e.g.
     * UTC, EDT, BST) appended.
     *
     * @param format Qt::TextDate, Qt::ISODate or Qt::LocalDate. See QDateTime
     *               description for details.
     * @return formatted string
     */
    QString toString(Qt::DateFormat format = Qt::TextDate) const;

    /**
     * Check whether this date/time is simultaneous with another.
     * Before comparing the instances, they are converted to the same time zone.
     *
     * @return @c true if the two instances represent the same time, @c false otherwise
     */
    bool operator==(const KDateTime &other) const;
    inline bool operator!=(const KDateTime &other) const { return !(*this == other); }

    /**
     * Check whether this date/time is earlier than another.
     * Before comparing the instances, they are converted to the same time zone.
     *
     * @return @c true if the this instance represent an earlier time than @p other,
     *         @c false otherwise
     */
    bool operator<(const KDateTime &other) const;
    inline bool operator<=(const KDateTime &other) const { return !(other < *this); }
    inline bool operator>(const KDateTime &other) const { return other < *this; }
    inline bool operator>=(const KDateTime &other) const { return !(*this < other); }

  private:
    KDateTimePrivate *d;
};

#endif

--Boundary-00=_5LTcDxZX1Rk9UyM--