%% Created: 07.03.00
%% RCS-ID: $Id$
%% Copyright: (c) Vadim Zeitlin
-%% License: wxWidgets license
+%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxDateTime}}\label{wxdatetime}
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,
+ 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
// Australia
A_WST = GMT8, // Western Standard Time
- A_CST = GMT12 + 1, // Central Standard Time (+9.5)
+ 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
Finally, Inv\_Year is defined to be an invalid value for year parameter.
\helpref{GetMonthName()}{wxdatetimegetmonthname} and
-\helpref{GetWeekDayName}{wxdatetimegetweekdayname} functions use the followign
+\helpref{GetWeekDayName}{wxdatetimegetweekdayname} functions use the following
flags:
\begin{verbatim}
\end{verbatim}
Date calculations often depend on the country and wxDateTime allows to set the
-country whose conventions should be used using
+country whose conventions should be used using
\helpref{SetCountry}{wxdatetimesetcountry}. It takes one of the following
values as parameter:
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
+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
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
+\pythonnote{These methods are standalone functions named
{\tt wxDateTime\_<StaticMethodName>} in wxPython.}
\helpref{SetCountry}{wxdatetimesetcountry}\\
\helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
\helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
\helpref{IsLeapYear}{wxdatetimeisleapyear}\\
-\helpref{GetCentury}{wxdatetimegetcentury}\\
+\helpref{GetCentury}{wxdatetimegetcenturystatic}\\
\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
\helpref{GetMonthName}{wxdatetimegetmonthname}\\
\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
+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}\\
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
+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
+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
+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
+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
+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
+parse the strings such as {\tt "tomorrow"}, {\tt "March first"} and even
{\tt "next Sunday"}.
\helpref{ParseRfc822Date}{wxdatetimeparserfc822date}\\
\membersection{Time zone and DST support}\label{datetimedstzone}
Please see the \helpref{time zone overview}{tdatetimezones} for more
-information about time zones. ormally, these functions should be rarely used.
+information about time zones. Normally, these functions should be rarely used.
+\helpref{FromTimezone}{wxdatetimefromtimezone}\\
\helpref{ToTimezone}{wxdatetimetotimezone}\\
\helpref{MakeTimezone}{wxdatetimemaketimezone}\\
-\helpref{ToGMT}{wxdatetimetogmt}\\
-\helpref{MakeGMT}{wxdatetimemakegmt}\\
+\helpref{MakeFromTimezone}{wxdatetimemakefromtimezone}\\
+\helpref{ToUTC}{wxdatetimetoutc}\\
+\helpref{MakeUTC}{wxdatetimemakeutc}\\
\helpref{GetBeginDST}{wxdatetimegetbegindst}\\
\helpref{GetEndDST}{wxdatetimegetenddst}\\
\helpref{IsDST}{wxdatetimeisdst}
Get the current month in given calendar (only Gregorian is currently supported).
-\membersection{wxDateTime::GetCentury}\label{wxdatetimegetcentury}
+\membersection{wxDateTime::GetCentury}\label{wxdatetimegetcenturystatic}
-\func{static int}{GetCentury}{\param{int }{year = Inv\_Year}}
+\func{static int}{GetCentury}{\param{int }{year}}
Get the current century, i.e. first two digits of the year, in given calendar
(only Gregorian is currently supported).
\membersection{wxDateTime::GetTmNow}\label{wxdatetimegettmnow}
-\func{static struct tm *}{GetTmNow}{\void}
+\func{static struct tm *}{GetTmNow}{\param{struct tm *}{tm}}
+
+Returns the current time broken down, uses the buffer whose adress is
+passed to the function via {\it tm} to store the result.
-Returns the current time broken down.
+\membersection{wxDateTime::GetTmNow}
+\func{static struct tm *}{GetTmNow}{\void}
+
+Returns the current time broken down. Note that this function returns a
+pointer to a static buffer that's reused by calls to this function and
+certain C library functions (e.g. localtime). If there is any chance your
+code might be used in a multi-threaded application, you really should use
+the flavour of function \helpref{wxDateTime::GetTmNow}{wxdatetimegettmnow}
+taking a parameter.
\membersection{wxDateTime::GetWeekDayName}\label{wxdatetimegetweekdayname}
printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
\end{verbatim}
-Note that this function is accurate up to second:
+Note that this function is accurate up to second:
\helpref{wxDateTime::UNow}{wxdatetimeunow} should be used for better precision
(but it is less efficient and might not be available on all platforms).
\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimedate}
-\func{wxDateTime\&}{wxDateTime}{\param{wxDateTime\_t }{day}, \param{Month }{month = Inv\_Month}, \param{int}{ Inv\_Year},
+\func{wxDateTime\&}{wxDateTime}{\param{wxDateTime\_t }{day}, \param{Month }{month = Inv\_Month}, \param{int}{ Inv\_Year},
\param{wxDateTime\_t }{hour = 0}, \param{wxDateTime\_t }{minute = 0}, \param{wxDateTime\_t }{second = 0}, \param{wxDateTime\_t }{millisec = 0}}
Same as \helpref{Set}{wxdatetimesetdate}
if the date is not in the range covered by {\tt time\_t} type.
+\membersection{wxDateTime::GetCentury}\label{wxdatetimegetcentury}
+
+\constfunc{int}{GetCentury}{\param{const TimeZone\& }{tz = Local}}
+
+Returns the century of this date.
+
+
\membersection{wxDateTime::GetYear}\label{wxdatetimegetyear}
\constfunc{int}{GetYear}{\param{const TimeZone\& }{tz = Local}}
equivalently, the first week which has Thursday in this year. Both of these
definitions are the same as saying that the first week of the year must contain
more than half of its days in this year. Accordingly, the week number will
-always be in $1\ldots53$ range ($52$ for non leap years).
+always be in $1\ldots53$ range ($52$ for non-leap years).
The function depends on the \helpref{week start}{wxdatetime} convention
-specified by the {\it flags} argument but its results for
+specified by the {\it flags} argument but its results for
\texttt{Sunday\_First} are not well-defined as the ISO definition quoted above
applies to the weeks starting on Monday only.
\func{wxDateTime\&}{Set}{\param{unsigned long }{ddt}}
-Sets the date from the date and time in
-\urlref{DOS}{http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms\_docs/data/hc2vlu5i.html}
+Sets the date from the date and time in
+\urlref{DOS}{http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms\_docs/data/hc2vlu5i.html}
format.
\constfunc{unsigned long}{GetAsDOS}{\void}
-Returns the date and time in
-\urlref{DOS}{http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms\_docs/data/hc2vlu5i.html}
+Returns the date and time in
+\urlref{DOS}{http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms\_docs/data/hc2vlu5i.html}
format.
%%%%%%%%%%%%%%%%%%%%%%%%%%% comparison %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\membersection{wxDateTime::ParseFormat}\label{wxdatetimeparseformat}
-\func{const wxChar *}{ParseFormat}{\param{const wxChar *}{date}, \param{const wxChar *}{format = "\%c"}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}}
+\func{const wxChar *}{ParseFormat}{\param{const wxChar *}{date}, \param{const wxChar *}{format = wxDefaultDateTimeFormat}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}}
This function parses the string {\it date} according to the given
{\it format}. The system {\tt strptime(3)} function is used whenever available,
can not be parsed in any way at all.
Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
-the character which stopped the scan. This method is currently not
-implemented, so always returns NULL.
+the character which stopped the scan.
\membersection{wxDateTime::ParseDate}\label{wxdatetimeparsedate}
\func{const wxChar *}{ParseDate}{\param{const wxChar *}{date}}
This function is like \helpref{ParseDateTime}{wxdatetimeparsedatetime}, but it
-only allows the date to be specified. It is thus less flexible then
+only allows the date to be specified. It is thus less flexible then
\helpref{ParseDateTime}{wxdatetimeparsedatetime}, but also has less chances to
misinterpret the user input.
\membersection{wxDateTime::Format}\label{wxdatetimeformat}
-\constfunc{wxString }{Format}{\param{const wxChar *}{format = "\%c"}, \param{const TimeZone\& }{tz = Local}}
+\constfunc{wxString }{Format}{\param{const wxChar *}{format = wxDefaultDateTimeFormat}, \param{const TimeZone\& }{tz = Local}}
This function does the same as the standard ANSI C {\tt strftime(3)} function.
Please see its description for the meaning of {\it format} parameter.
\constfunc{wxDateTime}{GetWeekDayInSameWeek}{\param{WeekDay }{weekday}, \param{WeekFlags}{flags = {\tt Monday\_First}}}
-Returns the copy of this object to which
+Returns the copy of this object to which
\helpref{SetToWeekDayInSameWeek}{wxdatetimesettoweekdayinsameweek} was
applied.
Note that the returned date may be in a different year than the one passed to
this function because both the week $1$ and week $52$ or $53$ (for leap years)
-contain days from different years. See
+contain days from different years. See
\helpref{GetWeekOfYear}{wxdatetimegetweekofyear} for the explanation of how the
year weeks are counted.
%%%%%%%%%%%%%%%%%%%%%%%%%%% timezone and DST %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\membersection{wxDateTime::FromTimezone}\label{wxdatetimefromtimezone}
+
+\constfunc{wxDateTime}{FromTimezone}{\param{const TimeZone\& }{tz}, \param{bool }{noDST = false}}
+
+Transform the date from the given time zone to the local one. If {\it noDST} is
+{\tt true}, no DST adjustments will be made.
+
+Returns the date in the local time zone.
+
+
\membersection{wxDateTime::ToTimezone}\label{wxdatetimetotimezone}
\constfunc{wxDateTime}{ToTimezone}{\param{const TimeZone\& }{tz}, \param{bool }{noDST = false}}
{\it noDST} is {\tt true}, no DST adjustments will be made.
-\membersection{wxDateTime::ToGMT}\label{wxdatetimetogmt}
+\membersection{wxDateTime::MakeFromTimezone}\label{wxdatetimemakefromtimezone}
+
+\func{wxDateTime\&}{MakeFromTimezone}{\param{const TimeZone\& }{tz}, \param{bool }{noDST = false}}
+
+Same as \helpref{FromTimezone}{wxdatetimefromtimezone} but modifies the object
+in place.
+
+
+\membersection{wxDateTime::ToUTC}\label{wxdatetimetoutc}
-\constfunc{wxDateTime}{ToGMT}{\param{bool }{noDST = false}}
+\constfunc{wxDateTime}{ToUTC}{\param{bool }{noDST = false}}
This is the same as calling \helpref{ToTimezone}{wxdatetimetotimezone} with
the argument {\tt GMT0}.
-\membersection{wxDateTime::MakeGMT}\label{wxdatetimemakegmt}
+\membersection{wxDateTime::MakeUTC}\label{wxdatetimemakeutc}
-\func{wxDateTime\&}{MakeGMT}{\param{bool }{noDST = false}}
+\func{wxDateTime\&}{MakeUTC}{\param{bool }{noDST = false}}
This is the same as calling \helpref{MakeTimezone}{wxdatetimemaketimezone} with
the argument {\tt GMT0}.
projects / wxWidgets.git / blobdiff