X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3103e8a97e834e9793f0eb149aa82a99fd64ef9a..984daa2a57c5fa9fd23d089209efd81f59273ea3:/docs/latex/wx/datetime.tex

diff --git a/docs/latex/wx/datetime.tex b/docs/latex/wx/datetime.tex
index c77282bc17..3fa45268da 100644
--- a/docs/latex/wx/datetime.tex
+++ b/docs/latex/wx/datetime.tex
@@ -43,7 +43,7 @@ Time zone symbolic names:
         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
 
@@ -77,10 +77,14 @@ Time zone symbolic names:
         // 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
@@ -171,6 +175,10 @@ No base class
 
 <wx/datetime.h>
 
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
 \wxheading{See also}
 
 \helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
@@ -202,7 +210,7 @@ supported. Future versions will support other calendars.
 \helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
 \helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
 \helpref{IsLeapYear}{wxdatetimeisleapyear}\\
-\helpref{GetCentury}{wxdatetimegetcentury}\\
+\helpref{GetCentury}{wxdatetimegetcenturystatic}\\
 \helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
 \helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
 \helpref{GetMonthName}{wxdatetimegetmonthname}\\
@@ -258,6 +266,7 @@ some more complicated calculations to find the answer are under the
 
 \helpref{IsValid}{wxdatetimeisvalid}\\
 \helpref{GetTicks}{wxdatetimegetticks}\\
+\helpref{GetCentury}{wxdatetimegetcentury}\\
 \helpref{GetYear}{wxdatetimegetyear}\\
 \helpref{GetMonth}{wxdatetimegetmonth}\\
 \helpref{GetDay}{wxdatetimegetday}\\
@@ -322,9 +331,10 @@ 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.
+\helpref{FormatISODate}{wxdatetimeformatisodate},
+\helpref{FormatISOTime}{wxdatetimeformatisotime} and
+\helpref{FormatISOCombined}{wxdatetimeformatisocombined}) 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
@@ -346,14 +356,26 @@ 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}\\
+Finally notice that each of the parsing functions is available in several
+overloads: if the input string is a narrow (\texttt{char *}) string, then a
+narrow pointer is returned. If the input string is a wide string, a wide char
+pointer is returned. Finally, if the input parameter is a wxString, a narrow
+char pointer is also returned for backwards compatibility but there is also an
+additional argument of wxString::const\_iterator type in which, if it is not
+\NULL, an iterator pointing to the end of the scanned string part is returned.
+
 \helpref{ParseFormat}{wxdatetimeparseformat}\\
 \helpref{ParseDateTime}{wxdatetimeparsedatetime}\\
 \helpref{ParseDate}{wxdatetimeparsedate}\\
 \helpref{ParseTime}{wxdatetimeparsetime}\\
+\helpref{ParseISODate}{wxdatetimeparseisodate}\\
+\helpref{ParseISOTime}{wxdatetimeparseisotime}\\
+\helpref{ParseISOCombined}{wxdatetimeparseisocombined}\\
+\helpref{ParseRfc822Date}{wxdatetimeparserfc822date}\\
 \helpref{Format}{wxdatetimeformat}\\
 \helpref{FormatDate}{wxdatetimeformatdate}\\
 \helpref{FormatTime}{wxdatetimeformattime}\\
+\helpref{FormatISOCombined}{wxdatetimeformatisocombined}\\
 \helpref{FormatISODate}{wxdatetimeformatisodate}\\
 \helpref{FormatISOTime}{wxdatetimeformatisotime}
 
@@ -406,10 +428,12 @@ provided. You can construct a wxDateTime object from a
 Please see the \helpref{time zone overview}{tdatetimezones} for more
 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}
@@ -489,9 +513,9 @@ Get the current year in given calendar (only Gregorian is currently supported).
 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).
@@ -545,10 +569,21 @@ Returns the current time.
 
 \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}
 
@@ -844,6 +879,20 @@ Same as \helpref{Set}{wxdatetimesettm}.
 Returns {\tt true} if the object represents a valid time moment.
 
 
