## NAME

DwDateTime -- Class representing an RFC-822 date-time

## SYNOPSIS

    class DW_EXPORT DwDateTime : public DwFieldBody {

    public:

        DwDateTime();
        DwDateTime(const DwDateTime& aDateTime);
        DwDateTime(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwDateTime();
        const DwDateTime& operator = (const DwDateTime& aDateTime);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        DwUint32 AsUnixTime() const;
        void FromUnixTime(DwUint32 aTime);
        time_t AsCalendarTime() const;
        void FromCalendarTime(time_t aTime);
        DwInt32 DateAsJulianDayNum() const;
        void DateFromJulianDayNum(DwInt32 aJdn);
        DwInt32 TimeAsSecsPastMidnight() const;
        void TimeFromSecsPastMidnight(DwInt32 aSecs);
        int Year() const;
        void SetYear(int aYear);
        int Month() const;
        void SetMonth(int aMonth);
        int Day() const;
        void SetDay(int aDay);
        int Hour() const;
        void SetHour(int aHour);
        int Minute() const;
        void SetMinute(int aMinute);
        int Second() const;
        void SetSecond(int aSecond);
        int Zone() const;
        void SetZone(int aZone);
        static void SetDefaultZone(int aZone);
        static DwDateTime* NewDateTime(const DwString&, DwMessageComponent*);
        static DwDateTime* (*sNewDateTime)(const DwString&, DwMessageComponent*);

    protected:

        void _FromUnixTime(DwUint32 aTime);
        void _FromCalendarTime(time_t aTime);
        int  mYear;
        int  mMonth;
        int  mDay;
        int  mHour;
        int  mMinute;
        int  mSecond;
        int  mZone;
        static int sDefaultZone;
        static int sIsDefaultZoneSet;

    public:

        virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
        virtual void CheckInvariants() const;

    protected:

        void _PrintDebugInfo(ostream& aStrm) const;
    };

## DESCRIPTION

`DwDatetime` represents a date-time as described in RFC-822 and RFC-1123. The parse method for `DwDateTime` parses the string representation to extract the year, month, day, hour, minute, second, and time zone. `DwDateTime` provides member functions to set or get the individual components of the date-time.

## Public Member Functions

DwDateTime()
DwDateTime(const DwDateTime& aDateTime)
DwDateTime(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which assigns the current date and time as reported by the operating system.

The second constructor is the copy constructor. The parent of the new `DwDateTime` object is set to `NULL`.

The third constructor sets `aStr` as the `DwDateTime` object's string representation and sets `aParent` as its parent. The virtual member function `Parse()` should be called after this constructor to extract the date and time information from the string representation. Unless it is `NULL`, `aParent` should point to an object of a class derived from `DwField`.

const DwDateTime& operator = (const DwDateTime& aDateTime)

This is the assignment operator, which sets this `DwDateTime` object to the same value as `aDateTime`.

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwDateTime` objects. The parse method creates or updates the broken-down representation from the string representation. For `DwDateTime` objects, the parse method parses the string representation to extract the year, month, day, hour, minute, second, and time zone.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwDateTime` objects. It should be called whenever one of the object's attributes is changed in order to assemble the string representation from its broken-down representation. It will be called automatically for this object by the parent object's `Assemble()` member function if the is-modified flag is set.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

This virtual function, inherited from `DwMessageComponent`, creates a new `DwDateTime` on the free store that has the same value as this `DwDateTime` object. The basic idea is that of a virtual copy constructor.

DwUint32 AsUnixTime() const

Returns the date and time as a UNIX (POSIX) time, defined as the number of seconds elapsed since 1 Jan 1970 00:00:00 UTC.

void FromUnixTime(DwUint32 aTime)

Sets the date and time from `aTime`, interpreted as the number of of seconds elapsed since 1 Jan 1970 00:00:00 UTC.

time_t AsCalendarTime() const

Returns the date and time as a value of type `time_t` that conforms to the native format returned by the `time()` ANSI C function. On most UNIX systems, this function returns the same value as `AsUnixTime()`. (For efficiency, use `AsUnixTime()` instead of `AsCalendarTime()` if possible).

void FromCalendarTime(time_t aTime)

Sets the date and time from `aTime`, which is assumed to be in a format compatible with the native `time()` ANSI C function. For most UNIX systems, this function is the same as the function `FromUnixTime()`. (For efficiency, use `FromUnixTime()` instead of `FromCalendarTime()` if possible).

DwInt32 DateAsJulianDayNum() const

Returns the Julian Day Number, defined as the number of days elapsed since 1 Jan 4713 BC. The JDN is calculated directly from the values of the year, month, and day; time zone information is ignored.

void DateFromJulianDayNum(DwInt32 aJdn)

Sets the year, month, and day from `aJdn`, interpreted as a Julian Day Number. By definition, the JDN is the number of days elapsed since 1 Jan 4713 BC. This member function ignores time zone information.

DwInt32 TimeAsSecsPastMidnight() const

Returns the number of seconds past midnight. The value is calculated directly from the values of the hour, minute, and second; time zone information is ignored.

void TimeFromSecsPastMidnight(DwInt32 aSecs)

Sets the hour, minute, and second from `aSecs`, interpreted as the number of seconds elapsed since midnight. This member function ignores time zone information. The argument `aSecs` should be in the range 0 to 86399, inclusive.

int Year() const

Returns the four digit year, e.g. 1997.

void SetYear(int aYear)

Sets the year from `aYear`, which should be a four digit year.

int Month() const

Returns the month. Values range from 1 to 12.

void SetMonth(int aMonth)

Sets the month from `aMonth`, which should be in the range 1 to 12.

int Day() const

Returns the day of the month. Values range from 1 to 31.

void SetDay(int aDay)

Sets the day of the month from `aDay`.

int Hour() const

Returns the hour according to the 24 hour clock. Values range from 0 to 23.

void SetHour(int aHour)

Sets the hour from `aHour` based on the 24-hour clock. `aHour` should be in the range 0 to 23.

int Minute() const

Returns the minute. Values range from 0 to 59.

void SetMinute(int aMinute)

Sets the minute from `aMinute`, which should be in the range 0 to 59.

int Second() const

Returns the second. Values range from 0 to 59.

void SetSecond(int aSecond)

Sets the second from `aSecond`, which should be in the range 0 to 59.

int Zone() const

Returns the time zone as the diffence in minutes between local time and Coordinated Universal Time (UTC or GMT).

void SetZone(int aZone)

Sets the time zone from `aZone`, interpreted as the time difference in minutes between local time and Coordinated Universal Time (UTC, or GMT).

static void SetDefaultZone(int aZone)

Sets the default time zone. `aZone` should be the time difference in minutes between local time and Coordinated Universal Time (UTC, or GMT). The value is used to set the time zone for any objects created using the default constructor.

static DwDateTime* NewDateTime(const DwString&, DwMessageComponent*)

Creates a new `DwDateTime` object on the free store. If the static data member `sNewDateTime` is `NULL`, this member function will create a new `DwDateTime` and return it. Otherwise, `NewDateTime()` will call the user-supplied function pointed to by `sNewDateTime`, which is assumed to return an object from a class derived from `DwDateTime`, and return that object.

virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const

This virtual function, inherited from `DwMessageComponent`, prints debugging information about this object to `aStrm`.

This member function is available only in the debug version of the library.

virtual void CheckInvariants() const

Aborts if one of the invariants of the object fails. Use this member function to track down bugs.

This member function is available only in the debug version of the library.

## Public Data Members

static DwDateTime* (*sNewDateTime)(const DwString&, DwMessageComponent*)

If `sNewDateTime` is not `NULL`, it is assumed to point to a user-supplied function that returns an object from a class derived from `DwDateTime`.

## Protected Member Functions

void _FromUnixTime(DwUint32 aTime)

Like `FromUnixTime()`, but doesn't set the is-modified flag.

void _FromCalendarTime(time_t aTime)

Like `FromCalendarTime()`, but doesn't set the is-modified flag.