1. fixed crash in wxDateTime::ParseDate

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        datetime.tex
%% Purpose:     wxDateTime documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     07.03.00
%% RCS-ID:      $Id$
%% Copyright:   (c) Vadim Zeitlin
%% Licence:     wxWindows licence
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxDateTime}}\label{wxdatetime}

wxDateTime class represents an absolute moment in the time.

\wxheading{Types}

The type {\tt wxDateTime\_t} is typedefed as {\tt unsigned short} and is used
to contain the number of years, hours, minutes, seconds and milliseconds.

\wxheading{Constants}

Global constant {\tt wxDefaultDateTime} and synonym for it {\tt wxInvalidDateTime} are defined. This constant will be different from any valid
wxDateTime object.

All the following constants are defined inside wxDateTime class (i.e., to refer to
them you should prepend their names with {\tt wxDateTime::}).

Time zone symbolic names:

\begin{verbatim}
    enum TZ
    {
        // the time in the current time zone
        Local,

        // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
        // consequent numbers, so writing something like `GMT0 + offset' is
        // safe if abs(offset) <= 12

        // underscore stands for minus
        GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
        GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
        GMT0,
        GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
        GMT7, GMT8, GMT9, GMT10, GMT11, GMT12,
        // Note that GMT12 and GMT_12 are not the same: there is a difference
        // of exactly one day between them

        // some symbolic names for TZ

        // Europe
        WET = GMT0,                         // Western Europe Time
        WEST = GMT1,                        // Western Europe Summer Time
        CET = GMT1,                         // Central Europe Time
        CEST = GMT2,                        // Central Europe Summer Time
        EET = GMT2,                         // Eastern Europe Time
        EEST = GMT3,                        // Eastern Europe Summer Time
        MSK = GMT3,                         // Moscow Time
        MSD = GMT4,                         // Moscow Summer Time

        // US and Canada
        AST = GMT_4,                        // Atlantic Standard Time
        ADT = GMT_3,                        // Atlantic Daylight Time
        EST = GMT_5,                        // Eastern Standard Time
        EDT = GMT_4,                        // Eastern Daylight Saving Time
        CST = GMT_6,                        // Central Standard Time
        CDT = GMT_5,                        // Central Daylight Saving Time
        MST = GMT_7,                        // Mountain Standard Time
        MDT = GMT_6,                        // Mountain Daylight Saving Time
        PST = GMT_8,                        // Pacific Standard Time
        PDT = GMT_7,                        // Pacific Daylight Saving Time
        HST = GMT_10,                       // Hawaiian Standard Time
        AKST = GMT_9,                       // Alaska Standard Time
        AKDT = GMT_8,                       // Alaska Daylight Saving Time

        // Australia

        A_WST = GMT8,                       // Western Standard Time
        A_CST = GMT12 + 1,                  // Central Standard Time (+9.5)
        A_EST = GMT10,                      // Eastern Standard Time
        A_ESST = GMT11,                     // Eastern Summer Time

        // Universal Coordinated Time = the new and politically correct name
        // for GMT
        UTC = GMT0
    };
\end{verbatim}

Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
Inv\_Month for an invalid.month value are the values of {\tt wxDateTime::Month} 
enum.

Likely, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv\_WeekDay are the values in 
{\tt wxDateTime::WeekDay} enum.

Finally, Inv\_Year is defined to be an invalid value for year parameter.

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/datetime.h>

\wxheading{See also}

%\helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
wxTimeSpan,\rtfsp
wxDateSpan,\rtfsp
\helpref{wxCalendarCtrl}{wxcalendarctrl}

\latexignore{\rtfignore{\wxheading{Function groups}}}

\membersection{Static functions}

For convenience, all static functions are collected here. These functions
either set or return the static variables of wxDateSpan (the country), return
the current moment, year, month or number of days in it, or do some general
calendar-related actions.