+\membersection{wxDateTime::GetDateOnly}\label{wxdatetimegetdateonly}
+
+\constfunc{wxDateTime}{GetDateOnly}{\void}
+
+Returns the object having the same date component as this one but time of
+00:00:00.
+
+\newsince{2.8.2}
+
+\wxheading{See also}
+
+\helpref{ResetTime}{wxdatetimeresettime}
+
+
 \membersection{wxDateTime::GetTm}\label{wxdatetimegettm}
 
 \constfunc{Tm}{GetTm}{\param{const TimeZone\& }{tz = Local}}
@@ -859,6 +908,13 @@ Returns the number of seconds since Jan 1, 1970. An assert failure will occur
 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}}
@@ -932,7 +988,7 @@ the year is, according to international standards, the one containing Jan 4 or,
 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
@@ -1126,9 +1182,13 @@ as wxTimeSpan.
 
 \membersection{wxDateTime::ParseRfc822Date}\label{wxdatetimeparserfc822date}
 
-\func{const wxChar *}{ParseRfc822Date}{\param{const wxChar* }{date}}
+\func{const char *}{ParseRfc822Date}{\param{const wxString\& }{date}, \param{wxString::const\_iterator *}{end = \NULL}}
 
-Parses the string {\it date} looking for a date formatted according to the RFC
+\func{const char *}{ParseRfc822Date}{\param{const char* }{date}}
+
+\func{const wchar\_t *}{ParseRfc822Date}{\param{const wchar\_t* }{date}}
+
+Parses the string \arg{date} looking for a date formatted according to the RFC
 822 in it. The exact description of this format may, of course, be found in
 the RFC (section $5$), but, briefly, this is the format used in the headers of
 Internet email messages and one of the most common strings expressing date in
@@ -1147,7 +1207,11 @@ free ways, you should use \helpref{ParseDateTime}{wxdatetimeparsedatetime} or
 
 \membersection{wxDateTime::ParseFormat}\label{wxdatetimeparseformat}
 
-\func{const wxChar *}{ParseFormat}{\param{const wxChar *}{date}, \param{const wxChar *}{format = wxDefaultDateTimeFormat}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}}
+\func{const char *}{ParseFormat}{\param{const wxString\& }{date}, \param{const wxString\& }{format = wxDefaultDateTimeFormat}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}, \param{wxString::const\_iterator *}{end = \NULL}}
+
+\func{const char *}{ParseFormat}{\param{const char *}{date}, \param{const wxString\& }{format = wxDefaultDateTimeFormat}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}}
+
+\func{const wchar\_t *}{ParseFormat}{\param{const wchar\_t *}{date}, \param{const wxString\& }{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,
@@ -1172,7 +1236,11 @@ the character which stopped the scan.
 
 \membersection{wxDateTime::ParseDateTime}\label{wxdatetimeparsedatetime}
 
-\func{const wxChar *}{ParseDateTime}{\param{const wxChar *}{datetime}}
+\func{const char *}{ParseDateTime}{\param{const wxString\& }{datetime}, \param{wxString::const\_iterator *}{end = \NULL}}
+
+\func{const char *}{ParseDateTime}{\param{const char *}{datetime}}
+
+\func{const wchar\_t *}{ParseDateTime}{\param{const wchar\_t *}{datetime}}
 
 Parses the string {\it datetime} containing the date and time in free format.
 This function tries as hard as it can to interpret the given string as date
@@ -1181,13 +1249,16 @@ will accept anything that may be accepted and will only reject strings which
 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}}
+\func{const char *}{ParseDate}{\param{const wxString\& }{date}, \param{wxString::const\_iterator *}{end = \NULL}}
+
+\func{const char *}{ParseDate}{\param{const char *}{date}}
+
+\func{const wchar\_t *}{ParseDate}{\param{const wchar\_t *}{date}}
 
 This function is like \helpref{ParseDateTime}{wxdatetimeparsedatetime}, but it
 only allows the date to be specified. It is thus less flexible then
