+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: tdate.tex
+%% Purpose: wxDateTime and related classes overview
+%% Author: Vadim Zeitlin
+%% Modified by:
+%% Created: 07.03.00
+%% RCS-ID: $Id$
+%% Copyright: (c) Vadim Zeitlin
+%% Licence: wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Date and time classes overview}\label{wxdatetimeoverview}
+
+Classes: \helpref{wxDateTime}{wxdatetime}, \helpref{wxDateSpan}{wxdatespan}, \helpref{wxTimeSpan}, \helpref{wxtimespan}, \helpref{wxCalendarCtrl}{wxcalendarctrl}
+
+\subsection{Introduction}
+
+wxWindows provides a set of powerful classes to work with dates and times. Some
+of the supported features of \helpref{wxDateTime}{wxdatetime} class are:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\item{Wide range}{The range of supported dates goes from about 4714 B.C. to
+some 480 million years in the future.}
+\item{Precision}{Not using floating point calculations anywhere ensures that
+the date calculations don't suffer from rounding errors.}
+\item{Many features}{Not only all usual calculations with dates are supported,
+but also more exotic week and year day calculations, work day testing, standard
+astronomical functions, conversion to and from strings in either strict or free
+format.}
+\item{Efficiency}{Objects of wxDateTime are small (8 bytes) and working with
+them is fast}
+\end{twocollist}
+
+\subsection{All date/time classes at a glance}
+
+There are 3 main classes declared in {\tt <wx/datetime.h>}: except
+\helpref{wxDateTime}{wxdatetime} itself which represents an absolute
+moment in the time, there are also two classes -
+\helpref{wxTimeSpan}{wxtimespan} and \helpref{wxDateSpan}{wxdatespan} which
+represent the intervals of time.
+
+There are also helper classes which are used together with wxDateTime:
+\helpref{wxDateTimeHolidayAuthority}{wxdatetimeholidayauthority} which is used
+to determine whether a given date is a holiday or not and
+\helpref{wxDateTimeWorkDays}{wxdatetimeworkdays} which is a derivation of this
+class for which (only) Saturdays and Sundays are the holidays.
+
+Finally, in other parts of this manual you may find mentions of wxDate and
+wxTime classes. \helpref{These classes}{tdatecompatibility} are obsolete and
+superseded by wxDateTime.
+
+\subsection{wxDateTime characteristics}
+
+\helpref{wxDateTime}{wxdatetime} stores the time as a signed number of
+milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
+however this is not visible to the class users (in particular, dates prior to
+the Epoch are handled just as well (or as bad) as the dates after it). But it
+does mean that the best resolution which can be achieved with this class is 1
+millisecond.
+
+The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
+integer. The resulting range of supported dates is thus approximatively 580
+million years, but due to the current limitations in the Gregorian calendar
+support, only dates from Nov 24, 4714BC are supported (this is subject to
+change if there is sufficient interest in doing it).
+
+Finally, the internal representation is time zone independent (always in GMT)
+and the time zones only come into play when a date is broken into
+year/month/day components. See more about \helpref{timezones}{tdatetimezones}
+below.
+
+Currently, the only supported calendar is Gregorian one (which is used even
+for the dates prior to the historic introduction of this calendar which was
+first done on Oct 15, 1582 but is, generally speaking, country, and even
+region, dependent). Future versions will probably have Julian calendar support
+as well and support for other calendars (Maya, Hebrew, Chinese...) is not
+ruled out.
+
+\subsection{Difference between wxDateSpan and wxTimeSpan}
+
+While there is only one logical way to represent an absolute moment in the
+time (and hence only one wxDateTime class), there are at least two methods to
+describe a time interval.
+
+First, there is the direct and self-explaining way implemented by
+\helpref{wxTimeSpan}{wxtimespan}: it is just a difference in milliseconds
+between two moments in the time. Adding and substracting such interval to
+wxDateTime is always well-defined and is a fast operation.
+
+But in the daily life other, calendar-dependent time interval specifications are
+used. For example, `one month later' is commonly used. However, it is clear
+that this is not the same as wxTimeSpan of $60*60*24*31$ seconds because `one
+month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
+the year is leap or not).
+
+This is why there is another class for representing such intervals called
+\helpref{wxDateSpan}{wxdatespan}. It handles this sort of operations in the
+most natural way possible, but note that manipulating with thei ntervals of
+this kind is not always well-defined. Consider, for example, Jan 31 + `1
+month': this will give Feb 28 (or 29), i.e. the last day of February and not
+the non-existing Feb 31. Of course, this is what is usually wanted, but you
+still might be surprized to notice that now substracting back the same
+interval from Feb 28 will result in Jan 28 and {\bf not} Jan 31 we started
+with!
+
+So, unless you plan to implement some kind of natural language parsing in the
+program, you should probably use wxTimeSpan instead of wxDateSpan (which is
+also more efficient). However, wxDateSpan may be very useful in situations
+when you do need to understand what does `in a month' mean (of course, it is
+just {\tt wxDateTime::Now() + wxDateSpan::Month()}).
+
+\subsection{Date arithmetics}
+
+Many different operations may be performed with the dates, however not all of
+them make sense. For example, multiplying date by a number is an invalid
+operation, even though multiplying either of time span classes by a number is
+perfectly valid.
+
+Here is what can be done:
+
+\begin{twocollist}
+\item{{\bf Addition}}{a wxTimeSpan or wxDateSpan can be added to wxDateTime
+resulting in a new wxDateTime object and also 2 objects of the same span class
+can be added together giving another object of the smae class.}
+\item{{\bf Substraction}}{the same types of operations as above are
+allowed and, additionally, a difference between two wxDateTime objects can be
+taken and this will yield wxTimeSpan.}
+\item{{\bf Multiplication}}{a wxTimeSpan or wxDateSpan object can be
+multiplied by an integer number resulting in an object of the same type.}
+\item{{\bf Unary minus}}{a wxTimeSpan or wxDateSpan object may finally be
+negated giving an interval of the same magnitude but of opposite time
+direction.}
+\end{twocollist}
+
+For all these operations there are corresponding global (overloaded) operators
+and also member functions which are synonyms for them: Add(), Substract() and
+Multiply(). Unary minus as well as composite assignment operations (like $+=$)
+are only implemented as members and Neg() is the synonym for unary minus.
+
+\subsection{Time zone considerations}\label{tdatetimezones}
+
+Although the time is always stored internally in GMT, you will usually work in
+the local time zone. Because of this, all wxDateTime constructors and setters
+which take the broken down date assume that these values are for the local
+time zone. Thus, {\tt wxDateTime(1, wxDateTime::Jan, 1970)} will not
+correspond to the wxDateTime Epoch unless you happen to live in the UK.
+
+All methods returning the date components (year, month, day, hour, minute,
+second...) will also return the correct values for the local time zone by
+default, so, generally, doing the natural things will lead to natural and
+correct results.
+
+If you only want to do this, you may safely skip the rest of this section.
+However, if you want to work with different time zones, you should read it to
+the end.
+
+In this (rare) case, you are still limited to the local time zone when
+constructing wxDateTime objects, i.e. there is no way to construct a
+wxDateTime corresponding to the given date in, say, Pacific Standard Time.
+To do it, you will need to call \helpref{ToTimezone}{wxdatetimetotimezone} or
+\helpref{MakeTimezone}{wxdatetimemaketimezone} methods to adjust the date for
+the target time zone. There are also special versions of these functions
+\helpref{ToGMT}{wxdatetimetogmt} and \helpref{MakeGMT}{wxdatetimemakegmt} for
+the most common case - when the date should be constructed in GMT.
+
+You also can just retrieve the value for some time zone without converting the
+obejct to it first. For this you may pass TimeZone argument to any of the
+methods which are affected by the time zone (all methods getting date
+components and the date formatting ones, for example). In particular, the
+Format() family of methods accepts a TimeZone parameter and this allows to
+simply print time in any time zone.
+
+To see how to do it, the last issue to address is how to construct a TimeZone
+object which must be passed to all these methods. First of all, you may construct
+it manually by specifying the time zone offset in seconds from GMT, but
+usually you will just use one of the \helpref{symbolic time zone
+names}{wxdatetimetimezones} and let the conversion constructor do the job.
+I.e.. you would just write
+
+\begin{verbatim}
+wxDateTime dt(...whatever...);
+printf("The time is %s in local time zone", dt.FormatTime().c_str());
+printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
+\end{verbatim}
+
+\subsection{Daylight saving time (DST)}
+
+DST (a.k.a. `summer time') handling is always a delicate task which is better
+left to the operating system which is supposed to be configured by the
+administrator to behave correctly. Unfortunately, when doing calculations with
+date outside of the range supported by the standard library, we are forced to
+deal with these issues ourselves.
+
+Several functions are provided to calculate the beginning and end of DST in
+the given year and to determine whether it is in effect at the given moment or
+not, but they should not be considered as absolutely correct because, first of
+all, they only work more or less correctly for only a handful of countries
+(any information about other ones appreciated!) and even for them the rules
+may perfectly well change in the future.
+
+The time zone handling \helpref{methods}{tdatetimezones} use these functions
+too, so they are subject to the same limitations.
+
+% is this really needed? \subsection{Conversion to/from text}
+
+\subsection{Compatibility}\label{tdatecompatibility}
+
+The old classes for date/time manipulations ported from wxWindows version 1.xx
+are still included but are reimplemented in terms of wxDateTime. However, using
+them is strongly discouraged because they have a few quirks/bugs and were not
+`Y2K' compatible.
projects / wxWidgets.git / commitdiff
