docs/doxygen/overviews/datetime.h

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