datetime.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        datetime.tex
%% Purpose:     wxDateTime documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     07.03.00
%% RCS-ID:      $Id: datetime.tex,v 1.34 2006/10/29 00:05:56 VZ Exp $
%% Copyright:   (c) Vadim Zeitlin
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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, GMT13,
        // 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 = GMT13 + 1,                  // Central Standard Time (+9.5)
        A_EST = GMT10,                      // Eastern Standard Time
        A_ESST = GMT11,                     // Eastern Summer Time

        // New Zealand
        NZST = GMT12,                       // Standard Time
        NZDT = GMT13,                       // Daylight Saving 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.

Likewise, 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.

\helpref{GetMonthName()}{wxdatetimegetmonthname} and
\helpref{GetWeekDayName}{wxdatetimegetweekdayname} functions use the following
flags:

\begin{verbatim}
    enum NameFlags
    {
        Name_Full = 0x01,       // return full name
        Name_Abbr = 0x02        // return abbreviated name
    };
\end{verbatim}

Several functions accept an extra parameter specifying the calendar to use
(although most of them only support now the Gregorian calendar). This
parameters is one of the following values:

\begin{verbatim}
    enum Calendar
    {
        Gregorian,  // calendar currently in use in Western countries
        Julian      // calendar in use since -45 until the 1582 (or later)
    };
\end{verbatim}

Date calculations often depend on the country and wxDateTime allows to set the
country whose conventions should be used using
\helpref{SetCountry}{wxdatetimesetcountry}. It takes one of the following
values as parameter:

\begin{verbatim}
    enum Country
    {
        Country_Unknown, // no special information for this country
        Country_Default, // set the default country with SetCountry() method
                         // or use the default country with any other

        Country_WesternEurope_Start,
        Country_EEC = Country_WesternEurope_Start,
        France,
        Germany,
        UK,
        Country_WesternEurope_End = UK,

        Russia,

        USA
    };
\end{verbatim}

Different parts of the world use different conventions for the week start.
In some countries, the week starts on Sunday, while in others -- on Monday.
The ISO standard doesn't address this issue, so we support both conventions in
the functions whose result depends on it (\helpref{GetWeekOfYear}{wxdatetimegetweekofyear} and
\helpref{GetWeekOfMonth}{wxdatetimegetweekofmonth}).

The desired behvaiour may be specified by giving one of the following
constants as argument to these functions:

\begin{verbatim}
    enum WeekFlags
    {
        Default_First,   // Sunday_First for US, Monday_First for the rest
        Monday_First,    // week starts with a Monday
        Sunday_First     // week starts with a Sunday
    };
\end{verbatim}

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/datetime.h>

\wxheading{See also}

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

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


\membersection{Static functions}\label{datetimestaticfunctions}

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.

Please note that although several function accept an extra {\it Calendar}
parameter, it is currently ignored as only the Gregorian calendar is
supported. Future versions will support other calendars.

\pythonnote{These methods are standalone functions named
{\tt wxDateTime\_<StaticMethodName>} in wxPython.}

\helpref{SetCountry}{wxdatetimesetcountry}\\
\helpref{GetCountry}{wxdatetimegetcountry}\\
\helpref{IsWestEuropeanCountry}{wxdatetimeiswesteuropeancountry}\\
\helpref{GetCurrentYear}{wxdatetimegetcurrentyear}\\
\helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
\helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
\helpref{IsLeapYear}{wxdatetimeisleapyear}\\
\helpref{GetCentury}{wxdatetimegetcenturystatic}\\
\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{UNow}{wxdatetimeunow}\\
\helpref{Today}{wxdatetimetoday}


\membersection{Constructors, assignment operators and setters}\label{datetimeconstructors}

Constructors and various {\tt Set()} methods are collected here. If you
construct a date object from separate values for day, month and year, you
should use \helpref{IsValid}{wxdatetimeisvalid} method to check that the
values were correct as constructors can not return an error code.

