another patch bring the docs more up to date (patch 1717776)

[wxWidgets.git] / docs / latex / wx / tdate.tex

diff --git a/docs/latex/wx/tdate.tex b/docs/latex/wx/tdate.tex
index fa232d914da6bd7f5f646cf409313bf902b71b0a..06b14b681fd6ec7ccbe5f35b25d330c1da1d5531 100644 (file)
--- a/docs/latex/wx/tdate.tex
+++ b/docs/latex/wx/tdate.tex
@@ -6,51 +6,52 @@
 %% Created:     07.03.00
 %% RCS-ID:      $Id$
 %% Copyright:   (c) Vadim Zeitlin
 %% Created:     07.03.00
 %% RCS-ID:      $Id$
 %% Copyright:   (c) Vadim Zeitlin

-%% Licence:     wxWindows licence
+%% License:     wxWindows license

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Date and time classes overview}\label{wxdatetimeoverview}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Date and time classes overview}\label{wxdatetimeoverview}
 

-Classes: \helpref{wxDateTime}{wxdatetime}, \helpref{wxDateSpan}{wxdatespan}, \helpref{wxTimeSpan}, \helpref{wxtimespan}, \helpref{wxCalendarCtrl}{wxcalendarctrl}
+Classes: \helpref{wxDateTime}{wxdatetime}, \helpref{wxDateSpan}{wxdatespan}, \helpref{wxTimeSpan}{wxtimespan}, \helpref{wxCalendarCtrl}{wxcalendarctrl}

 
 

-\subsection{Introduction}
+\subsection{Introduction}\label{introductiontowxdatetime}

 
 

-wxWindows provides a set of powerful classes to work with dates and times. Some
+wxWidgets 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
 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
+\twocolitem{Wide range}{The range of supported dates goes from about 4714 B.C. to

 some 480 million years in the future.}
 some 480 million years in the future.}

-\item{Precision}{Not using floating point calculations anywhere ensures that
+\twocolitem{Precision}{Not using floating point calculations anywhere ensures that

 the date calculations don't suffer from rounding errors.}
 the date calculations don't suffer from rounding errors.}

-\item{Many features}{Not only all usual calculations with dates are supported,
+\twocolitem{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.}
 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
+\twocolitem{Efficiency}{Objects of wxDateTime are small (8 bytes) and working with

 them is fast}
 \end{twocollist}
 
 them is fast}
 \end{twocollist}
 

-\subsection{All date/time classes at a glance}
+\subsection{All date/time classes at a glance}\label{alldatetimeclasses}

 
 There are 3 main classes declared in {\tt <wx/datetime.h>}: except 
 \helpref{wxDateTime}{wxdatetime} itself which represents an absolute
 
 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
+moment in 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
 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.
+class for which (only) Saturdays and Sundays are the holidays. See more about
+these classes in the discussion of the \helpref{holidays}{tdateholidays}.

 
 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.
 
 
 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}
+\subsection{wxDateTime characteristics}\label{wxdatetimecharacteristics}

 
 \helpref{wxDateTime}{wxdatetime} stores the time as a signed number of
 milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
 
 \helpref{wxDateTime}{wxdatetime} stores the time as a signed number of
 milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -


@@ -77,7 +78,7 @@ region, dependent). Future versions will probably have Julian calendar support
 as well and support for other calendars (Maya, Hebrew, Chinese...) is not
 ruled out.
 
 as well and support for other calendars (Maya, Hebrew, Chinese...) is not
 ruled out.
 

-\subsection{Difference between wxDateSpan and wxTimeSpan}
+\subsection{Difference between wxDateSpan and wxTimeSpan}\label{dateandtimespansdifference}

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


@@ -85,7 +86,7 @@ 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
 
 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
+between two moments in time. Adding or subtracting such an interval to

 wxDateTime is always well-defined and is a fast operation.
 
 But in the daily life other, calendar-dependent time interval specifications are
 wxDateTime is always well-defined and is a fast operation.
 
 But in the daily life other, calendar-dependent time interval specifications are


@@ -95,46 +96,46 @@ 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 
 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
+\helpref{wxDateSpan}{wxdatespan}. It handles these sort of operations in the
+most natural way possible, but note that manipulating with intervals 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
 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
+the non-existent Feb 31. Of course, this is what is usually wanted, but you
+still might be surprised to notice that now subtracting 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
 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
+when you do need to understand what `in a month' means (of course, it is

 just {\tt wxDateTime::Now() + wxDateSpan::Month()}).
 
 just {\tt wxDateTime::Now() + wxDateSpan::Month()}).
 

-\subsection{Date arithmetics}
+\subsection{Date arithmetics}\label{tdatearithm}

 
 Many different operations may be performed with the dates, however not all of
 
 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.
+them make sense. For example, multiplying a date by a number is an invalid
+operation, even though multiplying either of the time span classes by a number
+is perfectly valid.

 
 Here is what can be done:
 
 
 Here is what can be done:
 

-\begin{twocollist}
-\item{{\bf Addition}}{a wxTimeSpan or wxDateSpan can be added to wxDateTime
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\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
 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
+can be added together giving another object of the same class.}
+\twocolitem{{\bf Subtraction}}{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.}
 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
+\twocolitem{{\bf Multiplication}}{a wxTimeSpan or wxDateSpan object can be

 multiplied by an integer number resulting in an object of the same type.}
 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
+\twocolitem{{\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
 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
+and also member functions which are synonyms for them: Add(), Subtract() and

 Multiply(). Unary minus as well as composite assignment operations (like $+=$)
 are only implemented as members and Neg() is the synonym for unary minus.
 
 Multiply(). Unary minus as well as composite assignment operations (like $+=$)
 are only implemented as members and Neg() is the synonym for unary minus.
 


@@ -161,11 +162,11 @@ 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 
 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.
+\helpref{ToUTC}{wxdatetimetoutc} and \helpref{MakeUTC}{wxdatetimemakeutc} for
+the most common case - when the date should be constructed in UTC.

 
 You also can just retrieve the value for some time zone without converting the
 
 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
+object 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
 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


@@ -174,9 +175,9 @@ 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
 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
+usually you will just use one of the \helpref{symbolic time zone names}{wxdatetime} and
+let the conversion constructor do the job.
+I.e. you would just write

 
 \begin{verbatim}
 wxDateTime dt(...whatever...);
 
 \begin{verbatim}
 wxDateTime dt(...whatever...);


@@ -184,7 +185,7 @@ 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}
 
 printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
 \end{verbatim}
 

-\subsection{Daylight saving time (DST)}
+\subsection{Daylight saving time (DST)}\label{tdatedst}

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


@@ -204,9 +205,14 @@ too, so they are subject to the same limitations.
 
 % is this really needed? \subsection{Conversion to/from text}
 
 
 % is this really needed? \subsection{Conversion to/from text}
 

+\subsection{wxDateTime and Holidays}\label{tdateholidays}
+
+TODO.
+

 \subsection{Compatibility}\label{tdatecompatibility}
 
 \subsection{Compatibility}\label{tdatecompatibility}
 

-The old classes for date/time manipulations ported from wxWindows version 1.xx
+The old classes for date/time manipulations ported from wxWidgets 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.
 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.

+