Commit | Line | Data |
---|---|---|
15b6757b | 1 | ///////////////////////////////////////////////////////////////////////////// |
d54cf7ff | 2 | // Name: datetime.h |
15b6757b FM |
3 | // Purpose: topic overview |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
880efa2a | 9 | /** |
36c9828f | 10 | |
928f1a07 | 11 | @page overview_datetime Date and Time |
36c9828f | 12 | |
928f1a07 | 13 | Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl |
36c9828f | 14 | |
928f1a07 FM |
15 | @li @ref overview_datetime_introduction |
16 | @li @ref overview_datetime_classes | |
17 | @li @ref overview_datetime_characteristics | |
18 | @li @ref overview_datetime_timespandiff | |
19 | @li @ref overview_datetime_arithmetics | |
20 | @li @ref overview_datetime_timezones | |
21 | @li @ref overview_datetime_dst | |
22 | @li @ref overview_datetime_holidays | |
23 | @li @ref overview_datetime_compat | |
36c9828f FM |
24 | |
25 | ||
928f1a07 | 26 | <hr> |
36c9828f | 27 | |
36c9828f | 28 | |
928f1a07 | 29 | @section overview_datetime_introduction Introduction |
36c9828f | 30 | |
928f1a07 FM |
31 | wxWidgets provides a set of powerful classes to work with dates and times. Some |
32 | of the supported features of wxDateTime class are: | |
36c9828f | 33 | |
928f1a07 FM |
34 | @li Wide range: the range of supported dates goes from about 4714 B.C. to |
35 | some 480 million years in the future. | |
36c9828f | 36 | |
928f1a07 FM |
37 | @li Precision: not using floating point calculations anywhere ensures that |
38 | the date calculations don't suffer from rounding errors. | |
36c9828f | 39 | |
928f1a07 FM |
40 | @li Many features: not only all usual calculations with dates are supported, |
41 | but also more exotic week and year day calculations, work day testing, standard | |
42 | astronomical functions, conversion to and from strings in either strict or free | |
d54cf7ff | 43 | format. |
36c9828f | 44 | |
928f1a07 FM |
45 | @li Efficiency: objects of wxDateTime are small (8 bytes) and working with |
46 | them is fast | |
36c9828f FM |
47 | |
48 | ||
49 | ||
928f1a07 | 50 | @section overview_datetime_classes All date/time classes at a glance |
36c9828f | 51 | |
928f1a07 FM |
52 | There are 3 main classes declared in @c wx/datetime.h: except wxDateTime itself |
53 | which represents an absolute moment in time, there are also two classes - | |
54 | wxTimeSpan and wxDateSpan - which represent the intervals of time. | |
36c9828f | 55 | |
928f1a07 FM |
56 | There are also helper classes which are used together with wxDateTime: |
57 | wxDateTimeHolidayAuthority which is used to determine whether a given date | |
58 | is a holiday or not and wxDateTimeWorkDays which is a derivation of this | |
59 | class for which (only) Saturdays and Sundays are the holidays. See more about | |
60 | these classes in the discussion of the holidays (see @ref overview_datetime_holidays). | |
d54cf7ff | 61 | |
928f1a07 FM |
62 | Finally, in other parts of this manual you may find mentions of wxDate and |
63 | wxTime classes. @ref overview_datetime_compat are obsolete and | |
64 | superseded by wxDateTime. | |
36c9828f | 65 | |
d54cf7ff FM |
66 | |
67 | ||
928f1a07 | 68 | @section overview_datetime_characteristics wxDateTime characteristics |
36c9828f | 69 | |
928f1a07 FM |
70 | wxDateTime stores the time as a signed number of |
71 | milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - | |
72 | however this is not visible to the class users (in particular, dates prior to | |
73 | the Epoch are handled just as well (or as bad) as the dates after it). But it | |
74 | does mean that the best resolution which can be achieved with this class is 1 | |
75 | millisecond. | |
d54cf7ff | 76 | |
928f1a07 FM |
77 | The size of wxDateTime object is 8 bytes because it is represented as a 64 bit |
78 | integer. The resulting range of supported dates is thus approximatively 580 | |
79 | million years, but due to the current limitations in the Gregorian calendar | |
80 | support, only dates from Nov 24, 4714BC are supported (this is subject to | |
81 | change if there is sufficient interest in doing it). | |
d54cf7ff | 82 | |
928f1a07 FM |
83 | Finally, the internal representation is time zone independent (always in GMT) |
84 | and the time zones only come into play when a date is broken into | |
85 | year/month/day components. See more about timezones below | |
86 | (see @ref overview_datetime_timezones). | |
d54cf7ff | 87 | |
928f1a07 FM |
88 | Currently, the only supported calendar is Gregorian one (which is used even |
89 | for the dates prior to the historic introduction of this calendar which was | |
90 | first done on Oct 15, 1582 but is, generally speaking, country, and even | |
91 | region, dependent). Future versions will probably have Julian calendar support | |
92 | as well and support for other calendars (Maya, Hebrew, Chinese...) is not | |
93 | ruled out. | |
36c9828f | 94 | |
d54cf7ff FM |
95 | |
96 | ||
928f1a07 | 97 | @section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan |
36c9828f | 98 | |
928f1a07 FM |
99 | While there is only one logical way to represent an absolute moment in the |
100 | time (and hence only one wxDateTime class), there are at least two methods to | |
101 | describe a time interval. | |
d54cf7ff | 102 | |
928f1a07 FM |
103 | First, there is the direct and self-explaining way implemented by |
104 | wxTimeSpan: it is just a difference in milliseconds | |
105 | between two moments in time. Adding or subtracting such an interval to | |
106 | wxDateTime is always well-defined and is a fast operation. | |
d54cf7ff | 107 | |
928f1a07 FM |
108 | But in the daily life other, calendar-dependent time interval specifications are |
109 | used. For example, 'one month later' is commonly used. However, it is clear | |
110 | that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one | |
111 | month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether | |
112 | the year is leap or not). | |
d54cf7ff | 113 | |
928f1a07 FM |
114 | This is why there is another class for representing such intervals called |
115 | wxDateSpan. It handles these sort of operations in the | |
116 | most natural way possible, but note that manipulating with intervals of | |
117 | this kind is not always well-defined. Consider, for example, Jan 31 + '1 | |
118 | month': this will give Feb 28 (or 29), i.e. the last day of February and not | |
119 | the non-existent Feb 31. Of course, this is what is usually wanted, but you | |
120 | still might be surprised to notice that now subtracting back the same | |
121 | interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started | |
122 | with! | |
d54cf7ff | 123 | |
928f1a07 FM |
124 | So, unless you plan to implement some kind of natural language parsing in the |
125 | program, you should probably use wxTimeSpan instead of wxDateSpan (which is | |
126 | also more efficient). However, wxDateSpan may be very useful in situations | |
127 | when you do need to understand what 'in a month' means (of course, it is | |
128 | just @c wxDateTime::Now() + wxDateSpan::Month()). | |
36c9828f | 129 | |
d54cf7ff FM |
130 | |
131 | ||
928f1a07 | 132 | @section overview_datetime_arithmetics Date arithmetics |
36c9828f | 133 | |
928f1a07 FM |
134 | Many different operations may be performed with the dates, however not all of |
135 | them make sense. For example, multiplying a date by a number is an invalid | |
136 | operation, even though multiplying either of the time span classes by a number | |
137 | is perfectly valid. | |
36c9828f | 138 | |
928f1a07 | 139 | Here is what can be done: |
36c9828f | 140 | |
928f1a07 FM |
141 | @li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime |
142 | resulting in a new wxDateTime object and also 2 objects of the same span class | |
143 | can be added together giving another object of the same class. | |
36c9828f | 144 | |
928f1a07 FM |
145 | @li @b Subtraction: the same types of operations as above are |
146 | allowed and, additionally, a difference between two wxDateTime objects can be | |
147 | taken and this will yield wxTimeSpan. | |
36c9828f | 148 | |
928f1a07 FM |
149 | @li @b Multiplication: a wxTimeSpan or wxDateSpan object can be |
150 | multiplied by an integer number resulting in an object of the same type. | |
36c9828f | 151 | |
928f1a07 FM |
152 | @li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be |
153 | negated giving an interval of the same magnitude but of opposite time | |
154 | direction. | |
36c9828f | 155 | |
928f1a07 FM |
156 | For all these operations there are corresponding global (overloaded) operators |
157 | and also member functions which are synonyms for them: Add(), Subtract() and | |
158 | Multiply(). Unary minus as well as composite assignment operations (like +=) | |
159 | are only implemented as members and Neg() is the synonym for unary minus. | |
36c9828f | 160 | |
d54cf7ff FM |
161 | |
162 | ||
928f1a07 | 163 | @section overview_datetime_timezones Time zone considerations |
36c9828f | 164 | |
928f1a07 FM |
165 | Although the time is always stored internally in GMT, you will usually work in |
166 | the local time zone. Because of this, all wxDateTime constructors and setters | |
167 | which take the broken down date assume that these values are for the local | |
168 | time zone. Thus, @c wxDateTime(1, wxDateTime::Jan, 1970) will not | |
169 | correspond to the wxDateTime Epoch unless you happen to live in the UK. | |
170 | All methods returning the date components (year, month, day, hour, minute, | |
171 | second...) will also return the correct values for the local time zone by | |
172 | default, so, generally, doing the natural things will lead to natural and | |
173 | correct results. | |
d54cf7ff | 174 | |
928f1a07 FM |
175 | If you only want to do this, you may safely skip the rest of this section. |
176 | However, if you want to work with different time zones, you should read it to | |
177 | the end. | |
d54cf7ff | 178 | |
928f1a07 FM |
179 | In this (rare) case, you are still limited to the local time zone when |
180 | constructing wxDateTime objects, i.e. there is no way to construct a | |
181 | wxDateTime corresponding to the given date in, say, Pacific Standard Time. | |
182 | To do it, you will need to call wxDateTime::ToTimezone or wxDateTime::MakeTimezone | |
183 | methods to adjust the date for the target time zone. There are also special | |
184 | versions of these functions wxDateTime::ToUTC and wxDateTime::MakeUTC for | |
185 | the most common case - when the date should be constructed in UTC. | |
d54cf7ff | 186 | |
928f1a07 FM |
187 | You also can just retrieve the value for some time zone without converting the |
188 | object to it first. For this you may pass TimeZone argument to any of the | |
189 | methods which are affected by the time zone (all methods getting date | |
190 | components and the date formatting ones, for example). In particular, the | |
191 | Format() family of methods accepts a TimeZone parameter and this allows to | |
192 | simply print time in any time zone. | |
d54cf7ff | 193 | |
928f1a07 FM |
194 | To see how to do it, the last issue to address is how to construct a TimeZone |
195 | object which must be passed to all these methods. First of all, you may construct | |
196 | it manually by specifying the time zone offset in seconds from GMT, but | |
197 | usually you will just use one of the @ref overview_datetime and | |
198 | let the conversion constructor do the job. | |
d54cf7ff | 199 | |
928f1a07 | 200 | I.e. you would just write |
36c9828f | 201 | |
928f1a07 FM |
202 | @code |
203 | wxDateTime dt(...whatever...); | |
204 | printf("The time is %s in local time zone", dt.FormatTime().c_str()); | |
205 | printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str()); | |
206 | @endcode | |
36c9828f FM |
207 | |
208 | ||
d54cf7ff | 209 | |
928f1a07 | 210 | @section overview_datetime_dst Daylight saving time (DST) |
36c9828f | 211 | |
928f1a07 FM |
212 | DST (a.k.a. 'summer time') handling is always a delicate task which is better |
213 | left to the operating system which is supposed to be configured by the | |
214 | administrator to behave correctly. Unfortunately, when doing calculations with | |
215 | date outside of the range supported by the standard library, we are forced to | |
216 | deal with these issues ourselves. | |
d54cf7ff | 217 | |
928f1a07 FM |
218 | Several functions are provided to calculate the beginning and end of DST in |
219 | the given year and to determine whether it is in effect at the given moment or | |
220 | not, but they should not be considered as absolutely correct because, first of | |
221 | all, they only work more or less correctly for only a handful of countries | |
222 | (any information about other ones appreciated!) and even for them the rules | |
223 | may perfectly well change in the future. | |
d54cf7ff | 224 | |
928f1a07 FM |
225 | The time zone handling methods (see @ref overview_datetime_timezones) use |
226 | these functions too, so they are subject to the same limitations. | |
36c9828f | 227 | |
d54cf7ff FM |
228 | |
229 | ||
928f1a07 | 230 | @section overview_datetime_holidays wxDateTime and Holidays |
36c9828f | 231 | |
928f1a07 | 232 | @todo WRITE THIS DOC PARAGRAPH. |
36c9828f | 233 | |
d54cf7ff FM |
234 | |
235 | ||
928f1a07 | 236 | @section overview_datetime_compat Compatibility |
36c9828f | 237 | |
928f1a07 FM |
238 | The old classes for date/time manipulations ported from wxWidgets version 1.xx |
239 | are still included but are reimplemented in terms of wxDateTime. However, using | |
240 | them is strongly discouraged because they have a few quirks/bugs and were not | |
241 | 'Y2K' compatible. | |
36c9828f | 242 | |
d54cf7ff | 243 | */ |
36c9828f | 244 |