]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/datetime.h
More doxygen topic overview cleanup.
[wxWidgets.git] / docs / doxygen / overviews / datetime.h
CommitLineData
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
9/*!
36c9828f 10
d54cf7ff 11 @page overview_datetime Date and time classes overview
36c9828f 12
98ba1eee 13 Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
36c9828f 14
d54cf7ff
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
d54cf7ff 26 <hr>
36c9828f 27
36c9828f 28
d54cf7ff 29 @section overview_datetime_introduction Introduction
36c9828f 30
d54cf7ff 31 wxWidgets provides a set of powerful classes to work with dates and times. Some
98ba1eee 32 of the supported features of wxDateTime class are:
36c9828f 33
d54cf7ff
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
d54cf7ff
FM
37 @li Precision: not using floating point calculations anywhere ensures that
38 the date calculations don't suffer from rounding errors.
36c9828f 39
d54cf7ff
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
43 format.
36c9828f 44
d54cf7ff
FM
45 @li Efficiency: objects of wxDateTime are small (8 bytes) and working with
46 them is fast
36c9828f
FM
47
48
49
d54cf7ff 50 @section overview_datetime_classes All date/time classes at a glance
36c9828f 51
98ba1eee 52 There are 3 main classes declared in @c wx/datetime.h: except wxDateTime itself
d54cf7ff 53 which represents an absolute moment in time, there are also two classes -
98ba1eee 54 wxTimeSpan and wxDateSpan - which represent the intervals of time.
36c9828f 55
36c9828f 56 There are also helper classes which are used together with wxDateTime:
98ba1eee
FM
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
15b6757b 59 class for which (only) Saturdays and Sundays are the holidays. See more about
98ba1eee 60 these classes in the discussion of the holidays (see @ref overview_datetime_holidays).
d54cf7ff 61
15b6757b 62 Finally, in other parts of this manual you may find mentions of wxDate and
d54cf7ff 63 wxTime classes. @ref overview_datetime_compat are obsolete and
15b6757b 64 superseded by wxDateTime.
36c9828f 65
d54cf7ff
FM
66
67
68 @section overview_datetime_characteristics wxDateTime characteristics
36c9828f 69
98ba1eee 70 wxDateTime stores the time as a signed number of
15b6757b
FM
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
15b6757b
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
15b6757b
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
98ba1eee
FM
85 year/month/day components. See more about timezones below
86 (see @ref overview_datetime_timezones).
d54cf7ff 87
15b6757b
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
97 @section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
36c9828f 98
15b6757b
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
36c9828f 103 First, there is the direct and self-explaining way implemented by
98ba1eee 104 wxTimeSpan: it is just a difference in milliseconds
15b6757b
FM
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
15b6757b
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
36c9828f 114 This is why there is another class for representing such intervals called
98ba1eee 115 wxDateSpan. It handles these sort of operations in the
15b6757b
FM
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
15b6757b
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
132 @section overview_datetime_arithmetics Date arithmetics
36c9828f 133
15b6757b
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
d54cf7ff 139 Here is what can be done:
36c9828f 140
d54cf7ff
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
d54cf7ff
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
d54cf7ff
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
d54cf7ff
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
15b6757b
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
163 @section overview_datetime_timezones Time zone considerations
36c9828f 164
15b6757b
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
15b6757b
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
15b6757b
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.
98ba1eee
FM
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
15b6757b
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
15b6757b
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
d54cf7ff 197 usually you will just use one of the @ref overview_datetime and
15b6757b 198 let the conversion constructor do the job.
d54cf7ff 199
15b6757b 200 I.e. you would just write
36c9828f 201
15b6757b
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
FM
209
210 @section overview_datetime_dst Daylight saving time (DST)
36c9828f 211
15b6757b
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
15b6757b
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
98ba1eee
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
230 @section overview_datetime_holidays wxDateTime and Holidays
36c9828f 231
15b6757b 232 TODO.
36c9828f 233
d54cf7ff
FM
234
235
236 @section overview_datetime_compat Compatibility
36c9828f 237
15b6757b
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