Commited John Labenski's patch giving access to the low level selection
[wxWidgets.git] / docs / latex / wx / datetime.tex
CommitLineData
d7da9756
VZ
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: datetime.tex
3%% Purpose: wxDateTime documentation
4%% Author: Vadim Zeitlin
5%% Modified by:
6%% Created: 07.03.00
7%% RCS-ID: $Id$
8%% Copyright: (c) Vadim Zeitlin
f6bcfd97 9%% License: wxWindows license
d7da9756
VZ
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxDateTime}}\label{wxdatetime}
13
14wxDateTime class represents an absolute moment in the time.
15
16\wxheading{Types}
17
18The type {\tt wxDateTime\_t} is typedefed as {\tt unsigned short} and is used
19to contain the number of years, hours, minutes, seconds and milliseconds.
20
21\wxheading{Constants}
22
66f55ec6 23Global constant {\tt wxDefaultDateTime} and synonym for it {\tt wxInvalidDateTime} are defined. This constant will be different from any valid
d7da9756
VZ
24wxDateTime object.
25
26All the following constants are defined inside wxDateTime class (i.e., to refer to
27them you should prepend their names with {\tt wxDateTime::}).
28
fa482912 29Time zone symbolic names:
d7da9756
VZ
30
31\begin{verbatim}
32 enum TZ
33 {
34 // the time in the current time zone
35 Local,
36
37 // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
38 // consequent numbers, so writing something like `GMT0 + offset' is
39 // safe if abs(offset) <= 12
40
41 // underscore stands for minus
42 GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
43 GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
44 GMT0,
45 GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
46 GMT7, GMT8, GMT9, GMT10, GMT11, GMT12,
47 // Note that GMT12 and GMT_12 are not the same: there is a difference
48 // of exactly one day between them
49
50 // some symbolic names for TZ
51
52 // Europe
53 WET = GMT0, // Western Europe Time
54 WEST = GMT1, // Western Europe Summer Time
55 CET = GMT1, // Central Europe Time
56 CEST = GMT2, // Central Europe Summer Time
57 EET = GMT2, // Eastern Europe Time
58 EEST = GMT3, // Eastern Europe Summer Time
59 MSK = GMT3, // Moscow Time
60 MSD = GMT4, // Moscow Summer Time
61
62 // US and Canada
63 AST = GMT_4, // Atlantic Standard Time
64 ADT = GMT_3, // Atlantic Daylight Time
65 EST = GMT_5, // Eastern Standard Time
66 EDT = GMT_4, // Eastern Daylight Saving Time
67 CST = GMT_6, // Central Standard Time
68 CDT = GMT_5, // Central Daylight Saving Time
69 MST = GMT_7, // Mountain Standard Time
70 MDT = GMT_6, // Mountain Daylight Saving Time
71 PST = GMT_8, // Pacific Standard Time
72 PDT = GMT_7, // Pacific Daylight Saving Time
73 HST = GMT_10, // Hawaiian Standard Time
74 AKST = GMT_9, // Alaska Standard Time
75 AKDT = GMT_8, // Alaska Daylight Saving Time
76
77 // Australia
78
79 A_WST = GMT8, // Western Standard Time
80 A_CST = GMT12 + 1, // Central Standard Time (+9.5)
81 A_EST = GMT10, // Eastern Standard Time
82 A_ESST = GMT11, // Eastern Summer Time
83
84 // Universal Coordinated Time = the new and politically correct name
85 // for GMT
86 UTC = GMT0
87 };
88\end{verbatim}
89
90Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
f6bcfd97 91Inv\_Month for an invalid.month value are the values of {\tt wxDateTime::Month}
d7da9756
VZ
92enum.
93
f6bcfd97 94Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv\_WeekDay are the values in
d7da9756
VZ
95{\tt wxDateTime::WeekDay} enum.
96
97Finally, Inv\_Year is defined to be an invalid value for year parameter.
98
f6bcfd97
BP
99\helpref{GetMonthName()}{wxdatetimegetmonthname} and
100\helpref{GetWeekDayName}{wxdatetimegetweekdayname} functions use the followign
101flags:
102
103\begin{verbatim}
104 enum NameFlags
105 {
106 Name_Full = 0x01, // return full name
107 Name_Abbr = 0x02 // return abbreviated name
108 };
109\end{verbatim}
110
111Several functions accept an extra parameter specifying the calendar to use
112(although most of them only support now the Gregorian calendar). This
113parameters is one of the following values:
114
115\begin{verbatim}
116 enum Calendar
117 {
118 Gregorian, // calendar currently in use in Western countries
119 Julian // calendar in use since -45 until the 1582 (or later)
120 };
121\end{verbatim}
122
d3c7cfeb
JS
123Date calculations often depend on the country and wxDateTime allows to set the
124country whose conventions should be used using
f6bcfd97
BP
125\helpref{SetCountry}{wxdatetimesetcountry}. It takes one of the following
126values as parameter:
127
128\begin{verbatim}
129 enum Country
130 {
131 Country_Unknown, // no special information for this country
132 Country_Default, // set the default country with SetCountry() method
133 // or use the default country with any other
134
135 Country_WesternEurope_Start,
136 Country_EEC = Country_WesternEurope_Start,
137 France,
138 Germany,
139 UK,
140 Country_WesternEurope_End = UK,
141
142 Russia,
143
144 USA
145 };
146\end{verbatim}
147
cdfb1ae1
VZ
148Different parts of the world use different conventions for the week start.
149In some countries, the week starts on Sunday, while in others -- on Monday.
f6bcfd97 150The ISO standard doesn't address this issue, so we support both conventions in
d3c7cfeb 151the functions whose result depends on it (\helpref{GetWeekOfYear}{wxdatetimegetweekofyear} and
f6bcfd97
BP
152\helpref{GetWeekOfMonth}{wxdatetimegetweekofmonth}).
153
154The desired behvaiour may be specified by giving one of the following
155constants as argument to these functions:
156
157\begin{verbatim}
158 enum WeekFlags
159 {
160 Default_First, // Sunday_First for US, Monday_First for the rest
161 Monday_First, // week starts with a Monday
162 Sunday_First // week starts with a Sunday
163 };
164\end{verbatim}
165
d7da9756
VZ
166\wxheading{Derived from}
167
168No base class
169
170\wxheading{Include files}
171
172<wx/datetime.h>
173
174\wxheading{See also}
175
f6bcfd97 176\helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
df05cdc5
VZ
177\helpref{wxTimeSpan}{wxtimespan},\rtfsp
178\helpref{wxDateSpan}{wxdatespan},\rtfsp
d7da9756
VZ
179\helpref{wxCalendarCtrl}{wxcalendarctrl}
180
181\latexignore{\rtfignore{\wxheading{Function groups}}}
182
183\membersection{Static functions}
184
fa482912 185For convenience, all static functions are collected here. These functions
d7da9756
VZ
186either set or return the static variables of wxDateSpan (the country), return
187the current moment, year, month or number of days in it, or do some general
188calendar-related actions.
189
f6bcfd97
BP
190Please note that although several function accept an extra {\it Calendar}
191parameter, it is currently ignored as only the Gregorian calendar is
192supported. Future versions will support other calendars.
193
d3c7cfeb 194\pythonnote{These methods are standalone functions named
e7240349 195{\tt wxDateTime\_<StaticMethodName>} in wxPython.}
f6bcfd97 196
d7da9756
VZ
197\helpref{SetCountry}{wxdatetimesetcountry}\\
198\helpref{GetCountry}{wxdatetimegetcountry}\\
199\helpref{IsWestEuropeanCountry}{wxdatetimeiswesteuropeancountry}\\
200\helpref{GetCurrentYear}{wxdatetimegetcurrentyear}\\
201\helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
202\helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
203\helpref{IsLeapYear}{wxdatetimeisleapyear}\\
204\helpref{GetCentury}{wxdatetimegetcentury}\\
205\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
206\helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
207\helpref{GetMonthName}{wxdatetimegetmonthname}\\
208\helpref{GetWeekDayName}{wxdatetimegetweekdayname}\\
209\helpref{GetAmPmStrings}{wxdatetimegetampmstrings}\\
210\helpref{IsDSTApplicable}{wxdatetimeisdstapplicable}\\
211\helpref{GetBeginDST}{wxdatetimegetbegindst}\\
212\helpref{GetEndDST}{wxdatetimegetenddst}\\
213\helpref{Now}{wxdatetimenow}\\
f6bcfd97 214\helpref{UNow}{wxdatetimeunow}\\
d7da9756
VZ
215\helpref{Today}{wxdatetimetoday}
216
217\membersection{Constructors, assignment operators and setters}
218
f6bcfd97
BP
219Constructors and various {\tt Set()} methods are collected here. If you
220construct a date object from separate values for day, month and year, you
221should use \helpref{IsValid}{wxdatetimeisvalid} method to check that the
222values were correct as constructors can not return an error code.
223
224\helpref{wxDateTime()}{wxdatetimewxdatetimedef}\\
225\helpref{wxDateTime(time\_t)}{wxdatetimewxdatetimetimet}\\
226\helpref{wxDateTime(struct tm)}{wxdatetimewxdatetimetm}\\
227%\helpref{wxDateTime(struct Tm)}{wxdatetimewxdatetimetm} - Tm not documented yet\\
228\helpref{wxDateTime(double jdn)}{wxdatetimewxdatetimejdn}\\
229\helpref{wxDateTime(h, m, s, ms)}{wxdatetimewxdatetimetime}\\
230\helpref{wxDateTime(day, mon, year, h, m, s, ms)}{wxdatetimewxdatetimedate}\\
231\helpref{SetToCurrent}{wxdatetimesettocurrent}\\
232\helpref{Set(time\_t)}{wxdatetimesettimet}\\
233\helpref{Set(struct tm)}{wxdatetimesettm}\\
234%\helpref{Set(struct Tm)}{wxdatetimesettm} - Tm not documented yet\\
235\helpref{Set(double jdn)}{wxdatetimesetjdn}\\
236\helpref{Set(h, m, s, ms)}{wxdatetimesettime}\\
237\helpref{Set(day, mon, year, h, m, s, ms)}{wxdatetimesetdate}\\
238\helpref{ResetTime}{wxdatetimeresettime}\\
239\helpref{SetYear}{wxdatetimesetyear}\\
240\helpref{SetMonth}{wxdatetimesetmonth}\\
241\helpref{SetDay}{wxdatetimesetdate}\\
242\helpref{SetHour}{wxdatetimesethour}\\
243\helpref{SetMinute}{wxdatetimesetminute}\\
244\helpref{SetSecond}{wxdatetimesetsecond}\\
245\helpref{SetMillisecond}{wxdatetimesetmillisecond}\\
246\helpref{operator$=$(time\_t)}{wxdatetimeoperatoreqtimet}\\
247\helpref{operator$=$(struct tm)}{wxdatetimeoperatoreqtm}
248%\helpref{operator$=$(struct Tm)}{wxdatetimeoperatortm2}
249
d7da9756
VZ
250\membersection{Accessors}
251
f6bcfd97 252Here are the trivial accessors. Other functions, which might have to perform
d3c7cfeb 253some more complicated calculations to find the answer are under the
f6bcfd97
BP
254\helpref{Calendar calculations}{wxdatetimecalculations} section.
255
256\helpref{IsValid}{wxdatetimeisvalid}\\
257\helpref{GetTicks}{wxdatetimegetticks}\\
258\helpref{GetYear}{wxdatetimegetyear}\\
259\helpref{GetMonth}{wxdatetimegetmonth}\\
260\helpref{GetDay}{wxdatetimegetday}\\
261\helpref{GetWeekDay}{wxdatetimegetweekday}\\
262\helpref{GetHour}{wxdatetimegethour}\\
cdfb1ae1 263\helpref{GetMinute}{wxdatetimegetminute}\\
f6bcfd97
BP
264\helpref{GetSecond}{wxdatetimegetsecond}\\
265\helpref{GetMillisecond}{wxdatetimegetmillisecond}\\
266\helpref{GetDayOfYear}{wxdatetimegetdayofyear}\\
267\helpref{GetWeekOfYear}{wxdatetimegetweekofyear}\\
268\helpref{GetWeekOfMonth}{wxdatetimegetweekofmonth}\\
269\helpref{GetYearDay}{wxdatetimegetyearday}\\
270\helpref{IsWorkDay}{wxdatetimeisworkday}\\
271\helpref{IsGregorianDate}{wxdatetimeisgregoriandate}
272
d7da9756
VZ
273\membersection{Date comparison}
274
f6bcfd97
BP
275There are several function to allow date comparison. To supplement them, a few
276global operators $>$, $<$ etc taking wxDateTime are defined.
277
278\helpref{IsEqualTo}{wxdatetimeisequalto}\\
279\helpref{IsEarlierThan}{wxdatetimeisearlierthan}\\
280\helpref{IsLaterThan}{wxdatetimeislaterthan}\\
281\helpref{IsStrictlyBetween}{wxdatetimeisstrictlybetween}\\
282\helpref{IsBetween}{wxdatetimeisbetween}\\
283\helpref{IsSameDate}{wxdatetimeissamedate}\\
284\helpref{IsSameTime}{wxdatetimeissametime}\\
285\helpref{IsEqualUpTo}{wxdatetimeisequalupto}
286
d7da9756
VZ
287\membersection{Date arithmetics}
288
f6bcfd97
BP
289These functions carry out \helpref{arithmetics}{tdatearithm} on the wxDateTime
290objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be
291added to wxDateTime, hence all functions are overloaded to accept both
292arguments.
293
294Also, both {\tt Add()} and {\tt Subtract()} have both const and non-const
295version. The first one returns a new obejct which represents the
296sum/difference of the original one with the argument while the second form
297modifies the object to which it is applied. The operators $-=$ and $+=$ are
298defined to be equivalent to the second forms of these functions.
299
300\helpref{Add(wxTimeSpan)}{wxdatetimeaddts}\\
301\helpref{Add(wxDateSpan)}{wxdatetimeaddds}\\
302\helpref{Subtract(wxTimeSpan)}{wxdatetimesubtractts}\\
303\helpref{Subtract(wxDateSpan)}{wxdatetimesubtractds}\\
304\helpref{Subtract(wxDateTime)}{wxdatetimesubtractdt}\\
305\helpref{oparator$+=$(wxTimeSpan)}{wxdatetimeaddts}\\
306\helpref{oparator$+=$(wxDateSpan)}{wxdatetimeaddds}\\
307\helpref{oparator$-=$(wxTimeSpan)}{wxdatetimesubtractts}\\
308\helpref{oparator$-=$(wxDateSpan)}{wxdatetimesubtractds}
309
d7da9756
VZ
310\membersection{Parsing and formatting dates}
311
cdfb1ae1 312These functions convert wxDateTime obejcts to and from text. The
f6bcfd97 313conversions to text are mostly trivial: you can either do it using the default
cdfb1ae1
VZ
314date and time representations for the current locale (
315\helpref{FormatDate}{wxdatetimeformatdate} and
f6bcfd97 316\helpref{FormatTime}{wxdatetimeformattime}), using the international standard
cdfb1ae1
VZ
317representation defined by ISO 8601 (
318\helpref{FormatISODate}{wxdatetimeformatisodate} and
f6bcfd97
BP
319\helpref{FormatISOTime}{wxdatetimeformatisotime}) or by specifying any format
320at all and using \helpref{Format}{wxdatetimeformat} directly.
321
322The conversions from text are more interesting, as there are much more
cdfb1ae1 323possibilities to care about. The simplest cases can be taken care of with
f6bcfd97
BP
324\helpref{ParseFormat}{wxdatetimeparseformat} which can parse any date in the
325given (rigid) format. \helpref{ParseRfc822Date}{wxdatetimeparserfc822date} is
cdfb1ae1 326another function for parsing dates in predefined format -- the one of RFC 822
f6bcfd97 327which (still...) defines the format of email messages on the Internet. This
cdfb1ae1 328format can not be described with {\tt strptime(3)}-like format strings used by
f6bcfd97
BP
329\helpref{Format}{wxdatetimeformat}, hence the need for a separate function.
330
d3c7cfeb 331But the most interesting functions are
cdfb1ae1 332\helpref{ParseTime}{wxdatetimeparsetime},
d3c7cfeb 333\helpref{ParseDate}{wxdatetimeparsedate} and
cdfb1ae1
VZ
334\helpref{ParseDateTime}{wxdatetimeparsedatetime}. They try to parse the date
335ans time (or only one of them) in `free' format, i.e. allow them to be
336specified in any of possible ways. These functions will usually be used to
337parse the (interactive) user input which is not bound to be in any predefined
338format. As an example, \helpref{ParseDateTime}{wxdatetimeparsedatetime} can
339parse the strings such as {\tt "tomorrow"}, {\tt "March first"} and even
340{\tt "next Sunday"}.
f6bcfd97
BP
341
342\helpref{ParseRfc822Date}{wxdatetimeparserfc822date}\\
343\helpref{ParseFormat}{wxdatetimeparseformat}\\
344\helpref{ParseDateTime}{wxdatetimeparsedatetime}\\
345\helpref{ParseDate}{wxdatetimeparsedate}\\
346\helpref{ParseTime}{wxdatetimeparsetime}\\
347\helpref{Format}{wxdatetimeformat}\\
348\helpref{FormatDate}{wxdatetimeformatdate}\\
349\helpref{FormatTime}{wxdatetimeformattime}\\
350\helpref{FormatISODate}{wxdatetimeformatisodate}\\
351\helpref{FormatISOTime}{wxdatetimeformatisotime}
352
353\membersection{Calendar calculations}\label{wxdatetimecalculations}
354
355The functions in this section perform the basic calendar calculations, mostly
356related to the week days. They allow to find the given week day in the
357week with given number (either in the month or in the year) and so on.
358
359All (non-const) functions in this section don't modify the time part of the
cdfb1ae1 360wxDateTime -- they only work with the date part of it.
f6bcfd97
BP
361
362\helpref{SetToWeekDayInSameWeek}{wxdatetimesettoweekdayinsameweek}\\
363\helpref{GetWeekDayInSameWeek}{wxdatetimegetweekdayinsameweek}\\
364\helpref{SetToNextWeekDay}{wxdatetimesettonextweekday}\\
365\helpref{GetNextWeekDay}{wxdatetimegetnextweekday}\\
366\helpref{SetToPrevWeekDay}{wxdatetimesettoprevweekday}\\
367\helpref{GetPrevWeekDay}{wxdatetimegetprevweekday}\\
368\helpref{SetToWeekDay}{wxdatetimesettoweekday}\\
369\helpref{GetWeekDay}{wxdatetimegetweekday2}\\
370\helpref{SetToLastWeekDay}{wxdatetimesettolastweekday}\\
371\helpref{GetLastWeekDay}{wxdatetimegetlastweekday}\\
372\helpref{SetToTheWeek}{wxdatetimesettotheweek}\\
373\helpref{GetWeek}{wxdatetimegetweek}\\
374\helpref{SetToLastMonthDay}{wxdatetimesettolastmonthday}\\
375\helpref{GetLastMonthDay}{wxdatetimegetlastmonthday}\\
376\helpref{SetToYearDay}{wxdatetimesettoyearday}\\
377\helpref{GetYearDay}{wxdatetimegetyearday}
d7da9756
VZ
378
379\membersection{Astronomical/historical functions}
380
f6bcfd97
BP
381Some degree of support for the date units used in astronomy and/or history is
382provided. You can construct a wxDateTime object from a
383\helpref{JDN}{wxdatetimesetjdn} and you may also get its JDN,
384\helpref{MJD}{wxdatetimegetmodifiedjuliandaynumber} or
385\helpref{Rata Die number}{wxdatetimegetratadie} from it.
386
387\helpref{wxDateTime(double jdn)}{wxdatetimewxdatetimejdn}\\
388\helpref{Set(double jdn)}{wxdatetimesetjdn}\\
389\helpref{GetJulianDayNumber}{wxdatetimegetjuliandaynumber}\\
390\helpref{GetJDN}{wxdatetimegetjdn}\\
391\helpref{GetModifiedJulianDayNumber}{wxdatetimegetmodifiedjuliandaynumber}\\
392\helpref{GetMJD}{wxdatetimegetmjd}\\
393\helpref{GetRataDie}{wxdatetimegetratadie}
394
395\membersection{Time zone and DST support}
396
397Please see the \helpref{time zone overview}{tdatetimezones} for more
398information about time zones. ormally, these functions should be rarely used.
399
400\helpref{ToTimezone}{wxdatetimetotimezone}\\
401\helpref{MakeTimezone}{wxdatetimemaketimezone}\\
402\helpref{ToGMT}{wxdatetimetogmt}\\
403\helpref{MakeGMT}{wxdatetimemakegmt}\\
404\helpref{GetBeginDST}{wxdatetimegetbegindst}\\
405\helpref{GetEndDST}{wxdatetimegetenddst}\\
406\helpref{IsDST}{wxdatetimeisdst}
d7da9756
VZ
407
408\helponly{\insertatlevel{2}{
409
410\wxheading{Members}
411
412}}
413
f6bcfd97
BP
414%%%%%%%%%%%%%%%%%%%%%%%%%%% static functions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
415
66f55ec6 416\membersection{wxDateTime::ConvertYearToBC}\label{wxdatetimeconvertyeartobc}
d7da9756 417
66f55ec6 418\func{static int}{ConvertYearToBC}{\param{int }{year}}
d7da9756
VZ
419
420Converts the year in absolute notation (i.e. a number which can be negative,
421positive or zero) to the year in BC/AD notation. For the positive years,
422nothing is done, but the year 0 is year 1 BC and so for other years there is a
423difference of 1.
424
425This function should be used like this:
426
427\begin{verbatim}
428 wxDateTime dt(...);
429 int y = dt.GetYear();
430 printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
431\end{verbatim}
432
66f55ec6 433\membersection{wxDateTime::GetAmPmStrings}\label{wxdatetimegetampmstrings}
d7da9756
VZ
434
435\func{static void}{GetAmPmStrings}{\param{wxString *}{am}, \param{wxString *}{pm}}
436
f6bcfd97
BP
437Returns the translations of the strings {\tt AM} and {\tt PM} used for time
438formatting for the current locale. Either of the pointers may be {\tt NULL} if
439the corresponding value is not needed.
440
66f55ec6 441\membersection{wxDateTime::GetBeginDST}\label{wxdatetimegetbegindst}
d7da9756
VZ
442
443\func{static wxDateTime}{GetBeginDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
444
f6bcfd97
BP
445Get the beginning of DST for the given country in the given year (current one
446by default). This function suffers from limitations described in
447\helpref{DST overview}{tdatedst}.
448
449\wxheading{See also}
450
451\helpref{GetEndDST}{wxdatetimegetenddst}
452
66f55ec6 453\membersection{wxDateTime::GetCountry}\label{wxdatetimegetcountry}
d7da9756
VZ
454
455\func{static Country}{GetCountry}{\void}
456
f6bcfd97
BP
457Returns the current default country. The default country is used for DST
458calculations, for example.
459
460\wxheading{See also}
461
462\helpref{SetCountry}{wxdatetimesetcountry}
463
66f55ec6 464\membersection{wxDateTime::GetCurrentYear}\label{wxdatetimegetcurrentyear}
d7da9756
VZ
465
466\func{static int}{GetCurrentYear}{\param{Calendar }{cal = Gregorian}}
467
f6bcfd97
BP
468Get the current year in given calendar (only Gregorian is currently supported).
469
66f55ec6 470\membersection{wxDateTime::GetCurrentMonth}\label{wxdatetimegetcurrentmonth}
d7da9756
VZ
471
472\func{static Month}{GetCurrentMonth}{\param{Calendar }{cal = Gregorian}}
473
f6bcfd97
BP
474Get the current month in given calendar (only Gregorian is currently supported).
475
66f55ec6 476\membersection{wxDateTime::GetCentury}\label{wxdatetimegetcentury}
d7da9756
VZ
477
478\func{static int}{GetCentury}{\param{int }{year = Inv\_Year}}
479
f6bcfd97
BP
480Get the current century, i.e. first two digits of the year, in given calendar
481(only Gregorian is currently supported).
482
66f55ec6 483\membersection{wxDateTime::GetEndDST}\label{wxdatetimegetenddst}
d7da9756
VZ
484
485\func{static wxDateTime}{GetEndDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
486
f6bcfd97
BP
487Returns the end of DST for the given country in the given year (current one by
488default).
489
490\wxheading{See also}
491
492\helpref{GetBeginDST}{wxdatetimegetbegindst}
493
66f55ec6 494\membersection{wxDateTime::GetMonthName}\label{wxdatetimegetmonthname}
d7da9756
VZ
495
496\func{static wxString}{GetMonthName}{\param{Month }{month}, \param{NameFlags }{flags = Name\_Full}}
497
f6bcfd97
BP
498Gets the full (default) or abbreviated (specify {\tt Name\_Abbr} name of the
499given month.
500
501\wxheading{See also}
502
503\helpref{GetWeekDayName}{wxdatetimegetweekdayname}
504
66f55ec6 505\membersection{wxDateTime::GetNumberOfDays}\label{wxdatetimegetnumberofdays}
d7da9756
VZ
506
507\func{static wxDateTime\_t}{GetNumberOfDays}{\param{int }{year}, \param{Calendar }{cal = Gregorian}}
508
d7da9756
VZ
509\func{static wxDateTime\_t}{GetNumberOfDays}{\param{Month }{month}, \param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}
510
f6bcfd97
BP
511Returns the number of days in the given year or in the given month of the
512year.
513
514The only supported value for {\it cal} parameter is currently {\tt Gregorian}.
515
516\pythonnote{These two methods are named {\tt GetNumberOfDaysInYear}
517and {\tt GetNumberOfDaysInMonth} in wxPython.}
518
66f55ec6 519\membersection{wxDateTime::GetWeekDayName}\label{wxdatetimegetweekdayname}
d7da9756
VZ
520
521\func{static wxString}{GetWeekDayName}{\param{WeekDay }{weekday}, \param{NameFlags }{flags = Name\_Full}}
522
f6bcfd97
BP
523Gets the full (default) or abbreviated (specify {\tt Name\_Abbr} name of the
524given week day.
525
526\wxheading{See also}
527
528\helpref{GetMonthName}{wxdatetimegetmonthname}
529
66f55ec6 530\membersection{wxDateTime::IsLeapYear}\label{wxdatetimeisleapyear}
d7da9756
VZ
531
532\func{static bool}{IsLeapYear}{\param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}
533
f6bcfd97
BP
534Returns {\tt TRUE} if the {\it year} is a leap one in the specified calendar.
535
536This functions supports Gregorian and Julian calendars.
537
66f55ec6 538\membersection{wxDateTime::IsWestEuropeanCountry}\label{wxdatetimeiswesteuropeancountry}
d7da9756
VZ
539
540\func{static bool}{IsWestEuropeanCountry}{\param{Country }{country = Country\_Default}}
541
f6bcfd97
BP
542This function returns {\tt TRUE} if the specified (or default) country is one
543of Western European ones. It is used internally by wxDateTime to determine the
544DST convention and date and time formatting rules.
545
66f55ec6 546\membersection{wxDateTime::IsDSTApplicable}\label{wxdatetimeisdstapplicable}
d7da9756
VZ
547
548\func{static bool}{IsDSTApplicable}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
549
2edb0bde 550Returns {\tt TRUE} if DST was used n the given year (the current one by
f6bcfd97
BP
551default) in the given country.
552
66f55ec6 553\membersection{wxDateTime::Now}\label{wxdatetimenow}
d7da9756
VZ
554
555\func{static wxDateTime}{Now}{\void}
556
2edb0bde 557Returns the object corresponding to the current time.
f6bcfd97
BP
558
559Example:
560
561\begin{verbatim}
562 wxDateTime now = wxDateTime::Now();
563 printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
564\end{verbatim}
565
566Note that this function is accurate up to second:
567\helpref{wxDateTime::UNow}{wxdatetimeunow} should be used for better precision
2edb0bde 568(but it is less efficient and might not be available on all platforms).
f6bcfd97
BP
569
570\wxheading{See also}
571
572\helpref{Today}{wxdatetimetoday}
573
66f55ec6 574\membersection{wxDateTime::SetCountry}\label{wxdatetimesetcountry}
d7da9756
VZ
575
576\func{static void}{SetCountry}{\param{Country }{country}}
577
f6bcfd97
BP
578Sets the country to use by default. This setting influences the DST
579calculations, date formatting and other things.
580
581The possible values for {\it country} parameter are enumerated in
582\helpref{wxDateTime constants section}{wxdatetime}.
583
584\wxheading{See also}
585
586\helpref{GetCountry}{wxdatetimegetcountry}
587
66f55ec6 588\membersection{wxDateTime::Today}\label{wxdatetimetoday}
d7da9756
VZ
589
590\func{static wxDateTime}{Today}{\void}
591
f6bcfd97
BP
592Returns the object corresponding to the midnight of the current day (i.e. the
593same as \helpref{Now()}{wxdatetimenow}, but the time part is set to $0$).
594
595\wxheading{See also}
596
597\helpref{Now}{wxdatetimenow}
598
599\membersection{wxDateTime::UNow}\label{wxdatetimeunow}
600
601\func{static wxDateTime}{UNow}{\void}
602
2edb0bde 603Returns the object corresponding to the current time including the
f6bcfd97
BP
604milliseconds if a function to get time with such precision is available on the
605current platform (supported under most Unices and Win32).
606
607\wxheading{See also}
608
609\helpref{Now}{wxdatetimenow}
610
611%%%%%%%%%%%%%%%%%%%%%%%%%%% constructors &c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
612
613\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimedef}
614
615\func{}{wxDateTime}{\void}
616
617Default constructor. Use one of {\tt Set()} functions to initialize the object
618later.
619
620\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimetimet}
621
622\func{wxDateTime\&}{wxDateTime}{\param{time\_t }{timet}}
623
624Same as \helpref{Set}{wxdatetimewxdatetimetimet}.
625
626\pythonnote{This constructor is named {\tt wxDateTimeFromTimeT} in wxPython.}
627
628\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimetm}
629
630\func{wxDateTime\&}{wxDateTime}{\param{const struct tm\& }{tm}}
631
632Same as \helpref{Set}{wxdatetimewxdatetimetm}
633
634\pythonnote{Unsupported.}
635
636\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimejdn}
637
638\func{wxDateTime\&}{wxDateTime}{\param{double }{jdn}}
639
640Same as \helpref{Set}{wxdatetimewxdatetimejdn}
641
642\pythonnote{This constructor is named {\tt wxDateTimeFromJDN} in wxPython.}
643
644\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimetime}
645
646\func{wxDateTime\&}{wxDateTime}{\param{wxDateTime\_t }{hour}, \param{wxDateTime\_t }{minute = 0}, \param{wxDateTime\_t }{second = 0}, \param{wxDateTime\_t }{millisec = 0}}
647
648Same as \helpref{Set}{wxdatetimewxdatetimetime}
649
650\pythonnote{This constructor is named {\tt wxDateTimeFromHMS} in wxPython.}
651
652\membersection{wxDateTime::wxDateTime}\label{wxdatetimewxdatetimedate}
653
e98a0358 654\func{wxDateTime\&}{wxDateTime}{\param{wxDateTime\_t }{day}, \param{Month }{month = Inv\_Month}, \param{int}{ Inv\_Year},
a9d171bd 655\param{wxDateTime\_t }{hour = 0}, \param{wxDateTime\_t }{minute = 0}, \param{wxDateTime\_t }{second = 0}, \param{wxDateTime\_t }{millisec = 0}}
f6bcfd97
BP
656
657Same as \helpref{Set}{wxdatetimesetdate}
658
659\pythonnote{This constructor is named {\tt wxDateTimeFromDMY} in wxPython.}
660
661\membersection{wxDateTime::SetToCurrent}\label{wxdatetimesettocurrent}
662
7af3ca16 663\func{wxDateTime\&}{SetToCurrent}{\void}
f6bcfd97
BP
664
665Sets the date and time of to the current values. Same as assigning the result
666of \helpref{Now()}{wxdatetimenow} to this object.
667
668\membersection{wxDateTime::Set}\label{wxdatetimesettimet}
669
670\func{wxDateTime\&}{Set}{\param{time\_t }{timet}}
671
672Constructs the object from {\it timet} value holding the number of seconds
673since Jan 1, 1970.
674
675\pythonnote{This method is named {\tt SetTimeT} in wxPython.}
676
677\membersection{wxDateTime::Set}\label{wxdatetimesettm}
678
679\func{wxDateTime\&}{Set}{\param{const struct tm\& }{tm}}
680
2edb0bde 681Sets the date and time from the broken down representation in the standard
f6bcfd97
BP
682{\tt tm} structure.
683
684\pythonnote{Unsupported.}
685
686\membersection{wxDateTime::Set}\label{wxdatetimesetjdn}
687
688\func{wxDateTime\&}{Set}{\param{double }{jdn}}
689
690Sets the date from the so-called {\it Julian Day Number}.
691
692By definition, the Julian Day Number, usually abbreviated as JDN, of a
693particular instant is the fractional number of days since 12 hours Universal
2edb0bde 694Coordinated Time (Greenwich mean noon) on January 1 of the year -4712 in the
f6bcfd97
BP
695Julian proleptic calendar.
696
697\pythonnote{This method is named {\tt SetJDN} in wxPython.}
698
699\membersection{wxDateTime::Set}\label{wxdatetimesettime}
700
701\func{wxDateTime\&}{Set}{\param{wxDateTime\_t }{hour}, \param{wxDateTime\_t }{minute = 0}, \param{wxDateTime\_t }{second = 0}, \param{wxDateTime\_t }{millisec = 0}}
702
703Sets the date to be equal to \helpref{Today}{wxdatetimetoday} and the time
704from supplied parameters.
705
706\pythonnote{This method is named {\tt SetHMS} in wxPython.}
707
708\membersection{wxDateTime::Set}\label{wxdatetimesetdate}
709
fafcf127 710\func{wxDateTime\&}{Set}{\param{wxDateTime\_t }{day}, \param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}, \param{wxDateTime\_t }{hour = 0}, \param{wxDateTime\_t }{minute = 0}, \param{wxDateTime\_t }{second = 0}, \param{wxDateTime\_t }{millisec = 0}}
f6bcfd97
BP
711
712Sets the date and time from the parameters.
713
714\membersection{wxDateTime::ResetTime}\label{wxdatetimeresettime}
715
716\func{wxDateTime\&}{ResetTime}{\void}
717
718Reset time to midnight (00:00:00) without changing the date.
719
720\membersection{wxDateTime::SetYear}\label{wxdatetimesetyear}
721
722\func{wxDateTime\&}{SetYear}{\param{int }{year}}
723
724Sets the year without changing other date components.
725
726\membersection{wxDateTime::SetMonth}\label{wxdatetimesetmonth}
727
728\func{wxDateTime\&}{SetMonth}{\param{Month }{month}}
729
730Sets the month without changing other date components.
731
732\membersection{wxDateTime::SetDay}\label{wxdatetimesetday}
733
734\func{wxDateTime\&}{SetDay}{\param{wxDateTime\_t }{day}}
735
736Sets the day without changing other date components.
737
738\membersection{wxDateTime::SetHour}\label{wxdatetimesethour}
739
740\func{wxDateTime\&}{SetHour}{\param{wxDateTime\_t }{hour}}
741
742Sets the hour without changing other date components.
743
744\membersection{wxDateTime::SetMinute}\label{wxdatetimesetminute}
745
746\func{wxDateTime\&}{SetMinute}{\param{wxDateTime\_t }{minute}}
747
748Sets the minute without changing other date components.
749
750\membersection{wxDateTime::SetSecond}\label{wxdatetimesetsecond}
751
752\func{wxDateTime\&}{SetSecond}{\param{wxDateTime\_t }{second}}
753
754Sets the second without changing other date components.
755
756\membersection{wxDateTime::SetMillisecond}\label{wxdatetimesetmillisecond}
757
758\func{wxDateTime\&}{SetMillisecond}{\param{wxDateTime\_t }{millisecond}}
759
760Sets the millisecond without changing other date components.
761
762\membersection{wxDateTime::operator$=$}\label{wxdatetimeoperatoreqtimet}
763
764\func{wxDateTime\&}{operator}{\param{time\_t }{timet}}
765
766Same as \helpref{Set}{wxdatetimesettimet}.
767
768\membersection{wxDateTime::operator$=$}\label{wxdatetimeoperatoreqtm}
769
770\func{wxDateTime\&}{operator}{\param{const struct tm\& }{tm}}
771
772Same as \helpref{Set}{wxdatetimesettm}.
773
774%%%%%%%%%%%%%%%%%%%%%%%%%%% accessors %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
775
776\membersection{wxDateTime::IsValid}\label{wxdatetimeisvalid}
777
778\constfunc{bool}{IsValid}{\void}
779
780Returns {\tt TRUE} if the object represents a valid time moment.
781
782\membersection{wxDateTime::GetTm}\label{wxdatetimegettm}
783
784\constfunc{Tm}{GetTm}{\param{const TimeZone\& }{tz = Local}}
785
786Returns broken down representation of the date and time.
787
788\membersection{wxDateTime::GetTicks}\label{wxdatetimegetticks}
789
790\constfunc{time\_t}{GetTicks}{\void}
791
792Returns the number of seconds since Jan 1, 1970. An assert failure will occur
793if the date is not in the range covered by {\tt time\_t} type.
794
795\membersection{wxDateTime::GetYear}\label{wxdatetimegetyear}
796
797\constfunc{int}{GetYear}{\param{const TimeZone\& }{tz = Local}}
798
799Returns the year in the given timezone (local one by default).
800
801\membersection{wxDateTime::GetMonth}\label{wxdatetimegetmonth}
802
803\constfunc{Month}{GetMonth}{\param{const TimeZone\& }{tz = Local}}
804
805Returns the month in the given timezone (local one by default).
806
807\membersection{wxDateTime::GetDay}\label{wxdatetimegetday}
808
809\constfunc{wxDateTime\_t}{GetDay}{\param{const TimeZone\& }{tz = Local}}
810
811Returns the day in the given timezone (local one by default).
812
813\membersection{wxDateTime::GetWeekDay}\label{wxdatetimegetweekday}
814
815\constfunc{WeekDay}{GetWeekDay}{\param{const TimeZone\& }{tz = Local}}
816
817Returns the week day in the given timezone (local one by default).
818
819\membersection{wxDateTime::GetHour}\label{wxdatetimegethour}
820
821\constfunc{wxDateTime\_t}{GetHour}{\param{const TimeZone\& }{tz = Local}}
822
823Returns the hour in the given timezone (local one by default).
824
825\membersection{wxDateTime::GetMinute}\label{wxdatetimegetminute}
826
827\constfunc{wxDateTime\_t}{GetMinute}{\param{const TimeZone\& }{tz = Local}}
828
829Returns the minute in the given timezone (local one by default).
830
831\membersection{wxDateTime::GetSecond}\label{wxdatetimegetsecond}
832
833\constfunc{wxDateTime\_t}{GetSecond}{\param{const TimeZone\& }{tz = Local}}
834
835Returns the seconds in the given timezone (local one by default).
836
837\membersection{wxDateTime::GetMillisecond}\label{wxdatetimegetmillisecond}
838
839\constfunc{wxDateTime\_t}{GetMillisecond}{\param{const TimeZone\& }{tz = Local}}
840
841Returns the milliseconds in the given timezone (local one by default).
842
843\membersection{wxDateTime::GetDayOfYear}\label{wxdatetimegetdayofyear}
844
845\constfunc{wxDateTime\_t}{GetDayOfYear}{\param{const TimeZone\& }{tz = Local}}
846
847Returns the day of the year (in $1\ldots366$ range) in the given timezone
848(local one by default).
849
850\membersection{wxDateTime::GetWeekOfYear}\label{wxdatetimegetweekofyear}
851
852\constfunc{wxDateTime\_t}{GetWeekOfYear}{\param{WeekFlags }{flags = Monday\_First}, \param{const TimeZone\& }{tz = Local}}
853
854Returns the number of the week of the year this date is in. The first week of
855the year is, according to international standards, the one containing Jan 4.
856The week number is in $1\ldots53$ range ($52$ for non leap years).
857
858The function depends on the \helpref{week start}{wxdatetime} convention
859specified by the {\it flags} argument.
860
861\membersection{wxDateTime::GetWeekOfMonth}\label{wxdatetimegetweekofmonth}
862
863\constfunc{wxDateTime\_t}{GetWeekOfMonth}{\param{WeekFlags }{flags = Monday\_First}, \param{const TimeZone\& }{tz = Local}}
864
865Returns the ordinal number of the week in the month (in $1\ldots5$ range).
866
867As \helpref{GetWeekOfYear}{wxdatetimegetweekofyear}, this function supports
868both conventions for the week start. See the description of these
869\helpref{week start}{wxdatetime} conventions.
870
871\membersection{wxDateTime::IsWorkDay}\label{wxdatetimeisworkday}
872
873\constfunc{bool}{IsWorkDay}{\param{Country }{country = Country\_Default}}
874
875Returns {\tt TRUE} is this day is not a holiday in the given country.
876
877\membersection{wxDateTime::IsGregorianDate}\label{wxdatetimeisgregoriandate}
878
879\constfunc{bool}{IsGregorianDate}{\param{GregorianAdoption }{country = Gr\_Standard}}
880
881Returns {\tt TRUE} if the given date os later than the date of adoption of the
882Gregorian calendar in the given country (and hence the Gregorian calendar
883calculations make sense for it).
884
885%%%%%%%%%%%%%%%%%%%%%%%%%%% comparison %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
886
887\membersection{wxDateTime::IsEqualTo}\label{wxdatetimeisequalto}
888
7af3ca16 889\constfunc{bool}{IsEqualTo}{\param{const wxDateTime\& }{datetime}}
f6bcfd97
BP
890
891Returns {\tt TRUE} if the two dates are strictly identical.
892
893\membersection{wxDateTime::IsEarlierThan}\label{wxdatetimeisearlierthan}
894
7af3ca16 895\constfunc{bool}{IsEarlierThan}{\param{const wxDateTime\& }{datetime}}
f6bcfd97
BP
896
897Returns {\tt TRUE} if this date precedes the given one.
898
899\membersection{wxDateTime::IsLaterThan}\label{wxdatetimeislaterthan}
900
7af3ca16 901\constfunc{bool}{IsLaterThan}{\param{const wxDateTime\& }{datetime}}
f6bcfd97
BP
902
903Returns {\tt TRUE} if this date is later than the given one.
904
905\membersection{wxDateTime::IsStrictlyBetween}\label{wxdatetimeisstrictlybetween}
906
7af3ca16 907\constfunc{bool}{IsStrictlyBetween}{\param{const wxDateTime\& }{t1}, \param{const wxDateTime\& }{t2}}
f6bcfd97
BP
908
909Returns {\tt TRUE} if this date lies strictly between the two others,
910
911\wxheading{See also}
912
913\helpref{IsBetween}{wxdatetimeisbetween}
914
915\membersection{wxDateTime::IsBetween}\label{wxdatetimeisbetween}
916
7af3ca16 917\constfunc{bool}{IsBetween}{\param{const wxDateTime\& }{t1}, \param{const wxDateTime\& }{t2}}
f6bcfd97
BP
918
919Returns {\tt TRUE} if \helpref{IsStrictlyBetween}{wxdatetimeisstrictlybetween}
2edb0bde 920is {\tt TRUE} or if the date is equal to one of the limit values.
f6bcfd97
BP
921
922\wxheading{See also}
923
924\helpref{IsStrictlyBetween}{wxdatetimeisstrictlybetween}
925
926\membersection{wxDateTime::IsSameDate}\label{wxdatetimeissamedate}
927
7af3ca16 928\constfunc{bool}{IsSameDate}{\param{const wxDateTime\& }{dt}}
f6bcfd97
BP
929
930Returns {\tt TRUE} if the date is the same without comparing the time parts.
931
932\membersection{wxDateTime::IsSameTime}\label{wxdatetimeissametime}
933
7af3ca16 934\constfunc{bool}{IsSameTime}{\param{const wxDateTime\& }{dt}}
f6bcfd97
BP
935
936Returns {\tt TRUE} if the time is the same (although dates may differ).
937
938\membersection{wxDateTime::IsEqualUpTo}\label{wxdatetimeisequalupto}
939
940\constfunc{bool}{IsEqualUpTo}{\param{const wxDateTime\& }{dt}, \param{const wxTimeSpan\& }{ts}}
941
942Returns {\tt TRUE} if the date is equal to another one up to the given time
943interval, i.e. if the absolute difference between the two dates is less than
944this interval.
945
946%%%%%%%%%%%%%%%%%%%%%%%%%%% arithmetics %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
947
948\membersection{wxDateTime::Add}\label{wxdatetimeaddts}
949
950\constfunc{wxDateTime}{Add}{\param{const wxTimeSpan\& }{diff}}
951
952\func{wxDateTime\&}{Add}{\param{const wxTimeSpan\& }{diff}}
953
954\func{wxDateTime\&}{operator$+=$}{\param{const wxTimeSpan\& }{diff}}
955
956Adds the given time span to this object.
957
958\pythonnote{This method is named {\tt AddTS} in wxPython.}
959
960\membersection{wxDateTime::Subtract}\label{wxdatetimesubtractts}
961
962\constfunc{wxDateTime}{Subtract}{\param{const wxTimeSpan\& }{diff}}
963
964\func{wxDateTime\&}{Subtract}{\param{const wxTimeSpan\& }{diff}}
965
966\func{wxDateTime\&}{operator$-=$}{\param{const wxTimeSpan\& }{diff}}
967
968Subtracts the given time span from this object.
969
970\pythonnote{This method is named {\tt SubtractTS} in wxPython.}
971
972\membersection{wxDateTime::Add}\label{wxdatetimeaddds}
973
974\constfunc{wxDateTime}{Add}{\param{const wxDateSpan\& }{diff}}
975
976\func{wxDateTime\&}{Add}{\param{const wxDateSpan\& }{diff}}
977
978\func{wxDateTime\&}{operator$+=$}{\param{const wxDateSpan\& }{diff}}
979
980Adds the given date span to this object.
981
982\pythonnote{This method is named {\tt AddDS} in wxPython.}
983
984\membersection{wxDateTime::Subtract}\label{wxdatetimesubtractds}
985
986\constfunc{wxDateTime}{Subtract}{\param{const wxDateSpan\& }{diff}}
987
988\func{wxDateTime\&}{Subtract}{\param{const wxDateSpan\& }{diff}}
989
990\func{wxDateTime\&}{operator$-=$}{\param{const wxDateSpan\& }{diff}}
991
992Subtracts the given date span from this object.
993
994\pythonnote{This method is named {\tt SubtractDS} in wxPython.}
995
996\membersection{wxDateTime::Subtract}\label{wxdatetimesubtractdt}
997
998\constfunc{wxTimeSpan}{Subtract}{\param{const wxDateTime\& }{dt}}
999
1000Subtracts another date from this one and returns the difference between them
1001as wxTimeSpan.
1002
1003%%%%%%%%%%%%%%%%%%%%%%%%%%% parsing/formatting %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1004
1005\membersection{wxDateTime::ParseRfc822Date}\label{wxdatetimeparserfc822date}
1006
1007\func{const wxChar *}{ParseRfc822Date}{\param{const wxChar* }{date}}
1008
1009Parses the string {\it date} looking for a date formatted according to the RFC
1010822 in it. The exact description of this format may, of course, be found in
1011the RFC (section $5$), but, briefly, this is the format used in the headers of
1012Internet email messages and one of the most common strings expressing date in
1013this format may be something like {\tt "Sat, 18 Dec 1999 00:48:30 +0100"}.
1014
1015Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
1016the character immediately following the part of the string which could be
1017parsed. If the entire string contains only the date in RFC 822 format,
1018the returned pointer will be pointing to a {\tt NUL} character.
1019
2edb0bde 1020This function is intentionally strict, it will return an error for any string
f6bcfd97
BP
1021which is not RFC 822 compliant. If you need to parse date formatted in more
1022free ways, you should use \helpref{ParseDateTime}{wxdatetimeparsedatetime} or
1023\helpref{ParseDate}{wxdatetimeparsedate} instead.
1024
1025\membersection{wxDateTime::ParseFormat}\label{wxdatetimeparseformat}
1026
1027\func{const wxChar *}{ParseFormat}{\param{const wxChar *}{date}, \param{const wxChar *}{format = "\%c"}, \param{const wxDateTime\& }{dateDef = wxDefaultDateTime}}
1028
1029This function parses the string {\it date} according to the given
1030{\it format}. The system {\tt strptime(3)} function is used whenever available,
1031but even if it is not, this function is still implemented (although support
1032for locale-dependent format specificators such as {\tt "\%c"}, {\tt "\%x"} or
1033{\tt "\%X"} may be not perfect). This function does handle the month and
1034weekday names in the current locale on all platforms, however.
1035
1036Please the description of ANSI C function {\tt strftime(3)} for the syntax of
1037the format string.
1038
1039The {\it dateDef} parameter is used to fill in the fields which could not be
1040determined from the format string. For example, if the format is {\tt "\%d"}
1041(the day of the month), the month and the year are taken from {\it dateDef}.
1042If it is not specified, \helpref{Today}{wxdatetimetoday} is used as the
1043default date.
1044
1045Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
1046the character which stopped the scan.
1047
1048\membersection{wxDateTime::ParseDateTime}\label{wxdatetimeparsedatetime}
1049
1050\func{const wxChar *}{ParseDateTime}{\param{const wxChar *}{datetime}}
1051
1052Parses the string {\it datetime} containing the date and time in free format.
1053This function tries as hard as it can to interpret the given string as date
1054and time. Unlike \helpref{ParseRfc822Date}{wxdatetimeparserfc822date}, it
1055will accept anything that may be accepted and will only reject strings which
1056can not be parsed in any way at all.
1057
1058Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
1059the character which stopped the scan.
1060
1061\membersection{wxDateTime::ParseDate}\label{wxdatetimeparsedate}
1062
1063\func{const wxChar *}{ParseDate}{\param{const wxChar *}{date}}
1064
1065This function is like \helpref{ParseDateTime}{wxdatetimeparsedatetime}, but it
d3c7cfeb 1066only allows the date to be specified. It is thus less flexible then
f6bcfd97
BP
1067\helpref{ParseDateTime}{wxdatetimeparsedatetime}, but also has less chances to
1068misinterpret the user input.
1069
1070Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
1071the character which stopped the scan.
1072
1073\membersection{wxDateTime::ParseTime}\label{wxdatetimeparsetime}
1074
1075\func{const wxChar *}{ParseTime}{\param{const wxChar *}{time}}
1076
1077This functions is like \helpref{ParseDateTime}{wxdatetimeparsedatetime}, but
1078only allows the time to be specified in the input string.
1079
1080Returns {\tt NULL} if the conversion failed, otherwise return the pointer to
1081the character which stopped the scan.
1082
1083\membersection{wxDateTime::Format}\label{wxdatetimeformat}
1084
1085\constfunc{wxString }{Format}{\param{const wxChar *}{format = "\%c"}, \param{const TimeZone\& }{tz = Local}}
1086
1087This function does the same as the standard ANSI C {\tt strftime(3)} function.
1088Please see its description for the meaning of {\it format} parameter.
1089
1090It also accepts a few wxWindows-specific extensions: you can optionally specify
1091the width of the field to follow using {\tt printf(3)}-like syntax and the
2edb0bde 1092format specification {\tt \%l} can be used to get the number of milliseconds.
f6bcfd97
BP
1093
1094\wxheading{See also}
1095
1096\helpref{ParseFormat}{wxdatetimeparseformat}
1097
1098\membersection{wxDateTime::FormatDate}\label{wxdatetimeformatdate}
1099
1100\constfunc{wxString }{FormatDate}{\void}
1101
1102Identical to calling \helpref{Format()}{wxdatetimeformat} with {\tt "\%x"}
1103argument (which means `preferred date representation for the current locale').
1104
1105\membersection{wxDateTime::FormatTime}\label{wxdatetimeformattime}
1106
1107\constfunc{wxString }{FormatTime}{\void}
1108
1109Identical to calling \helpref{Format()}{wxdatetimeformat} with {\tt "\%X"}
1110argument (which means `preferred time representation for the current locale').
1111
1112\membersection{wxDateTime::FormatISODate}\label{wxdatetimeformatisodate}
1113
1114\constfunc{wxString }{FormatISODate}{\void}
1115
1116This function returns the date representation in the ISO 8601 format
1117(YYYY-MM-DD).
1118
1119\membersection{wxDateTime::FormatISOTime}\label{wxdatetimeformatisotime}
1120
1121\constfunc{wxString }{FormatISOTime}{\void}
1122
1123This function returns the time representation in the ISO 8601 format
1124(HH:MM:SS).
1125
1126%%%%%%%%%%%%%%%%%%%%%%%%%%% calendar calculations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1127
1128\membersection{wxDateTime::SetToWeekDayInSameWeek}\label{wxdatetimesettoweekdayinsameweek}
1129
1130\func{wxDateTime\&}{SetToWeekDayInSameWeek}{\param{WeekDay }{weekday}}
1131
1132Adjusts the date so that it will still lie in the same week as before, but its
1133week day will be the given one.
1134
1135Returns the reference to the modified object itself.
1136
1137\membersection{wxDateTime::GetWeekDayInSameWeek}\label{wxdatetimegetweekdayinsameweek}
1138
1139\constfunc{wxDateTime}{GetWeekDayInSameWeek}{\param{WeekDay }{weekday}}
1140
1141Returns the copy of this object to which
1142\helpref{SetToWeekDayInSameWeek}{wxdatetimesettoweekdayinsameweek} was
1143applied.
1144
1145\membersection{wxDateTime::SetToNextWeekDay}\label{wxdatetimesettonextweekday}
1146
1147\func{wxDateTime\&}{SetToNextWeekDay}{\param{WeekDay }{weekday}}
1148
1149Sets the date so that it will be the first {\it weekday} following the current
1150date.
1151
1152Returns the reference to the modified object itself.
1153
1154\membersection{wxDateTime::GetNextWeekDay}\label{wxdatetimegetnextweekday}
1155
1156\constfunc{wxDateTime}{GetNextWeekDay}{\param{WeekDay }{weekday}}
1157
1158Returns the copy of this object to which
1159\helpref{SetToNextWeekDay}{wxdatetimesettonextweekday} was applied.
1160
1161\membersection{wxDateTime::SetToPrevWeekDay}\label{wxdatetimesettoprevweekday}
1162
1163\func{wxDateTime\&}{SetToPrevWeekDay}{\param{WeekDay }{weekday}}
1164
1165Sets the date so that it will be the last {\it weekday} before the current
1166date.
1167
1168Returns the reference to the modified object itself.
1169
1170\membersection{wxDateTime::GetPrevWeekDay}\label{wxdatetimegetprevweekday}
1171
1172\constfunc{wxDateTime}{GetPrevWeekDay}{\param{WeekDay }{weekday}}
1173
1174Returns the copy of this object to which
1175\helpref{SetToPrevWeekDay}{wxdatetimesettoprevweekday} was applied.
1176
1177\membersection{wxDateTime::SetToWeekDay}\label{wxdatetimesettoweekday}
1178
1179\func{bool}{SetToWeekDay}{\param{WeekDay }{weekday}, \param{int }{n = 1}, \param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1180
1181Sets the date to the {\it n}-th {\it weekday} in the given month of the given
1182year (the current month and year are used by default). The parameter {\it n}
2edb0bde 1183may be either positive (counting from the beginning of the month) or negative
f6bcfd97
BP
1184(counting from the end of it).
1185
1186For example, {\tt SetToWeekDay(2, wxDateTime::Wed)} will set the date to the
1187second Wednesday in the current month and
cdfb1ae1 1188{\tt SetToWeekDay(-1, wxDateTime::Sun)} -- to the last Sunday in it.
f6bcfd97
BP
1189
1190Returns {\tt TRUE} if the date was modified successfully, {\tt FALSE}
1191otherwise meaning that the specified date doesn't exist.
1192
1193\membersection{wxDateTime::GetWeekDay}\label{wxdatetimegetweekday2}
1194
1195\constfunc{wxDateTime}{GetWeekDay}{\param{WeekDay }{weekday}, \param{int }{n = 1}, \param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1196
1197Returns the copy of this object to which
1198\helpref{SetToWeekDay}{wxdatetimesettoweekday} was applied.
1199
1200\membersection{wxDateTime::SetToLastWeekDay}\label{wxdatetimesettolastweekday}
1201
1202\func{bool}{SetToLastWeekDay}{\param{WeekDay }{weekday}, \param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1203
1204The effect of calling this function is the same as of calling
1205{\tt SetToWeekDay(-1, weekday, month, year)}. The date will be set to the last
1206{\it weekday} in the given month and year (the current ones by default).
1207
1208Always returns {\tt TRUE}.
1209
1210\membersection{wxDateTime::GetLastWeekDay}\label{wxdatetimegetlastweekday}
1211
1212\func{wxDateTime}{GetLastWeekDay}{\param{WeekDay }{weekday}, \param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1213
1214Returns the copy of this object to which
1215\helpref{SetToLastWeekDay}{wxdatetimesettolastweekday} was applied.
1216
1217\membersection{wxDateTime::SetToTheWeek}\label{wxdatetimesettotheweek}
1218
1219\func{bool}{SetToTheWeek}{\param{wxDateTime\_t }{numWeek}, \param{WeekDay }{weekday = Mon}}
1220
1221Set the date to the given {\it weekday} in the week with given number
1222{\it numWeek}. The number should be in range $1\ldots53$ and {\tt FALSE} will
1223be returned if the specified date doesn't exist. {\tt TRUE} is returned if the
1224date was changed successfully.
1225
1226\membersection{wxDateTime::GetWeek}\label{wxdatetimegetweek}
1227
1228\constfunc{wxDateTime}{GetWeek}{\param{wxDateTime\_t }{numWeek}, \param{WeekDay }{weekday = Mon}}
1229
1230Returns the copy of this object to which
1231\helpref{SetToTheWeek}{wxdatetimesettotheweek} was applied.
1232
1233\membersection{wxDateTime::SetToLastMonthDay}\label{wxdatetimesettolastmonthday}
1234
1235\func{wxDateTime\&}{SetToLastMonthDay}{\param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1236
1237Sets the date to the last day in the specified month (the current one by
1238default).
1239
1240Returns the reference to the modified object itself.
1241
1242\membersection{wxDateTime::GetLastMonthDay}\label{wxdatetimegetlastmonthday}
1243
1244\constfunc{wxDateTime}{GetLastMonthDay}{\param{Month }{month = Inv\_Month}, \param{int }{year = Inv\_Year}}
1245
1246Returns the copy of this object to which
1247\helpref{SetToLastMonthDay}{wxdatetimesettolastmonthday} was applied.
1248
1249\membersection{wxDateTime::SetToYearDay}\label{wxdatetimesettoyearday}
1250
1251\func{wxDateTime\&}{SetToYearDay}{\param{wxDateTime\_t }{yday}}
1252
1253Sets the date to the day number {\it yday} in the same year (i.e., unlike the
1254other functions, this one does not use the current year). The day number
1255should be in the range $1\ldots366$ for the leap years and $1\ldots365$ for
1256the other ones.
1257
1258Returns the reference to the modified object itself.
1259
1260\membersection{wxDateTime::GetYearDay}\label{wxdatetimegetyearday}
1261
1262\constfunc{wxDateTime}{GetYearDay}{\param{wxDateTime\_t }{yday}}
1263
1264Returns the copy of this object to which
1265\helpref{SetToYearDay}{wxdatetimesettoyearday} was applied.
1266
1267%%%%%%%%%%%%%%%%%%%%%%%%%%% astronomical functions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1268
1269\membersection{wxDateTime::GetJulianDayNumber}\label{wxdatetimegetjuliandaynumber}
1270
1271\constfunc{double}{GetJulianDayNumber}{\void}
1272
1273Returns the \helpref{JDN}{wxdatetimesetjdn} corresponding to this date. Beware
1274of rounding errors!
1275
1276\wxheading{See also}
1277
1278\helpref{GetModifiedJulianDayNumber}{wxdatetimegetmodifiedjuliandaynumber}
1279
1280\membersection{wxDateTime::GetJDN}\label{wxdatetimegetjdn}
1281
1282\constfunc{double}{GetJDN}{\void}
1283
1284Synonym for \helpref{GetJulianDayNumber}{wxdatetimegetjuliandaynumber}.
1285
1286\membersection{wxDateTime::GetModifiedJulianDayNumber}\label{wxdatetimegetmodifiedjuliandaynumber}
1287
1288\constfunc{double}{GetModifiedJulianDayNumber}{\void}
1289
1290Returns the {\it Modified Julian Day Number} (MJD) which is, by definition,
1291equal to $JDN - 2400000.5$. The MJDs are simpler to work with as the integral
1292MJDs correspond to midnights of the dates in the Gregorian calendar and not th
1293noons like JDN. The MJD $0$ is Nov 17, 1858.
1294
1295\membersection{wxDateTime::GetMJD}\label{wxdatetimegetmjd}
1296
1297\constfunc{double}{GetMJD}{\void}
1298
1299Synonym for \helpref{GetModifiedJulianDayNumber}{wxdatetimegetmodifiedjuliandaynumber}.
1300
1301\membersection{wxDateTime::GetRataDie}\label{wxdatetimegetratadie}
1302
1303\constfunc{double}{GetRataDie}{\void}
1304
1305Return the {\it Rata Die number} of this date.
1306
1307By definition, the Rata Die number is a date specified as the number of days
1308relative to a base date of December 31 of the year 0. Thus January 1 of the
1309year 1 is Rata Die day 1.
1310
1311%%%%%%%%%%%%%%%%%%%%%%%%%%% timezone and DST %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1312
1313\membersection{wxDateTime::ToTimezone}\label{wxdatetimetotimezone}
1314
1315\constfunc{wxDateTime}{ToTimezone}{\param{const TimeZone\& }{tz}, \param{bool }{noDST = FALSE}}
1316
1317Transform the date to the given time zone. If {\it noDST} is {\tt TRUE}, no
1318DST adjustments will be made.
1319
1320Returns the date in the new time zone.
1321
1322\membersection{wxDateTime::MakeTimezone}\label{wxdatetimemaketimezone}
1323
1324\func{wxDateTime\&}{MakeTimezone}{\param{const TimeZone\& }{tz}, \param{bool }{noDST = FALSE}}
1325
1326Modifies the object in place to represent the date in another time zone. If
1327{\it noDST} is {\tt TRUE}, no DST adjustments will be made.
1328
1329\membersection{wxDateTime::ToGMT}\label{wxdatetimetogmt}
1330
1331\constfunc{wxDateTime}{ToGMT}{\param{bool }{noDST = FALSE}}
1332
1333This is the same as calling \helpref{ToTimezone}{wxdatetimetotimezone} with
1334the argument {\tt GMT0}.
1335
1336\membersection{wxDateTime::MakeGMT}\label{wxdatetimemakegmt}
1337
1338\func{wxDateTime\&}{MakeGMT}{\param{bool }{noDST = FALSE}}
1339
1340This is the same as calling \helpref{MakeTimezone}{wxdatetimemaketimezone} with
1341the argument {\tt GMT0}.
1342
1343\membersection{wxDateTime::IsDST}\label{wxdatetimeisdst}
1344
1345\constfunc{int}{IsDST}{\param{Country }{country = Country\_Default}}
1346
1347Returns {\tt TRUE} if the DST is applied for this date in the given country.
1348
1349\wxheading{See also}
1350
1351\helpref{GetBeginDST}{wxdatetimegetbegindst} and
1352\helpref{GetEndDST}{wxdatetimegetenddst}
1353
1354\section{\class{wxDateTimeHolidayAuthority}}\label{wxdatetimeholidayauthority}
1355
1356TODO
1357
1358\section{\class{wxDateTimeWorkDays}}\label{wxdatetimeworkdays}
1359
1360TODO
1361