@@ -1200,7 +1271,11 @@ the character which stopped the scan.
 
 \membersection{wxDateTime::ParseTime}\label{wxdatetimeparsetime}
 
-\func{const wxChar *}{ParseTime}{\param{const wxChar *}{time}}
+\func{const char *}{ParseTime}{\param{const wxString\& }{time}, \param{wxString::const\_iterator *}{end = \NULL}}
+
+\func{const char *}{ParseTime}{\param{const char *}{time}}
+
+\func{const wchar\_t *}{ParseTime}{\param{const wchar\_t *}{time}}
 
 This functions is like \helpref{ParseDateTime}{wxdatetimeparsedatetime}, but
 only allows the time to be specified in the input string.
@@ -1209,6 +1284,35 @@ Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
 the character which stopped the scan.
 
 
+\membersection{wxDateTime::ParseISODate}\label{wxdatetimeparseisodate}
+
+\func{bool}{ParseISODate}{\param{const wxString\& }{date}}
+
+This function parses the date in ISO 8601 format (YYYY-MM-DD).
+
+Returns \true if the entire string was parsed successfully, \false otherwise.
+
+
+\membersection{wxDateTime::ParseISOTime}\label{wxdatetimeparseisotime}
+
+\func{bool}{ParseISOTime}{\param{const wxString\& }{date}}
+
+This function parses the time in ISO 8601 format (HH:MM:SS).
+
+Returns \true if the entire string was parsed successfully, \false otherwise.
+
+
+\membersection{wxDateTime::ParseISOCombined}\label{wxdatetimeparseisocombined}
+
+\func{bool}{ParseISOCombined}{\param{const wxString\& }{date}, \param{char }{sep = 'T'}}
+
+This function parses the string containing the date and time in ISO 8601
+combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time
+parts must be equal to \arg{sep} for the function to succeed.
+
+Returns \true if the entire string was parsed successfully, \false otherwise.
+
+
 \membersection{wxDateTime::Format}\label{wxdatetimeformat}
 
 \constfunc{wxString }{Format}{\param{const wxChar *}{format = wxDefaultDateTimeFormat}, \param{const TimeZone\& }{tz = Local}}
@@ -1241,6 +1345,23 @@ Identical to calling \helpref{Format()}{wxdatetimeformat} with {\tt "\%X"}
 argument (which means `preferred time representation for the current locale').
 
 
+\membersection{wxDateTime::FormatISOCombined}\label{wxdatetimeformatisocombined}
+
+\constfunc{wxString}{FormatISOCombined}{\param{char }{sep = 'T'}}
+
+Returns the combined date-time representation in the ISO 8601 format
+(YYYY-MM-DDTHH:MM:SS). The \arg{sep} parameter default value produces the
+result exactly corresponding to the ISO standard, but it can also be useful to
+use a space as seprator if a more human-readable combined date-time
+representation is needed.
+
+\wxheading{See also}
+
+\helpref{FormatISODate}{wxdatetimeformatisodate},\\
+\helpref{FormatISOTime}{wxdatetimeformatisotime},\\
+\helpref{ParseISOCombined}{wxdatetimeparseisocombined}
+
+
 \membersection{wxDateTime::FormatISODate}\label{wxdatetimeformatisodate}
 
 \constfunc{wxString }{FormatISODate}{\void}
@@ -1461,6 +1582,16 @@ year 1 is Rata Die day 1.
 %%%%%%%%%%%%%%%%%%%%%%%%%%% 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}}
@@ -1479,17 +1610,25 @@ Modifies the object in place to represent the date in another time zone. If
 {\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}.
@@ -1508,9 +1647,37 @@ Returns {\tt true} if the DST is applied for this date in the given country.
 
 \section{\class{wxDateTimeHolidayAuthority}}\label{wxdatetimeholidayauthority}
 
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/datetime.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
 TODO
 
 \section{\class{wxDateTimeWorkDays}}\label{wxdatetimeworkdays}
 
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/datetime.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
 TODO
 
