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