DwDateTime Man Page

## NAME

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

## SYNOPSIS

    class DW_CORE_EXPORT DwDateTime : public DwFieldBody {

    public:

        DwDateTime(DwBool aConvertToLocal=DwTrue);
        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, DwBool aConvertToLocal=DwTrue);
        time_t AsCalendarTime() const;
        void FromCalendarTime(time_t aTime, DwBool aConvertToLocal=DwTrue);
        void SetValuesLocal(int aYear, int aMonth, int aDay, int aHour,
            int aMinute, int aSecond);
        void SetValuesLiteral(int aYear, int aMonth, int aDay, int aHour,
            int aMinute, int aSecond, int aZoneOffset, const char* aZoneName=0);
        int Year() const;
        int Month() const;
        int Day() const;
        int Hour() const;
        int Minute() const;
        int Second() const;
        int Zone() const;
        const DwString& ZoneName() const;
        int DayOfTheWeek() const;
        static DwDateTime* NewDateTime(const DwString&, DwMessageComponent*);
        static DwDateTime* (*sNewDateTime)(const DwString&, DwMessageComponent*);

    protected:

        void _FromUnixTime(DwUint32 aTime, DwBool aConvertToLocal);
        void _FromCalendarTime(time_t aTime, DwBool aConvertToLocal);
        int      mYear;
        int      mMonth;
        int      mDay;
        int      mHour;
        int      mMinute;
        int      mSecond;
        int      mZone;
        DwString mZoneName;

    public:

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

    protected:

        void _PrintDebugInfo(DW_STD ostream& aStrm) const;
    };

## DESCRIPTION

`DwDatetime` represents an Internet date-time string 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 elements of the date-time.

The primary purpose of `DwDateTime` is to provide access to the elements of a date-time string (the year, month, day, and so on), and not to provide an abstract representation of time. Thus, it may be helpful to think of `DwDateTime` as you would a `struct` `tm` structure from the standard library. This is important, for example, when you use the default constructor to create a new `DwDateTime` object. In this situation, you can specify an optional parameter to create the object in UTC time, or you can accept the default to create the object in local time. It is then the concrete representation of date and time, with respect to a particular time zone, that is maintained internally, and not some more abstract notion of time.

The use of `DwDateTime` is best explained by considering the following use cases.

`DwDateTime` parses Internet date-time strings. When a MIME message is received, perhaps from a remote source, you can use the inherited member function `DwMessageComponent::FromString()`, or the `DwDateTime(const DwString&)` constructor, to set the string representation of the `DwDateTime` object. Then call the virtual function `Parse()` to parse the string representation. Finally, call the member functions `Year()`, `Month()`, and so on, to access the parsed elements of the date-time string.

`DwDateTime` assembles Internet date-time strings. Use the default constructor to create a new `DwDateTime` object with the current date and time. Call one of the member functions `SetValuesLocal()` or `SetValuesLiteral()` to set the year, month, and so on, from actual values. Then call the virtual function `Assemble()` to create the date-time string. Finally, call the inherited member function `DwMessageComponent::AsString()` to retrieve the date-time string.

`DwDateTime` converts to and from a scalar date and time. On a Unix system, or for portability with other Unix software, call the member functions `FromUnixTime()` or `AsUnixTime()` to convert from or to a ``Unix time,'' defined as the number of seconds elapsed since 1 Jan 1970 00:00:00 UTC. Alternatively, or for portability at the source code level, call the member functions `FromCalendarTime()` or `AsCalendarTime()` to convert from or to a ``calendar time,'' a value that is commensurate with the output from the `time()` function of the standard library. By converting to a scalar representation of the date and time, MIME++ makes it easy for you to compare two different dates.

Note: It is possible that `DwDateTime` will encounter an error while parsing a date-time string. When this happens, throwing an exception is not a wise way to proceed, since in most cases higher level operations would also have to terminate before the library user's code could deal with the exception. What actually happens, is that `DwDateTime` ``recovers'' from the error by setting the date and time to 1 Jan 1970 00:00:00 UTC. To easily check whether a parse operation completed successfully, you can call `AsUnixTime()` and examine the return value. A value of zero indicates that the parsing operation failed; any other value indicates it succeeded.

## Public Member Functions

DwDateTime(DwBool aConvertToLocal=DwTrue)
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. If `aConvertToLocal` is true, then the `DwDateTime` object creates its internal representation in local time; otherwise, it creates it in UTC time.

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, DwBool aConvertToLocal=DwTrue)

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

If `aConvertToLocal` is true, then the `DwDateTime` object creates its internal representation in local time; otherwise, it creates it in UTC time.

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()`.

void FromCalendarTime(time_t aTime, DwBool aConvertToLocal=DwTrue)

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()`.

If `aConvertToLocal` is true, then the `DwDateTime` object creates its internal representation in local time; otherwise, it creates it in UTC time.

void SetValuesLocal(int aYear, int aMonth, int aDay, int aHour, int aMinute, int aSecond)

Sets the values of the `DwDateTime` object as specified. Time zone information will be obtained from the system, based on the values specified.

See also `SetValuesLiteral()`.

void SetValuesLiteral(int aYear, int aMonth, int aDay, int aHour, int aMinute, int aSecond, int aZoneOffset, const char* aZoneName=0)

Sets the values of the `DwDateTime` object as specified. Unlike `SetValuesLocal()`, this function will not obtain any time zone information from the system, nor will it do any conversion. In other words, all values are taken to be literal, including the time zone offset.

`aZoneOffset` is the offset in minutes from Coordinated Universal Time (UTC or GMT). For example, the correct value for US Eastern Standard Time is -300, since 12:00 UTC equals 7:00 EST, a difference of 300 minutes. `aZoneName`, if it is not NULL, is the name of the time zone (for example, EST).

The allowed values for the parameters are as listed below:

    aYear      1970 -
    aMonth        1 -  12
    aDay          1 -  31
    aHour         0 -  23
    aMinute       0 -  59
    aSecond       0 -  59
    aZone      -720 - 720

int Year() const

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

int Month() const

Returns the month. Values range from 1 to 12.

int Day() const

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

int Hour() const

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

int Minute() const

Returns the minute. Values range from 0 to 59.

int Second() const

Returns the second. Values range from 0 to 59.

int Zone() const

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

const DwString& ZoneName() const

Returns the name of the time zone, if it's available; otherwise, returns an empty string. The time zone name is not part of the RFC-822 date-time string. Some implementations, however, include the time zone name in a comment, like so:

    Sat, 28 Feb 1998 10:00:00 -0500 (EST)

The above date is perfectly valid under RFC-822/RFC-1123; including the time zone name is slightly more readable to humans.

MIME++ will include the time zone name in a comment if the time zone name is set in the `DwDateTime` object or if it can be obtained from the system. It will infer a time zone name if a date-time string that it parses has a comment at the end.

int DayOfTheWeek() const

Returns an integer indicating the day of the week. (Sunday is 0. Saturday is 6.) This value is always computed from the other values. The day of the week is a read-only value that cannot be set.

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(DW_STD 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, DwBool aConvertToLocal)

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

void _FromCalendarTime(time_t aTime, DwBool aConvertToLocal)

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