← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to docs/doxygen/overviews/datetime.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/doxygen/overviews/datetime.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        datetime.h
 
3
// Purpose:     topic overview
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: datetime.h 64940 2010-07-13 13:29:13Z VZ $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/**
 
10
 
 
11
@page overview_datetime Date and Time
 
12
 
 
13
Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
 
14
 
 
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
 
24
 
 
25
 
 
26
<hr>
 
27
 
 
28
 
 
29
@section overview_datetime_introduction Introduction
 
30
 
 
31
wxWidgets provides a set of powerful classes to work with dates and times. Some
 
32
of the supported features of wxDateTime class are:
 
33
 
 
34
@li Wide range: the range of supported dates goes from about 4714 B.C. to
 
35
    some 480 million years in the future.
 
36
 
 
37
@li Precision: not using floating point calculations anywhere ensures that
 
38
    the date calculations don't suffer from rounding errors.
 
39
 
 
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.
 
44
 
 
45
@li Efficiency: objects of wxDateTime are small (8 bytes) and working with
 
46
    them is fast
 
47
 
 
48
 
 
49
 
 
50
@section overview_datetime_classes All date/time classes at a glance
 
51
 
 
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.
 
55
 
 
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).
 
61
 
 
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.
 
65
 
 
66
 
 
67
 
 
68
@section overview_datetime_characteristics wxDateTime characteristics
 
69
 
 
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.
 
76
 
 
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).
 
82
 
 
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).
 
87
 
 
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.
 
94
 
 
95
 
 
96
 
 
97
@section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
 
98
 
 
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.
 
102
 
 
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.
 
107
 
 
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).
 
113
 
 
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!
 
123
 
 
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()).
 
129
 
 
130
 
 
131
 
 
132
@section overview_datetime_arithmetics Date arithmetics
 
133
 
 
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.
 
138
 
 
139
Here is what can be done:
 
140
 
 
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.
 
144
 
 
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.
 
148
 
 
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.
 
151
 
 
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.
 
155
 
 
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.
 
160
 
 
161
 
 
162
 
 
163
@section overview_datetime_timezones Time zone considerations
 
164
 
 
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.
 
174
 
 
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.
 
178
 
 
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.
 
186
 
 
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.
 
193
 
 
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.
 
199
 
 
200
I.e. you would just write
 
201
 
 
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
 
207
 
 
208
 
 
209
 
 
210
@section overview_datetime_dst Daylight saving time (DST)
 
211
 
 
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.
 
217
 
 
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.
 
224
 
 
225
The time zone handling methods (see @ref overview_datetime_timezones) use
 
226
these functions too, so they are subject to the same limitations.
 
227
 
 
228
 
 
229
 
 
230
@section overview_datetime_holidays wxDateTime and Holidays
 
231
 
 
232
@todo WRITE THIS DOC PARAGRAPH.
 
233
 
 
234
 
 
235
 
 
236
@section overview_datetime_compat Compatibility
 
237
 
 
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.
 
242
 
 
243
*/
 
244