docs/latex/wx/tdate.tex

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