\helpref{SetCountry}{wxdatetimesetcountry}\\
\helpref{GetCountry}{wxdatetimegetcountry}\\
\helpref{IsWestEuropeanCountry}{wxdatetimeiswesteuropeancountry}\\
\helpref{GetCurrentYear}{wxdatetimegetcurrentyear}\\
\helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
\helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
\helpref{IsLeapYear}{wxdatetimeisleapyear}\\
\helpref{GetCentury}{wxdatetimegetcentury}\\
\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
\helpref{GetMonthName}{wxdatetimegetmonthname}\\
\helpref{GetWeekDayName}{wxdatetimegetweekdayname}\\
\helpref{GetAmPmStrings}{wxdatetimegetampmstrings}\\
\helpref{IsDSTApplicable}{wxdatetimeisdstapplicable}\\
\helpref{GetBeginDST}{wxdatetimegetbegindst}\\
\helpref{GetEndDST}{wxdatetimegetenddst}\\
\helpref{Now}{wxdatetimenow}\\
\helpref{Today}{wxdatetimetoday}

\membersection{Constructors, assignment operators and setters}

\membersection{Accessors}

\membersection{Date comparison}

\membersection{Date arithmetics}

\membersection{Parsing and formatting dates}

\membersection{Calendar calculations}

\membersection{Astronomical/historical functions}

\membersection{Time zone support}

\helponly{\insertatlevel{2}{

\wxheading{Members}

}}

\membersection{wxDateTime::ConvertYearToBC}\label{wxdatetimeconvertyeartobc}

\func{static int}{ConvertYearToBC}{\param{int }{year}}

Converts the year in absolute notation (i.e. a number which can be negative,
positive or zero) to the year in BC/AD notation. For the positive years,
nothing is done, but the year 0 is year 1 BC and so for other years there is a
difference of 1.

This function should be used like this:

\begin{verbatim}
    wxDateTime dt(...);
    int y = dt.GetYear();
    printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
\end{verbatim}

\membersection{wxDateTime::GetAmPmStrings}\label{wxdatetimegetampmstrings}

\func{static void}{GetAmPmStrings}{\param{wxString *}{am}, \param{wxString *}{pm}}

\membersection{wxDateTime::GetBeginDST}\label{wxdatetimegetbegindst}

\func{static wxDateTime}{GetBeginDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}

\membersection{wxDateTime::GetCountry}\label{wxdatetimegetcountry}

\func{static Country}{GetCountry}{\void}

\membersection{wxDateTime::GetCurrentYear}\label{wxdatetimegetcurrentyear}

\func{static int}{GetCurrentYear}{\param{Calendar }{cal = Gregorian}}

\membersection{wxDateTime::GetCurrentMonth}\label{wxdatetimegetcurrentmonth}

\func{static Month}{GetCurrentMonth}{\param{Calendar }{cal = Gregorian}}

\membersection{wxDateTime::GetCentury}\label{wxdatetimegetcentury}

\func{static int}{GetCentury}{\param{int }{year = Inv\_Year}}

\membersection{wxDateTime::GetEndDST}\label{wxdatetimegetenddst}

\func{static wxDateTime}{GetEndDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}

\membersection{wxDateTime::GetMonthName}\label{wxdatetimegetmonthname}

\func{static wxString}{GetMonthName}{\param{Month }{month}, \param{NameFlags }{flags = Name\_Full}}

\membersection{wxDateTime::GetNumberOfDays}\label{wxdatetimegetnumberofdays}

\func{static wxDateTime\_t}{GetNumberOfDays}{\param{int }{year}, \param{Calendar }{cal = Gregorian}}

\func{static wxDateTime\_t}{GetNumberOfDays}{\param{Month }{month}, \param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}

\membersection{wxDateTime::GetWeekDayName}\label{wxdatetimegetweekdayname}

\func{static wxString}{GetWeekDayName}{\param{WeekDay }{weekday}, \param{NameFlags }{flags = Name\_Full}}

\membersection{wxDateTime::IsLeapYear}\label{wxdatetimeisleapyear}

\func{static bool}{IsLeapYear}{\param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}

\membersection{wxDateTime::IsWestEuropeanCountry}\label{wxdatetimeiswesteuropeancountry}

\func{static bool}{IsWestEuropeanCountry}{\param{Country }{country = Country\_Default}}

\membersection{wxDateTime::IsDSTApplicable}\label{wxdatetimeisdstapplicable}

\func{static bool}{IsDSTApplicable}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}

\membersection{wxDateTime::Now}\label{wxdatetimenow}

\func{static wxDateTime}{Now}{\void}

\membersection{wxDateTime::SetCountry}\label{wxdatetimesetcountry}

\func{static void}{SetCountry}{\param{Country }{country}}

\membersection{wxDateTime::Today}\label{wxdatetimetoday}

\func{static wxDateTime}{Today}{\void}