Storing and Processing Dates and Times

wxWidgets provides a comprehensive wxDateTime class for representing date and time information with many operations such as formatting, time zones, date and time arithmetic, and more. Static functions provide information such as the current date and time, as well as queries such as whether a given year is a leap year. Note that the wxDateTime class is the appropriate class to use even when you need to store only date or time information. Helper classes wxTimeSpan and wxDateSpan provide convenient ways for modifying an existing wxDateTime object.

wxDateTime

The wxDateTime class has too many methods to include in a concise discussion; the complete API reference is available in the wxWidgets documentation. What is presented here is an overview of the most frequently used wxDateTime methods and operations.

Note that although time is always stored internally in Greenwich Mean Time (GMT), you will usually work in the local time zone. Because of this, all wxDateTime constructors and modifiers that compose a date or time from components (for example hours, minutes, and seconds) assume that these values are for the local time zone. All methods returning date or time components (month, day, hour, minute, second, and so on) will also return the correct values for the local time zone by default; no effort is required to get correct results for your time zone. If you want to manipulate time zones, please refer to the documentation.

wxDateTime Constructors and Modifiers

wxDateTime objects can be constructed from Unix timestamps, time-only information, date-only information, or complete date and time information. For each constructor, there is a corresponding Set method that modifies an existing object to have the specified date or time. There are also individual modifiers such as SetMonth or SetHour that change just one component of the date or time.

wxDateTime(time_t) constructs an object with the date and time set according to the specified Unix timestamp.

wxDateTime(const struct tm&) constructs an object using the data from the C standard tm structure.

wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0, wxDateTime_t second = 0, wxDateTime_t millisec = 0) constructs an object based on the specified time information.

wxDateTime(wxDateTime_t day, Month month = Inv_Month, int year = Inv_Year, wxDateTime_t hour = 0, wxDateTime_t minute = 0, wxDateTime_t second = 0, wxDateTime_t millisec = 0) constructs an object with the specified date and time information.

wxDateTime Accessors

The accessors for wxDateTime are mostly self-explanatory: GetYear, GetMonth, Getday, GetWeekDay, GetHour, GetMinute, GetSecond, GetMillisecond, GeTDayOfYear, GetWeekOfYear, GetWeekOfMonth, and GetYearDay. wxDateTime also provides the following:

• GetTicks returns the date and time in Unix timestamp format (seconds since January 1, 1970 at midnight).

• IsValid returns whether or not the object is in a valid state (the object could have been constructed but never given a date or time).

Getting the Current Time

wxDateTime provides two static methods for retrieving the current time:

• wxDateTime::Now creates a wxDateTime object with the current time, accurate to up the second.

• wxDateTime::UNow creates a wxDateTime object with the current time, including milliseconds.

Parsing and Formatting Dates

The functions in this section convert wxDateTime objects to and from text. The conversions to text are mostly trivial: you can use the default date and time representations for the current locale (FormatDate and FormatTime), use the international standard representation defined by ISO 8601 (FormatISODate and FormatISOTime), or specify any format at all by using Format directly.

The conversions from text are more interesting because there are many more possibilities. The simplest cases can be taken care of with ParseFormat, which can parse any date in a specified (rigid) format. ParseRfc822Date parses dates using the format from RFC 822 that defines the format of email messages on the Internet.

The most interesting functions are ParseTime, ParseDate, and ParseDateTime, which try to parse the date and/or time in "free" format, allowing them to be specified in a variety of ways. These functions can be used to parse user input that is not bound by any predefined format. As an example, ParseDateTime can parse strings such as "tomorrow", "March first", and even "next Sunday".

Date Comparisons

Two wxDateTime objects can easily be compared using one of many available comparison functions. All of these methods return true or false.

The following methods all make comparisons to one other wxDateTime object: IsEqualTo, IsEarlierThan, IsLaterThan, IsSameDate, and IsSameTime.

The following methods all make comparisons using two other wxDateTime objects: IsStrictlyBetween and IsBetween. The difference between these two is that IsStrictlyBetween would return false if the wxDateObject in question exactly equaled one of the range extremes, whereas IsBetween would return TRue.

Date Arithmetic

wxWidgets provides two very robust classes for performing arithmetic on wxDateTime objects: wxTimeSpan and wxDateSpan. wxTimeSpan is simply a difference in milliseconds and always gives fast, predictable results. On the other hand, time has larger meaningful units, such as weeks or months. wxDateSpan handles these operations in the most natural way possible, but note that manipulating intervals of this kind is not always well-defined. For example, Jan 31 plus one month will give Feb 28 (or 29), the last day of February, and not the non-existent Feb 31. Of course, this is what is usually wanted, but you still might be surprised that subtracting back the same interval from Feb 28 will result in Jan 28 (not the January 31 that we started with).

Many different operations may be performed with the dates, but not all combinations of them make sense. For example, multiplying a date by a number is an invalid operation, even though multiplying either of the time span classes by a number is perfectly valid.

• Addition: A wxTimeSpan or wxDateSpan can be added to wxDateTime resulting in a new wxDateTime object. Also, two objects of the same span class can be added together, resulting in another object of the same class.

• Subtraction: The same operations as addition are valid for subtraction. Additionally, a difference between two wxDateTime objects can be taken and will return a wxTimeSpan object.

• Multiplication: A wxTimeSpan or wxDateSpan object can be multiplied by an integer number, resulting in an object of the same type.

• Unary minus: A wxTimeSpan or wxDateSpan object may be negated, resulting in an interval of the same magnitude but in the opposite time direction.

The following small code example demonstrates how to use wxDateSpan and wxTimeSpan to change the time stored in a wxDateTime object. See the wxWidgets manual for a complete list of available methods.

 void TimeTests() {     // Get the current day and time     wxDateTime DT1 = wxDateTime::Now();     // A span of 2 weeks and 1 day, or 15 days     wxDateSpan Span1(0, 0, 2, 1);     // Substract 15 days from today     wxDateTime DT2 = DT1 - Span1;     // Static creation of a one-day difference     wxDateSpan Span2 = wxDateSpan::Day();     // Span 3 will now be 14 days     wxDateSpan Span3 = Span1 - Span2;     // 0 days (the span is defined as 2 weeks)     int Days = Span3.GetDays();     // 14 days (2 weeks)     int TotalDays = Span3.GetTotalDays();     // 2 weeks into the past     wxDateSpan Span4 = -Span3;     // A span of 3 months     wxDateSpan Span5 = wxDateSpan::Month() * 3;     // 10 hours, 5 minutes and 6 seconds     wxTimeSpan Span6(10, 5, 6, 0);     // Add the specified amount of time to DT2     wxDateTime DT3 = DT2 + Span6;     // Span7 is 3 times longer than Span6, but in the past     wxTimeSpan Span7 = (-Span6) * 3;     // SpanNeg will be true, the span is negative (in the past)     bool SpanNeg = Span7.IsNegative();     // Static creation of a span of one hour     wxTimeSpan Span8 = wxTimeSpan::Hour();     // One hour is not longer than 30+ hours (uses absolutes)     bool Longer = Span8.IsLongerThan(Span7); }