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; };
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.
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.
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.
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.