\helpref{wxDateTime()}{wxdatetimewxdatetimedef}\\
\helpref{wxDateTime(time\_t)}{wxdatetimewxdatetimetimet}\\
\helpref{wxDateTime(struct tm)}{wxdatetimewxdatetimetm}\\
%\helpref{wxDateTime(struct Tm)}{wxdatetimewxdatetimetm} - Tm not documented yet\\
\helpref{wxDateTime(double jdn)}{wxdatetimewxdatetimejdn}\\
\helpref{wxDateTime(h, m, s, ms)}{wxdatetimewxdatetimetime}\\
\helpref{wxDateTime(day, mon, year, h, m, s, ms)}{wxdatetimewxdatetimedate}\\
\helpref{SetToCurrent}{wxdatetimesettocurrent}\\
\helpref{Set(time\_t)}{wxdatetimesettimet}\\
\helpref{Set(struct tm)}{wxdatetimesettm}\\
%\helpref{Set(struct Tm)}{wxdatetimesettm} - Tm not documented yet\\
\helpref{Set(double jdn)}{wxdatetimesetjdn}\\
\helpref{Set(h, m, s, ms)}{wxdatetimesettime}\\
\helpref{Set(day, mon, year, h, m, s, ms)}{wxdatetimesetdate}\\
\helpref{SetFromDOS(unsigned long ddt)}{wxdatetimesetfromdos}\\
\helpref{ResetTime}{wxdatetimeresettime}\\
\helpref{SetYear}{wxdatetimesetyear}\\
\helpref{SetMonth}{wxdatetimesetmonth}\\
\helpref{SetDay}{wxdatetimesetdate}\\
\helpref{SetHour}{wxdatetimesethour}\\
\helpref{SetMinute}{wxdatetimesetminute}\\
\helpref{SetSecond}{wxdatetimesetsecond}\\
\helpref{SetMillisecond}{wxdatetimesetmillisecond}\\
\helpref{operator$=$(time\_t)}{wxdatetimeoperatoreqtimet}\\
\helpref{operator$=$(struct tm)}{wxdatetimeoperatoreqtm}\rtfsp


\membersection{Accessors}\label{datetimeaccessors}

Here are the trivial accessors. Other functions, which might have to perform
some more complicated calculations to find the answer are under the
\helpref{Calendar calculations}{datetimecalculations} section.

\helpref{IsValid}{wxdatetimeisvalid}\\
\helpref{GetTicks}{wxdatetimegetticks}\\
\helpref{GetCentury}{wxdatetimegetcentury}\\
\helpref{GetYear}{wxdatetimegetyear}\\
\helpref{GetMonth}{wxdatetimegetmonth}\\
\helpref{GetDay}{wxdatetimegetday}\\
\helpref{GetWeekDay}{wxdatetimegetweekday}\\
\helpref{GetHour}{wxdatetimegethour}\\
\helpref{GetMinute}{wxdatetimegetminute}\\
\helpref{GetSecond}{wxdatetimegetsecond}\\
\helpref{GetMillisecond}{wxdatetimegetmillisecond}\\
\helpref{GetDayOfYear}{wxdatetimegetdayofyear}\\
\helpref{GetWeekOfYear}{wxdatetimegetweekofyear}\\
\helpref{GetWeekOfMonth}{wxdatetimegetweekofmonth}\\
\helpref{GetYearDay}{wxdatetimegetyearday}\\
\helpref{IsWorkDay}{wxdatetimeisworkday}\\
\helpref{IsGregorianDate}{wxdatetimeisgregoriandate}\\
\helpref{GetAsDOS}{wxdatetimegetasdos}


\membersection{Date comparison}\label{datecomparison}

There are several function to allow date comparison. To supplement them, a few
global operators $>$, $<$ etc taking wxDateTime are defined.

\helpref{IsEqualTo}{wxdatetimeisequalto}\\
\helpref{IsEarlierThan}{wxdatetimeisearlierthan}\\
\helpref{IsLaterThan}{wxdatetimeislaterthan}\\
\helpref{IsStrictlyBetween}{wxdatetimeisstrictlybetween}\\
\helpref{IsBetween}{wxdatetimeisbetween}\\
\helpref{IsSameDate}{wxdatetimeissamedate}\\
\helpref{IsSameTime}{wxdatetimeissametime}\\
\helpref{IsEqualUpTo}{wxdatetimeisequalupto}


\membersection{Date arithmetics}\label{datearithmetics}

These functions carry out \helpref{arithmetics}{tdatearithm} on the wxDateTime
objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be
added to wxDateTime, hence all functions are overloaded to accept both
arguments.

Also, both {\tt Add()} and {\tt Subtract()} have both const and non-const
version. The first one returns a new object which represents the
sum/difference of the original one with the argument while the second form
modifies the object to which it is applied. The operators $-=$ and $+=$ are
defined to be equivalent to the second forms of these functions.

