docs/doxygen/overviews/datetime.h

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