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 license
   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.
 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