\helpref{Add(wxTimeSpan)}{wxdatetimeaddts}\\
\helpref{Add(wxDateSpan)}{wxdatetimeaddds}\\
\helpref{Subtract(wxTimeSpan)}{wxdatetimesubtractts}\\
\helpref{Subtract(wxDateSpan)}{wxdatetimesubtractds}\\
\helpref{Subtract(wxDateTime)}{wxdatetimesubtractdt}\\
\helpref{oparator$+=$(wxTimeSpan)}{wxdatetimeaddts}\\
\helpref{oparator$+=$(wxDateSpan)}{wxdatetimeaddds}\\
\helpref{oparator$-=$(wxTimeSpan)}{wxdatetimesubtractts}\\
\helpref{oparator$-=$(wxDateSpan)}{wxdatetimesubtractds}


\membersection{Parsing and formatting dates}\label{datetimeparsing}

These functions convert wxDateTime objects to and from text. The
conversions to text are mostly trivial: you can either do it using the default
date and time representations for the current locale (
\helpref{FormatDate}{wxdatetimeformatdate} and
\helpref{FormatTime}{wxdatetimeformattime}), using the international standard
representation defined by ISO 8601 (
\helpref{FormatISODate}{wxdatetimeformatisodate} and
\helpref{FormatISOTime}{wxdatetimeformatisotime}) or by specifying any format
at all and using \helpref{Format}{wxdatetimeformat} directly.

The conversions from text are more interesting, as there are much more
possibilities to care about. The simplest cases can be taken care of with
\helpref{ParseFormat}{wxdatetimeparseformat} which can parse any date in the
given (rigid) format. \helpref{ParseRfc822Date}{wxdatetimeparserfc822date} is
another function for parsing dates in predefined format -- the one of RFC 822
which (still...) defines the format of email messages on the Internet. This
format can not be described with {\tt strptime(3)}-like format strings used by
\helpref{Format}{wxdatetimeformat}, hence the need for a separate function.

But the most interesting functions are
\helpref{ParseTime}{wxdatetimeparsetime},
\helpref{ParseDate}{wxdatetimeparsedate} and
\helpref{ParseDateTime}{wxdatetimeparsedatetime}. They try to parse the date
ans time (or only one of them) in `free' format, i.e. allow them to be
specified in any of possible ways. These functions will usually be used to
parse the (interactive) user input which is not bound to be in any predefined
format. As an example, \helpref{ParseDateTime}{wxdatetimeparsedatetime} can
parse the strings such as {\tt "tomorrow"}, {\tt "March first"} and even
{\tt "next Sunday"}.

\helpref{ParseRfc822Date}{wxdatetimeparserfc822date}\\
\helpref{ParseFormat}{wxdatetimeparseformat}\\
\helpref{ParseDateTime}{wxdatetimeparsedatetime}\\
\helpref{ParseDate}{wxdatetimeparsedate}\\
\helpref{ParseTime}{wxdatetimeparsetime}\\
\helpref{Format}{wxdatetimeformat}\\
\helpref{FormatDate}{wxdatetimeformatdate}\\
\helpref{FormatTime}{wxdatetimeformattime}\\
\helpref{FormatISODate}{wxdatetimeformatisodate}\\
\helpref{FormatISOTime}{wxdatetimeformatisotime}


\membersection{Calendar calculations}\label{datetimecalculations}

The functions in this section perform the basic calendar calculations, mostly
related to the week days. They allow to find the given week day in the
week with given number (either in the month or in the year) and so on.

All (non-const) functions in this section don't modify the time part of the
wxDateTime -- they only work with the date part of it.

\helpref{SetToWeekDayInSameWeek}{wxdatetimesettoweekdayinsameweek}\\
\helpref{GetWeekDayInSameWeek}{wxdatetimegetweekdayinsameweek}\\
\helpref{SetToNextWeekDay}{wxdatetimesettonextweekday}\\
\helpref{GetNextWeekDay}{wxdatetimegetnextweekday}\\
\helpref{SetToPrevWeekDay}{wxdatetimesettoprevweekday}\\
\helpref{GetPrevWeekDay}{wxdatetimegetprevweekday}\\
\helpref{SetToWeekDay}{wxdatetimesettoweekday}\\
\helpref{GetWeekDay}{wxdatetimegetweekday2}\\
\helpref{SetToLastWeekDay}{wxdatetimesettolastweekday}\\
\helpref{GetLastWeekDay}{wxdatetimegetlastweekday}\\
\helpref{SetToWeekOfYear}{wxdatetimesettoweekofyear}\\
\helpref{SetToLastMonthDay}{wxdatetimesettolastmonthday}\\
\helpref{GetLastMonthDay}{wxdatetimegetlastmonthday}\\
\helpref{SetToYearDay}{wxdatetimesettoyearday}\\
\helpref{GetYearDay}{wxdatetimegetyearday}