Inheritance diagram for DateTime:
The use of DateTime is best explained by considering the following use cases.
DateTime parses Internet date-time strings. When a MIME message is received, perhaps from a remote source, you can use the inherited member function Node::setString(const String&), or the DateTime(const String&) constructor, to set the string representation of the DateTime 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.
DateTime assembles Internet date-time strings. Use the default constructor to create a new DateTime object with a null date-time. Call one of the member functions setValuesLocal() or setValuesLiteral() to set the year, month, day, hour, minute, second, and zone with the desired values. Alternatively, you can set the values for the date-time from a calendar time (returned by the time() function in the C library), using the fromCalendarTime() member function. Then call the virtual function assemble() to create the string representation. Finally, call the inherited member function Node::getString() to get the string representation.
DateTime 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, Hunny MIME++ makes it easy for you to compare two different dates.
Note: It is possible that DateTime 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 DateTime "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 | |
| DateTime () | |
| Default constructor. | |
| DateTime (const DateTime &other) | |
| Copy constructor. | |
| DateTime (const String &str, Node *parent=0) | |
| Constructor that takes an initial string and parent node. | |
| virtual | ~DateTime () |
| Destructor. | |
| const DateTime & | operator= (const DateTime &other) |
| Assignment operator. | |
| virtual void | parse () |
| Parses the string representation. | |
| virtual void | assemble () |
| Assembles the string representation. | |
| virtual Node * | clone () const |
| Creates a copy of this object. | |
| int32_t | asUnixTime () const |
| Gets the date and time as a UNIX (POSIX) time. | |
| void | fromUnixTime (int32_t time, bool convertToLocal=true) |
| Sets the date and time from a UNIX (POSIX) time. | |
| time_t | asCalendarTime () const |
| Gets the date and time as a system-dependent calendar time. | |
| void | fromCalendarTime (int32_t time, bool convertToLocal=true) |
| Sets the date and time from a system-dependent calendar time. | |
| void | setValuesLocal (int year, int month, int day, int hour, int minute, int second) |
| Sets values, excluding time zone. | |
| void | setValuesLiteral (int year, int month, int day, int hour, int minute, int second, int zoneOffset, const char *zoneName=0) |
| Sets values, including time zone. | |
| int | year () const |
| Gets the year. | |
| int | month () const |
| Gets the month. | |
| int | day () const |
| Gets the day of the month. | |
| int | hour () const |
| Gets the hour. | |
| int | minute () const |
| Gets the minute. | |
| int | second () const |
| Gets the second. | |
| int | zone () const |
| Gets the time zone. | |
| const String & | zoneName () const |
| Gets the name of the time zone. | |
| int | dayOfTheWeek () const |
| Gets the day of the week. | |
Static Public Member Functions | |
| DateTime * | newDateTime () |
| Creates a new instance. | |
Static Public Attributes | |
| DateTime *(* | sNewDateTime )() |
| Provides a class factory hook. | |
Protected Member Functions | |
| void | _fromUnixTime (int32_t time, bool convertToLocal) |
| Sets the date and time from a UNIX (POSIX) time. | |
| void | _fromCalendarTime (int32_t time, bool convertToLocal) |
| Sets the date and time from a system-dependent calendar time. | |
|
|
This constructor sets the DateTime object's string representation to the empty string and sets its parent node to NULL. The date-time value is set to the null value, defined as the date 1 Jan 1970 00:00:00 UTC. |
|
|
This constructor performs a deep copy of its argument. The parent node of the new DateTime object is set to NULL.
|
|
||||||||||||
|
This constructor sets the DateTime object's string representation to str and sets its parent node to parent. The date-time value is set to the null value, defined as the date 1 Jan 1970 00:00:00 UTC. Normally, you call the virtual function parse() immediately after this constructor to create the broken-down representation.
|
|
|
Destructor |
|
||||||||||||
|
Same as fromCalendarTime(), but does not set the is-modified flag.
|
|
||||||||||||
|
Same as fromUnixTime(), but does not set the is-modified flag.
|
|
|
Gets 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().
|
|
|
This virtual function, inherited from Node, executes the assemble operation for DateTime objects. The assemble operation creates or updates the string representation from the broken-down representation. For DateTime objects, the assemble operation builds the string representation from the year, month, day, hour, minute, second, and zone. You should call this member function after you set or modify the year, month, day, hour, minute, second, or zone, and before you retrieve the string representation. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Gets the date and time as a UNIX (POSIX) time, defined as the number of seconds elapsed since 1 Jan 1970 00:00:00 UTC.
|
|
|
This virtual function, inherited from Node, creates a new DateTime object that has the same value as this DateTime object. The parent node of the new DateTime object is set to NULL.
Reimplemented from FieldBody. |
|
|
Gets the day of the month. Values range from 1 to 31.
|
|
|
Gets the day of the week. Values range from 0 to 6, with 0 = Sunday. This value is always computed from the other values. The day of the week is a read-only value that cannot be set.
|
|
||||||||||||
|
Sets the date and time from time, 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 convertToLocal is true, then the DateTime object creates the internal representation in local time; otherwise, it creates the internal representation in UTC time.
|
|
||||||||||||
|
Sets the date and time from time, interpreted as the number of of seconds elapsed since 1 Jan 1970 00:00:00 UTC. If convertToLocal is true, then the DateTime object creates the internal representation in local time; otherwise, it creates the internal representation in UTC time.
|
|
|
Gets the hour according to the 24 hour clock. Values range from 0 to 23.
|
|
|
Gets the minute. Values range from 0 to 59.
|
|
|
Gets the month. Values range from 1 to 12, with 1 = January.
|
|
|
Creates a new DateTime object. If the static data member sNewDateTime is NULL, this member function creates a new DateTime object and returns it. Otherwise, newDateTime() calls the user-supplied function that sNewDateTime points to and returns the object created by that function.
|
|
|
Performs a deep copy of its argument. The parent node of this DateTime object is not changed.
|
|
|
This virtual function, inherited from Node, executes the parse operation for DateTime objects. The parse operation creates or updates the broken-down representation from the string representation. For DateTime objects, the parse operation parses the string representation to get the values of the year, month, day, hour, minute, second, and time zone. You should call this member function after you set or modify the string representation, and before you retrieve the year, month, day, hour, minute second, zone, or zone name. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Gets the second. In accordance with RFC 2822, values range from 0 to 60.
|
|
||||||||||||||||||||||||||||||||||||
|
Sets the date-time value as specified. Use this member function to create the internal date-time representation in any time zone. The values are used "as is" without any additional interpretation. zoneOffset is the offset in minutes from Coordinated Universal Time (UTC). For example, the correct value for US Eastern Standard Time (e.g. New York City) is -300, since 12:00 UTC equals 7:00 EST, a difference of 300 minutes. zoneName, if it is not NULL, is the name of the time zone (for example, EST).
|
|
||||||||||||||||||||||||||||
|
Sets the date-time value as specified, assuming local time. Use this member function to create the internal date-time representation in local time. Time zone information is obtained from the local system, based on the values specified. Note that when the local system is set up to recognize daylight time, there is an ambiguity during the overlap time period that occurs when the local time clock is set back. During this overlap period, it is impossible to determine whether the time zone offset should be the standard zone offset or the daylight time zone offset. This ambiguity is probably not a problem for most applications. If it is a problem, then the work around is to use SetValuesLiteral() to specify the precise time zone offset.
|
|
|
Gets the four digit year, e.g. 1997.
|
|
|
Gets the time zone as the difference in minutes between local time and Coordinated Universal Time (UTC). For example, for US Eastern Standard Time (e.g. New York City), the time zone difference would be -300.
|
|
|
Gets 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 2822 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 2822; including the time zone name is slightly more readable to humans. Hunny MIME++ will include the time zone name in a comment if the time zone name is set in the DateTime 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 immediately following the zone offset. Note that using a comment for the time zone name is non-standard. Use at your own risk.
|
|
|
If sNewDateTime is not NULL, it must point to a user-supplied function that returns a new instance of a subclass of DateTime.
|
Copyright © 2001-2007 Hunny Software, Inc. All rights reserved.