1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDateTime
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 wxDateTime class represents an absolute moment in the time.
14 The type @c wxDateTime_t is typedefed as <tt>unsigned short</tt> and is
15 used to contain the number of years, hours, minutes, seconds and
19 @section datetime_constants Constants
21 Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
22 defined. This constant will be different from any valid wxDateTime object.
24 All the following constants are defined inside wxDateTime class (i.e., to
25 refer to them you should prepend their names with "wxDateTime::").
27 Time zone symbolic names:
32 // the time in the current time zone
35 // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
36 // consequent numbers, so writing something like `GMT0 + offset' is
37 // safe if abs(offset) <= 12
39 // underscore stands for minus
40 GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
41 GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
43 GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
44 GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
45 // Note that GMT12 and GMT_12 are not the same: there is a difference
46 // of exactly one day between them
48 // some symbolic names for TZ
51 WET = GMT0, // Western Europe Time
52 WEST = GMT1, // Western Europe Summer Time
53 CET = GMT1, // Central Europe Time
54 CEST = GMT2, // Central Europe Summer Time
55 EET = GMT2, // Eastern Europe Time
56 EEST = GMT3, // Eastern Europe Summer Time
57 MSK = GMT3, // Moscow Time
58 MSD = GMT4, // Moscow Summer Time
61 AST = GMT_4, // Atlantic Standard Time
62 ADT = GMT_3, // Atlantic Daylight Time
63 EST = GMT_5, // Eastern Standard Time
64 EDT = GMT_4, // Eastern Daylight Saving Time
65 CST = GMT_6, // Central Standard Time
66 CDT = GMT_5, // Central Daylight Saving Time
67 MST = GMT_7, // Mountain Standard Time
68 MDT = GMT_6, // Mountain Daylight Saving Time
69 PST = GMT_8, // Pacific Standard Time
70 PDT = GMT_7, // Pacific Daylight Saving Time
71 HST = GMT_10, // Hawaiian Standard Time
72 AKST = GMT_9, // Alaska Standard Time
73 AKDT = GMT_8, // Alaska Daylight Saving Time
77 A_WST = GMT8, // Western Standard Time
78 A_CST = GMT13 + 1, // Central Standard Time (+9.5)
79 A_EST = GMT10, // Eastern Standard Time
80 A_ESST = GMT11, // Eastern Summer Time
83 NZST = GMT12, // Standard Time
84 NZDT = GMT13, // Daylight Saving Time
86 // Universal Coordinated Time = the new and politically correct name
92 Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
93 Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
95 Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
96 in @c wxDateTime::WeekDay enum.
98 Finally, Inv_Year is defined to be an invalid value for year parameter.
100 GetMonthName() and GetWeekDayName() functions use the following flags:
105 Name_Full = 0x01, // return full name
106 Name_Abbr = 0x02 // return abbreviated name
110 Several functions accept an extra parameter specifying the calendar to use
111 (although most of them only support now the Gregorian calendar). This
112 parameters is one of the following values:
117 Gregorian, // calendar currently in use in Western countries
118 Julian // calendar in use since -45 until the 1582 (or later)
122 Date calculations often depend on the country and wxDateTime allows to set
123 the country whose conventions should be used using SetCountry(). It takes
124 one of the following values as parameter:
129 Country_Unknown, // no special information for this country
130 Country_Default, // set the default country with SetCountry() method
131 // or use the default country with any other
133 Country_WesternEurope_Start,
134 Country_EEC = Country_WesternEurope_Start,
138 Country_WesternEurope_End = UK,
146 Different parts of the world use different conventions for the week start.
147 In some countries, the week starts on Sunday, while in others -- on Monday.
148 The ISO standard doesn't address this issue, so we support both conventions
149 in the functions whose result depends on it (GetWeekOfYear() and
152 The desired behvaiour may be specified by giving one of the following
153 constants as argument to these functions:
158 Default_First, // Sunday_First for US, Monday_First for the rest
159 Monday_First, // week starts with a Monday
160 Sunday_First // week starts with a Sunday
165 @section datetime_static Static Functions
167 All static functions either set or return the static variables of
168 wxDateSpan (the country), return the current moment, year, month or number
169 of days in it, or do some general calendar-related actions.
171 Please note that although several function accept an extra Calendar
172 parameter, it is currently ignored as only the Gregorian calendar is
173 supported. Future versions will support other calendars.
176 These methods are standalone functions named
177 "wxDateTime_<StaticMethodName>" in wxPython.
181 @section datetime_formatting Date Formatting and Parsing
183 The date formatting and parsing functions convert wxDateTime objects to and
184 from text. The conversions to text are mostly trivial: you can either do it
185 using the default date and time representations for the current locale
186 (FormatDate() and FormatTime()), using the international standard
187 representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and
188 FormatISOCombined()) or by specifying any format at all and using Format()
191 The conversions from text are more interesting, as there are much more
192 possibilities to care about. The simplest cases can be taken care of with
193 ParseFormat() which can parse any date in the given (rigid) format.
194 ParseRfc822Date() is another function for parsing dates in predefined
195 format -- the one of RFC 822 which (still...) defines the format of email
196 messages on the Internet. This format can not be described with
197 @c strptime(3)-like format strings used by Format(), hence the need for a
200 But the most interesting functions are ParseTime(), ParseDate() and
201 ParseDateTime(). They try to parse the date and time (or only one of them)
202 in 'free' format, i.e. allow them to be specified in any of possible ways.
203 These functions will usually be used to parse the (interactive) user input
204 which is not bound to be in any predefined format. As an example,
205 ParseDateTime() can parse the strings such as "tomorrow", "March first" and
208 Finally notice that each of the parsing functions is available in several
209 overloads: if the input string is a narrow (@c char *) string, then a
210 narrow pointer is returned. If the input string is a wide string, a wide
211 char pointer is returned. Finally, if the input parameter is a wxString, a
212 narrow char pointer is also returned for backwards compatibility but there
213 is also an additional argument of wxString::const_iterator type in which,
214 if it is not @NULL, an iterator pointing to the end of the scanned string
222 - ::wxDefaultDateTime
224 @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
230 @name Constructors, Assignment Operators and Setters
232 Constructors and various Set() methods are collected here. If you
233 construct a date object from separate values for day, month and year,
234 you should use IsValid() method to check that the values were correct
235 as constructors can not return an error code.
240 Default constructor. Use one of the Set() functions to initialize the
248 This constructor is named "wxDateTimeFromTimeT" in wxPython.
251 wxDateTime(time_t timet
);
255 @beginWxPythonOnly Unsupported. @endWxPythonOnly
257 wxDateTime(const struct tm
& tm
);
262 This constructor is named "wxDateTimeFromJDN" in wxPython.
265 wxDateTime(double jdn
);
270 This constructor is named "wxDateTimeFromHMS" in wxPython.
273 wxDateTime(wxDateTime_t hour
, wxDateTime_t minute
= 0,
274 wxDateTime_t second
= 0, wxDateTime_t millisec
= 0);
279 This constructor is named "wxDateTimeFromDMY" in wxPython.
282 wxDateTime(wxDateTime_t day
, Month month
= Inv_Month
,
283 int year
= Inv_Year
, wxDateTime_t hour
= 0,
284 wxDateTime_t minute
= 0, wxDateTime_t second
= 0,
285 wxDateTime_t millisec
= 0);
288 Same as SetFromMSWSysTime.
291 Input, Windows SYSTEMTIME reference
295 wxDateTime(const struct _SYSTEMTIME
& st
);
299 Reset time to midnight (00:00:00) without changing the date.
301 wxDateTime
& ResetTime();
304 Constructs the object from @a timet value holding the number of seconds
308 This method is named "SetTimeT" in wxPython.
311 wxDateTime
& Set(time_t timet
);
313 Sets the date and time from the broken down representation in the
314 standard @a tm structure.
316 @beginWxPythonOnly Unsupported. @endWxPythonOnly
318 wxDateTime
& Set(const struct tm
& tm
);
320 Sets the date from the so-called Julian Day Number.
322 By definition, the Julian Day Number, usually abbreviated as JDN, of a
323 particular instant is the fractional number of days since 12 hours
324 Universal Coordinated Time (Greenwich mean noon) on January 1 of the
325 year -4712 in the Julian proleptic calendar.
328 This method is named "SetJDN" in wxPython.
331 wxDateTime
& Set(double jdn
);
333 Sets the date to be equal to Today() and the time from supplied
337 This method is named "SetHMS" in wxPython.
340 wxDateTime
& Set(wxDateTime_t hour
, wxDateTime_t minute
= 0,
341 wxDateTime_t second
= 0, wxDateTime_t millisec
= 0);
343 Sets the date and time from the parameters.
345 wxDateTime
& Set(wxDateTime_t day
, Month month
= Inv_Month
,
346 int year
= Inv_Year
, wxDateTime_t hour
= 0,
347 wxDateTime_t minute
= 0, wxDateTime_t second
= 0,
348 wxDateTime_t millisec
= 0);
351 Sets the day without changing other date components.
353 wxDateTime
& SetDay(unsigned short day
);
356 Sets the date from the date and time in DOS format.
358 wxDateTime
& SetFromDOS(unsigned long ddt
);
361 Sets the hour without changing other date components.
363 wxDateTime
& SetHour(unsigned short hour
);
366 Sets the millisecond without changing other date components.
368 wxDateTime
& SetMillisecond(unsigned short millisecond
);
371 Sets the minute without changing other date components.
373 wxDateTime
& SetMinute(unsigned short minute
);
376 Sets the month without changing other date components.
378 wxDateTime
& SetMonth(Month month
);
381 Sets the second without changing other date components.
383 wxDateTime
& SetSecond(unsigned short second
);
386 Sets the date and time of to the current values. Same as assigning the
387 result of Now() to this object.
389 wxDateTime
& SetToCurrent();
392 Sets the year without changing other date components.
394 wxDateTime
& SetYear(int year
);
399 wxDateTime
& operator=(time_t timet
);
403 wxDateTime
& operator=(const struct tm
& tm
);
412 Here are the trivial accessors. Other functions, which might have to
413 perform some more complicated calculations to find the answer are under
414 the "Date Arithmetics" section.
419 Returns the date and time in DOS format.
421 long unsigned int GetAsDOS() const;
424 Initialize using the Windows SYSTEMTIME structure.
426 Input, Windows SYSTEMTIME reference
430 wxDateTime
& SetFromMSWSysTime(const struct _SYSTEMTIME
& st
);
433 Returns the date and time in the Windows SYSTEMTIME format.
435 Output, pointer to Windows SYSTEMTIME
439 void GetAsMSWSysTime(struct _SYSTEMTIME
* st
) const;
442 Returns the century of this date.
444 int GetCentury(const TimeZone
& tz
= Local
) const;
447 Returns the object having the same date component as this one but time
454 wxDateTime
GetDateOnly() const;
457 Returns the day in the given timezone (local one by default).
459 short unsigned int GetDay(const TimeZone
& tz
= Local
) const;
462 Returns the day of the year (in 1-366 range) in the given timezone
463 (local one by default).
465 short unsigned int GetDayOfYear(const TimeZone
& tz
= Local
) const;
468 Returns the hour in the given timezone (local one by default).
470 short unsigned int GetHour(const TimeZone
& tz
= Local
) const;
473 Returns the milliseconds in the given timezone (local one by default).
475 short unsigned int GetMillisecond(const TimeZone
& tz
= Local
) const;
478 Returns the minute in the given timezone (local one by default).
480 short unsigned int GetMinute(const TimeZone
& tz
= Local
) const;
483 Returns the month in the given timezone (local one by default).
485 Month
GetMonth(const TimeZone
& tz
= Local
) const;
488 Returns the seconds in the given timezone (local one by default).
490 short unsigned int GetSecond(const TimeZone
& tz
= Local
) const;
493 Returns the number of seconds since Jan 1, 1970. An assert failure will
494 occur if the date is not in the range covered by @c time_t type.
496 time_t GetTicks() const;
499 Returns broken down representation of the date and time.
501 Tm
GetTm(const TimeZone
& tz
= Local
) const;
504 Returns the week day in the given timezone (local one by default).
506 WeekDay
GetWeekDay(const TimeZone
& tz
= Local
) const;
509 Returns the ordinal number of the week in the month (in 1-5 range).
511 As GetWeekOfYear(), this function supports both conventions for the
512 week start. See the description of these @c WeekFlags in the
513 @ref datetime_constants section.
515 wxDateTime_t
GetWeekOfMonth(WeekFlags flags
= Monday_First
,
516 const TimeZone
& tz
= Local
) const;
519 Returns the number of the week of the year this date is in. The first
520 week of the year is, according to international standards, the one
521 containing Jan 4 or, equivalently, the first week which has Thursday in
522 this year. Both of these definitions are the same as saying that the
523 first week of the year must contain more than half of its days in this
524 year. Accordingly, the week number will always be in 1-53 range (52 for
527 The function depends on the @ref datetime_constants "week start"
528 convention specified by the @a flags argument but its results for
529 @c Sunday_First are not well-defined as the ISO definition quoted above
530 applies to the weeks starting on Monday only.
532 wxDateTime_t
GetWeekOfYear(WeekFlags flags
= Monday_First
,
533 const TimeZone
& tz
= Local
) const;
536 Returns the year in the given timezone (local one by default).
538 int GetYear(const TimeZone
& tz
= Local
) const;
541 Returns @true if the given date is later than the date of adoption of
542 the Gregorian calendar in the given country (and hence the Gregorian
543 calendar calculations make sense for it).
545 bool IsGregorianDate(GregorianAdoption country
= Gr_Standard
) const;
548 Returns @true if the object represents a valid time moment.
550 bool IsValid() const;
553 Returns @true is this day is not a holiday in the given country.
555 bool IsWorkDay(Country country
= Country_Default
) const;
562 @name Date Comparison
564 There are several functions to allow date comparison. To supplement
565 them, a few global operators, etc taking wxDateTime are defined.
570 Returns @true if this date precedes the given one.
572 bool IsEarlierThan(const wxDateTime
& datetime
) const;
575 Returns @true if the two dates are strictly identical.
577 bool IsEqualTo(const wxDateTime
& datetime
) const;
580 Returns @true if the date is equal to another one up to the given time
581 interval, i.e. if the absolute difference between the two dates is less
584 bool IsEqualUpTo(const wxDateTime
& dt
, const wxTimeSpan
& ts
) const;
587 Returns @true if this date is later than the given one.
589 bool IsLaterThan(const wxDateTime
& datetime
) const;
592 Returns @true if the date is the same without comparing the time parts.
594 bool IsSameDate(const wxDateTime
& dt
) const;
597 Returns @true if the time is the same (although dates may differ).
599 bool IsSameTime(const wxDateTime
& dt
) const;
602 Returns @true if this date lies strictly between the two given dates.
606 bool IsStrictlyBetween(const wxDateTime
& t1
,
607 const wxDateTime
& t2
) const;
610 Returns @true if IsStrictlyBetween() is @true or if the date is equal
611 to one of the limit values.
613 @see IsStrictlyBetween()
615 bool IsBetween(const wxDateTime
& t1
, const wxDateTime
& t2
) const;
622 @name Date Arithmetics
624 These functions carry out
625 @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime
626 objects. As explained in the overview, either wxTimeSpan or wxDateSpan
627 may be added to wxDateTime, hence all functions are overloaded to
628 accept both arguments.
630 Also, both Add() and Subtract() have both const and non-const version.
631 The first one returns a new object which represents the sum/difference
632 of the original one with the argument while the second form modifies
633 the object to which it is applied. The operators "-=" and "+=" are
634 defined to be equivalent to the second forms of these functions.
639 Adds the given date span to this object.
642 This method is named "AddDS" in wxPython.
645 wxDateTime
Add(const wxDateSpan
& diff
) const;
647 Adds the given date span to this object.
650 This method is named "AddDS" in wxPython.
653 wxDateTime
Add(const wxDateSpan
& diff
);
655 Adds the given time span to this object.
658 This method is named "AddTS" in wxPython.
661 wxDateTime
Add(const wxTimeSpan
& diff
) const;
663 Adds the given time span to this object.
666 This method is named "AddTS" in wxPython.
669 wxDateTime
& Add(const wxTimeSpan
& diff
);
672 Subtracts the given time span from this object.
675 This method is named "SubtractTS" in wxPython.
678 wxDateTime
Subtract(const wxTimeSpan
& diff
) const;
680 Subtracts the given time span from this object.
683 This method is named "SubtractTS" in wxPython.
686 wxDateTime
& Subtract(const wxTimeSpan
& diff
);
688 Subtracts the given date span from this object.
691 This method is named "SubtractDS" in wxPython.
694 wxDateTime
Subtract(const wxDateSpan
& diff
) const;
696 Subtracts the given date span from this object.
699 This method is named "SubtractDS" in wxPython.
702 wxDateTime
& Subtract(const wxDateSpan
& diff
);
704 Subtracts another date from this one and returns the difference between
705 them as a wxTimeSpan.
707 wxTimeSpan
Subtract(const wxDateTime
& dt
) const;
710 Adds the given date span to this object.
712 wxDateTime
operator+=(const wxDateSpan
& diff
);
714 Subtracts the given date span from this object.
716 wxDateTime
& operator-=(const wxDateSpan
& diff
);
718 Adds the given time span to this object.
720 wxDateTime
& operator+=(const wxTimeSpan
& diff
);
722 Subtracts the given time span from this object.
724 wxDateTime
& operator-=(const wxTimeSpan
& diff
);
731 @name Date Formatting and Parsing
733 See @ref datetime_formatting
738 This function does the same as the standard ANSI C @c strftime(3)
739 function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html).
740 Please see its description for the meaning of @a format parameter.
742 It also accepts a few wxWidgets-specific extensions: you can optionally
743 specify the width of the field to follow using @c printf(3)-like syntax
744 and the format specification @c "%l" can be used to get the number of
749 wxString
Format(const wxString
& format
= wxDefaultDateTimeFormat
,
750 const TimeZone
& tz
= Local
) const;
753 Identical to calling Format() with @c "%x" argument (which means
754 "preferred date representation for the current locale").
756 wxString
FormatDate() const;
759 Returns the combined date-time representation in the ISO 8601 format
760 @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
761 the result exactly corresponding to the ISO standard, but it can also
762 be useful to use a space as seprator if a more human-readable combined
763 date-time representation is needed.
765 @see FormatISODate(), FormatISOTime(), ParseISOCombined()
767 wxString
FormatISOCombined(char sep
= 'T') const;
770 This function returns the date representation in the ISO 8601 format
773 wxString
FormatISODate() const;
776 This function returns the time representation in the ISO 8601 format
779 wxString
FormatISOTime() const;
782 Identical to calling Format() with @c "%X" argument (which means
783 "preferred time representation for the current locale").
785 wxString
FormatTime() const;
788 This function is like ParseDateTime(), but it only allows the date to
789 be specified. It is thus less flexible then ParseDateTime(), but also
790 has less chances to misinterpret the user input.
792 @return @NULL if the conversion failed, otherwise return the pointer
793 to the character which stopped the scan.
797 const char* ParseDate(const wxString
& date
,
798 wxString
::const_iterator
* end
= NULL
);
803 const char* ParseDate(const char* date
);
808 const wchar_t* ParseDate(const wchar_t* date
);
811 Parses the string @a datetime containing the date and time in free
812 format. This function tries as hard as it can to interpret the given
813 string as date and time. Unlike ParseRfc822Date(), it will accept
814 anything that may be accepted and will only reject strings which can
815 not be parsed in any way at all.
817 @return @NULL if the conversion failed, otherwise return the pointer
818 to the character which stopped the scan.
820 const char* ParseDateTime(const wxString
& datetime
,
821 wxString
::const_iterator
* end
= NULL
);
826 const char* ParseDateTime(const char* datetime
);
831 const wchar_t* ParseDateTime(const wchar_t* datetime
);
834 This function parses the string @a date according to the given
835 @e format. The system @c strptime(3) function is used whenever
836 available, but even if it is not, this function is still implemented,
837 although support for locale-dependent format specifiers such as
838 @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
839 as @c "%z" and @c "%Z" are not implemented. This function does handle
840 the month and weekday names in the current locale on all platforms,
843 Please see the description of the ANSI C function @c strftime(3) for
844 the syntax of the format string.
846 The @a dateDef parameter is used to fill in the fields which could not
847 be determined from the format string. For example, if the format is
848 @c "%d" (the day of the month), the month and the year are taken from
849 @a dateDef. If it is not specified, Today() is used as the default
852 @return @NULL if the conversion failed, otherwise return the pointer
853 to the character which stopped the scan.
857 const char* ParseFormat(const wxString
& date
,
858 const wxString
& format
= wxDefaultDateTimeFormat
,
859 const wxDateTime
& dateDef
= wxDefaultDateTime
,
860 wxString
::const_iterator
* end
= NULL
);
865 const char* ParseFormat(const char* date
,
866 const wxString
& format
= wxDefaultDateTimeFormat
,
867 const wxDateTime
& dateDef
= wxDefaultDateTime
);
872 const wchar_t* ParseFormat(const wchar_t* date
,
873 const wxString
& format
= wxDefaultDateTimeFormat
,
874 const wxDateTime
& dateDef
= wxDefaultDateTime
);
877 This function parses the string containing the date and time in ISO
878 8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between
879 the date and time parts must be equal to @a sep for the function to
882 @return @true if the entire string was parsed successfully, @false
885 bool ParseISOCombined(const wxString
& date
, char sep
= 'T');
888 This function parses the date in ISO 8601 format @c "YYYY-MM-DD".
890 @return @true if the entire string was parsed successfully, @false
893 bool ParseISODate(const wxString
& date
);
896 This function parses the time in ISO 8601 format @c "HH:MM:SS".
898 @return @true if the entire string was parsed successfully, @false
901 bool ParseISOTime(const wxString
& date
);
904 Parses the string @a date looking for a date formatted according to the
905 RFC 822 in it. The exact description of this format may, of course, be
906 found in the RFC (section 5), but, briefly, this is the format used in
907 the headers of Internet email messages and one of the most common
908 strings expressing date in this format may be something like
909 @c "Sat, 18 Dec 1999 00:48:30 +0100".
911 Returns @NULL if the conversion failed, otherwise return the pointer to
912 the character immediately following the part of the string which could
913 be parsed. If the entire string contains only the date in RFC 822
914 format, the returned pointer will be pointing to a @c NUL character.
916 This function is intentionally strict, it will return an error for any
917 string which is not RFC 822 compliant. If you need to parse date
918 formatted in more free ways, you should use ParseDateTime() or
921 const char* ParseRfc822Date(const wxString
& date
,
922 wxString
::const_iterator
* end
= NULL
);
927 const char* ParseRfc822Date(const char* date
);
932 const wchar_t* ParseRfc822Date(const wchar_t* date
);
935 This functions is like ParseDateTime(), but only allows the time to be
936 specified in the input string.
938 @return @NULL if the conversion failed, otherwise return the pointer
939 to the character which stopped the scan.
941 const char* ParseTime(const wxString
& time
,
942 wxString
::const_iterator
* end
= NULL
);
947 const char* ParseTime(const char* time
);
952 const wchar_t* ParseTime(const wchar_t* time
);
959 @name Calendar Calculations
961 The functions in this section perform the basic calendar calculations,
962 mostly related to the week days. They allow to find the given week day
963 in the week with given number (either in the month or in the year) and
966 None of the functions in this section modify the time part of the
967 wxDateTime, they only work with the date part of it.
972 Returns the copy of this object to which SetToLastMonthDay() was
975 wxDateTime
GetLastMonthDay(Month month
= Inv_Month
,
976 int year
= Inv_Year
) const;
979 Returns the copy of this object to which SetToLastWeekDay() was
982 wxDateTime
GetLastWeekDay(WeekDay weekday
, Month month
= Inv_Month
,
983 int year
= Inv_Year
);
986 Returns the copy of this object to which SetToNextWeekDay() was
989 wxDateTime
GetNextWeekDay(WeekDay weekday
) const;
992 Returns the copy of this object to which SetToPrevWeekDay() was
995 wxDateTime
GetPrevWeekDay(WeekDay weekday
) const;
998 Returns the copy of this object to which SetToWeekDay() was applied.
1000 wxDateTime
GetWeekDay(WeekDay weekday
, int n
= 1, Month month
= Inv_Month
,
1001 int year
= Inv_Year
) const;
1004 Returns the copy of this object to which SetToWeekDayInSameWeek() was
1007 wxDateTime
GetWeekDayInSameWeek(WeekDay weekday
,
1008 WeekFlags flags
= Monday_First
) const;
1011 Returns the copy of this object to which SetToYearDay() was applied.
1013 wxDateTime
GetYearDay(wxDateTime_t yday
) const;
1016 Sets the date to the last day in the specified month (the current one
1019 @return The reference to the modified object itself.
1021 wxDateTime
& SetToLastMonthDay(Month month
= Inv_Month
, int year
= Inv_Year
);
1024 The effect of calling this function is the same as of calling
1025 @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
1026 last @a weekday in the given month and year (the current ones by
1027 default). Always returns @true.
1029 bool SetToLastWeekDay(WeekDay weekday
, Month month
= Inv_Month
,
1030 int year
= Inv_Year
);
1033 Sets the date so that it will be the first @a weekday following the
1036 @return The reference to the modified object itself.
1038 wxDateTime
& SetToNextWeekDay(WeekDay weekday
);
1041 Sets the date so that it will be the last @a weekday before the current
1044 @return The reference to the modified object itself.
1046 wxDateTime
& SetToPrevWeekDay(WeekDay weekday
);
1049 Sets the date to the @e n-th @a weekday in the given month of the given
1050 year (the current month and year are used by default). The parameter
1051 @a n may be either positive (counting from the beginning of the month)
1052 or negative (counting from the end of it).
1054 For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
1055 second Wednesday in the current month and
1056 SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
1057 in the current month.
1059 @return @true if the date was modified successfully, @false otherwise
1060 meaning that the specified date doesn't exist.
1062 bool SetToWeekDay(WeekDay weekday
, int n
= 1,
1063 Month month
= Inv_Month
, int year
= Inv_Year
);
1066 Adjusts the date so that it will still lie in the same week as before,
1067 but its week day will be the given one.
1069 @return The reference to the modified object itself.
1071 wxDateTime
& SetToWeekDayInSameWeek(WeekDay weekday
,
1072 WeekFlags flags
= Monday_First
);
1075 Sets the date to the day number @a yday in the same year (i.e., unlike
1076 the other functions, this one does not use the current year). The day
1077 number should be in the range 1-366 for the leap years and 1-365 for
1080 @return The reference to the modified object itself.
1082 wxDateTime
& SetToYearDay(wxDateTime_t yday
);
1089 @name Astronomical/Historical Functions
1091 Some degree of support for the date units used in astronomy and/or
1092 history is provided. You can construct a wxDateTime object from a
1093 JDN and you may also get its JDN, MJD or Rata Die number from it.
1095 Related functions in other groups: wxDateTime(double), Set(double)
1100 Synonym for GetJulianDayNumber().
1102 double GetJDN() const;
1105 Returns the JDN corresponding to this date. Beware of rounding errors!
1107 @see GetModifiedJulianDayNumber()
1109 double GetJulianDayNumber() const;
1112 Synonym for GetModifiedJulianDayNumber().
1114 double GetMJD() const;
1117 Returns the @e "Modified Julian Day Number" (MJD) which is, by
1118 definition, is equal to JDN - 2400000.5.
1119 The MJDs are simpler to work with as the integral MJDs correspond to
1120 midnights of the dates in the Gregorian calendar and not the noons like
1121 JDN. The MJD 0 represents Nov 17, 1858.
1123 double GetModifiedJulianDayNumber() const;
1126 Return the @e Rata Die number of this date.
1128 By definition, the Rata Die number is a date specified as the number of
1129 days relative to a base date of December 31 of the year 0. Thus January
1130 1 of the year 1 is Rata Die day 1.
1132 double GetRataDie() const;
1139 @name Time Zone and DST Support
1141 Please see the @ref overview_datetime_timezones "time zone overview"
1142 for more information about time zones. Normally, these functions should
1145 Related functions in other groups: GetBeginDST(), GetEndDST()
1150 Transform the date from the given time zone to the local one. If
1151 @a noDST is @true, no DST adjustments will be made.
1153 @return The date in the local time zone.
1155 wxDateTime
FromTimezone(const TimeZone
& tz
, bool noDST
= false) const;
1158 Returns @true if the DST is applied for this date in the given country.
1160 @see GetBeginDST(), GetEndDST()
1162 int IsDST(Country country
= Country_Default
) const;
1165 Same as FromTimezone() but modifies the object in place.
1167 wxDateTime
& MakeFromTimezone(const TimeZone
& tz
, bool noDST
= false);
1170 Modifies the object in place to represent the date in another time
1171 zone. If @a noDST is @true, no DST adjustments will be made.
1173 wxDateTime
& MakeTimezone(const TimeZone
& tz
, bool noDST
= false);
1176 This is the same as calling MakeTimezone() with the argument @c GMT0.
1178 wxDateTime
& MakeUTC(bool noDST
= false);
1181 Transform the date to the given time zone. If @a noDST is @true, no DST
1182 adjustments will be made.
1184 @return The date in the new time zone.
1186 wxDateTime
ToTimezone(const TimeZone
& tz
, bool noDST
= false) const;
1189 This is the same as calling ToTimezone() with the argument @c GMT0.
1191 wxDateTime
ToUTC(bool noDST
= false) const;
1200 Converts the year in absolute notation (i.e. a number which can be
1201 negative, positive or zero) to the year in BC/AD notation. For the
1202 positive years, nothing is done, but the year 0 is year 1 BC and so for
1203 other years there is a difference of 1.
1205 This function should be used like this:
1209 int y = dt.GetYear();
1210 printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
1213 static int ConvertYearToBC(int year
);
1216 Returns the translations of the strings @c AM and @c PM used for time
1217 formatting for the current locale. Either of the pointers may be @NULL
1218 if the corresponding value is not needed.
1220 static void GetAmPmStrings(wxString
* am
, wxString
* pm
);
1223 Get the beginning of DST for the given country in the given year
1224 (current one by default). This function suffers from limitations
1225 described in the @ref overview_datetime_dst "DST overview".
1229 static wxDateTime
GetBeginDST(int year
= Inv_Year
,
1230 Country country
= Country_Default
);
1233 Returns the end of DST for the given country in the given year (current
1238 static wxDateTime
GetEndDST(int year
= Inv_Year
,
1239 Country country
= Country_Default
);
1242 Get the current century, i.e. first two digits of the year, in given
1243 calendar (only Gregorian is currently supported).
1245 static int GetCentury(int year
);
1248 Returns the current default country. The default country is used for
1249 DST calculations, for example.
1253 static Country
GetCountry();
1256 Get the current month in given calendar (only Gregorian is currently
1259 static Month
GetCurrentMonth(Calendar cal
= Gregorian
);
1262 Get the current year in given calendar (only Gregorian is currently
1265 static int GetCurrentYear(Calendar cal
= Gregorian
);
1268 Gets the full (default) or abbreviated (specify @c Name_Abbr name of
1271 @see GetWeekDayName()
1273 static wxString
GetMonthName(Month month
, NameFlags flags
= Name_Full
);
1276 Returns the number of days in the given year. The only supported value
1277 for @a cal currently is @c Gregorian.
1280 This method is named "GetNumberOfDaysInYear" in wxPython.
1283 static wxDateTime_t
GetNumberOfDays(int year
, Calendar cal
= Gregorian
);
1286 Returns the number of days in the given month of the given year. The
1287 only supported value for @a cal currently is @c Gregorian.
1290 This method is named "GetNumberOfDaysInMonth" in wxPython.
1293 static wxDateTime_t
GetNumberOfDays(Month month
, int year
= Inv_Year
,
1294 Calendar cal
= Gregorian
);
1297 Returns the current time.
1299 static time_t GetTimeNow();
1302 Returns the current time broken down using the buffer whose adress is
1303 passed to the function with @a tm to store the result.
1305 static tm
* GetTmNow(struct tm
*tm
);
1308 Returns the current time broken down. Note that this function returns a
1309 pointer to a static buffer that's reused by calls to this function and
1310 certain C library functions (e.g. localtime). If there is any chance
1311 your code might be used in a multi-threaded application, you really
1312 should use GetTmNow(struct tm *) instead.
1314 static tm
* GetTmNow();
1317 Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
1322 static wxString
GetWeekDayName(WeekDay weekday
,
1323 NameFlags flags
= Name_Full
);
1326 Returns @true if DST was used in the given year (the current one by
1327 default) in the given country.
1329 static bool IsDSTApplicable(int year
= Inv_Year
,
1330 Country country
= Country_Default
);
1333 Returns @true if the @a year is a leap one in the specified calendar.
1334 This functions supports Gregorian and Julian calendars.
1336 static bool IsLeapYear(int year
= Inv_Year
, Calendar cal
= Gregorian
);
1339 This function returns @true if the specified (or default) country is
1340 one of Western European ones. It is used internally by wxDateTime to
1341 determine the DST convention and date and time formatting rules.
1343 static bool IsWestEuropeanCountry(Country country
= Country_Default
);
1346 Returns the object corresponding to the current time.
1351 wxDateTime now = wxDateTime::Now();
1352 printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
1355 @note This function is accurate up to seconds. UNow() should be used
1356 for better precision, but it is less efficient and might not be
1357 available on all platforms.
1361 static wxDateTime
Now();
1364 Sets the country to use by default. This setting influences the DST
1365 calculations, date formatting and other things.
1367 The possible values for @a country parameter are enumerated in the
1368 @ref datetime_constants section.
1372 static void SetCountry(Country country
);
1375 Set the date to the given @a weekday in the week number @a numWeek of
1376 the given @a year . The number should be in range 1-53.
1378 Note that the returned date may be in a different year than the one
1379 passed to this function because both the week 1 and week 52 or 53 (for
1380 leap years) contain days from different years. See GetWeekOfYear() for
1381 the explanation of how the year weeks are counted.
1383 static wxDateTime
SetToWeekOfYear(int year
, wxDateTime_t numWeek
,
1384 WeekDay weekday
= Mon
);
1387 Returns the object corresponding to the midnight of the current day
1388 (i.e. the same as Now(), but the time part is set to 0).
1392 static wxDateTime
Today();
1395 Returns the object corresponding to the current time including the
1396 milliseconds if a function to get time with such precision is available
1397 on the current platform (supported under most Unices and Win32).
1401 static wxDateTime
UNow();
1405 Global instance of an empty wxDateTime object.
1407 @todo Would it be better to rename this wxNullDateTime so it's consistent
1408 with the rest of the "empty/invalid/null" global objects?
1410 const wxDateTime wxDefaultDateTime
;
1415 @class wxDateTimeWorkDays
1417 @todo Write wxDateTimeWorkDays documentation.
1422 class wxDateTimeWorkDays
1433 This class is a "logical time span" and is useful for implementing program
1434 logic for such things as "add one month to the date" which, in general,
1435 doesn't mean to add 60*60*24*31 seconds to it, but to take the same date
1436 the next month (to understand that this is indeed different consider adding
1437 one month to Feb, 15 -- we want to get Mar, 15, of course).
1439 When adding a month to the date, all lesser components (days, hours, ...)
1440 won't be changed unless the resulting date would be invalid: for example,
1441 Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
1443 Because of this feature, adding and subtracting back again the same
1444 wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
1445 month will be Jan 28, not Jan 31!
1447 wxDateSpan objects can be either positive or negative. They may be
1448 multiplied by scalars which multiply all deltas by the scalar: i.e.
1449 2*(1 month and 1 day) is 2 months and 2 days. They can be added together
1450 with wxDateTime or wxTimeSpan, but the type of result is different for each
1453 @warning If you specify both weeks and days, the total number of days added
1454 will be 7*weeks + days! See also GetTotalDays().
1456 Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
1457 if and only if they both give the same target date when added to @b every
1458 source date. Thus wxDateSpan::Months(1) is not equal to
1459 wxDateSpan::Days(30), because they don't give the same date when added to
1460 Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
1462 Finally, notice that for adding hours, minutes and so on you don't need
1463 this class at all: wxTimeSpan will do the job because there are no
1464 subtleties associated with those (we don't support leap seconds).
1469 @see @ref overview_datetime, wxDateTime
1475 Constructs the date span object for the given number of years, months,
1476 weeks and days. Note that the weeks and days add together if both are
1479 wxDateSpan(int years
= 0, int months
= 0, int weeks
= 0, int days
= 0);
1482 Returns the sum of two date spans.
1484 @return A new wxDateSpan object with the result.
1486 wxDateSpan
Add(const wxDateSpan
& other
) const;
1488 Adds the given wxDateSpan to this wxDateSpan and returns a reference
1491 wxDateSpan
& Add(const wxDateSpan
& other
);
1494 Returns a date span object corresponding to one day.
1498 static wxDateSpan
Day();
1501 Returns a date span object corresponding to the given number of days.
1505 static wxDateSpan
Days(int days
);
1508 Returns the number of days (not counting the weeks component) in this
1513 int GetDays() const;
1516 Returns the number of the months (not counting the years) in this date
1519 int GetMonths() const;
1522 Returns the combined number of days in this date span, counting both
1523 weeks and days. This doesn't take months or years into account.
1525 @see GetWeeks(), GetDays()
1527 int GetTotalDays() const;
1530 Returns the number of weeks in this date span.
1534 int GetWeeks() const;
1537 Returns the number of years in this date span.
1539 int GetYears() const;
1542 Returns a date span object corresponding to one month.
1546 static wxDateSpan
Month();
1549 Returns a date span object corresponding to the given number of months.
1553 static wxDateSpan
Months(int mon
);
1556 Returns the product of the date span by the specified @a factor. The
1557 product is computed by multiplying each of the components by the
1560 @return A new wxDateSpan object with the result.
1562 wxDateSpan
Multiply(int factor
) const;
1564 Multiplies this date span by the specified @a factor. The product is
1565 computed by multiplying each of the components by the @a factor.
1567 @return A reference to this wxDateSpan object modified in place.
1569 wxDateSpan
& Multiply(int factor
);
1572 Changes the sign of this date span.
1579 Returns a date span with the opposite sign.
1583 wxDateSpan
Negate() const;
1586 Sets the number of days (without modifying any other components) in
1589 wxDateSpan
& SetDays(int n
);
1592 Sets the number of months (without modifying any other components) in
1595 wxDateSpan
& SetMonths(int n
);
1598 Sets the number of weeks (without modifying any other components) in
1601 wxDateSpan
& SetWeeks(int n
);
1604 Sets the number of years (without modifying any other components) in
1607 wxDateSpan
& SetYears(int n
);
1610 Returns the difference of two date spans.
1612 @return A new wxDateSpan object with the result.
1614 wxDateSpan
Subtract(const wxDateSpan
& other
) const;
1616 Subtracts the given wxDateSpan to this wxDateSpan and returns a
1617 reference to itself.
1619 wxDateSpan
& Subtract(const wxDateSpan
& other
);
1622 Returns a date span object corresponding to one week.
1626 static wxDateSpan
Week();
1629 Returns a date span object corresponding to the given number of weeks.
1633 static wxDateSpan
Weeks(int weeks
);
1636 Returns a date span object corresponding to one year.
1640 static wxDateSpan
Year();
1643 Returns a date span object corresponding to the given number of years.
1647 static wxDateSpan
Years(int years
);
1650 Adds the given wxDateSpan to this wxDateSpan and returns the result.
1652 wxDateSpan
& operator+=(const wxDateSpan
& other
);
1655 Subtracts the given wxDateSpan to this wxDateSpan and returns the
1658 wxDateSpan
& operator-=(const wxDateSpan
& other
);
1661 Changes the sign of this date span.
1665 wxDateSpan
& operator-();
1668 Multiplies this date span by the specified @a factor. The product is
1669 computed by multiplying each of the components by the @a factor.
1671 @return A reference to this wxDateSpan object modified in place.
1673 wxDateSpan
& operator*=(int factor
);
1676 Returns @true if this date span is different from the other one.
1678 bool operator!=(const wxDateSpan
&) const;
1681 Returns @true if this date span is equal to the other one. Two date
1682 spans are considered equal if and only if they have the same number of
1683 years and months and the same total number of days (counting both days
1686 bool operator==(const wxDateSpan
&) const;
1694 wxTimeSpan class represents a time interval.
1699 @see @ref overview_datetime, wxDateTime
1705 Default constructor, constructs a zero timespan.
1709 Constructs timespan from separate values for each component, with the
1710 date set to 0. Hours are not restricted to 0-24 range, neither are
1711 minutes, seconds or milliseconds.
1713 wxTimeSpan(long hours
, long min
= 0, wxLongLong sec
= 0, wxLongLong msec
= 0);
1716 Returns the absolute value of the timespan: does not modify the object.
1718 wxTimeSpan
Abs() const;
1721 Returns the sum of two time spans.
1723 @return A new wxDateSpan object with the result.
1725 wxTimeSpan
Add(const wxTimeSpan
& diff
) const;
1727 Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
1730 wxTimeSpan
& Add(const wxTimeSpan
& diff
);
1733 Returns the timespan for one day.
1735 static wxTimeSpan
Day();
1738 Returns the timespan for the given number of days.
1740 static wxTimeSpan
Days(long days
);
1743 Returns the string containing the formatted representation of the time
1744 span. The following format specifiers are allowed after %:
1746 - @c H - Number of Hours
1747 - @c M - Number of Minutes
1748 - @c S - Number of Seconds
1749 - @c l - Number of Milliseconds
1750 - @c D - Number of Days
1751 - @c E - Number of Weeks
1752 - @c % - The percent character
1754 Note that, for example, the number of hours in the description above is
1755 not well defined: it can be either the total number of hours (for
1756 example, for a time span of 50 hours this would be 50) or just the hour
1757 part of the time span, which would be 2 in this case as 50 hours is
1758 equal to 2 days and 2 hours.
1760 wxTimeSpan resolves this ambiguity in the following way: if there had
1761 been, indeed, the @c %D format specified preceding the @c %H, then it
1762 is interpreted as 2. Otherwise, it is 50.
1764 The same applies to all other format specifiers: if they follow a
1765 specifier of larger unit, only the rest part is taken, otherwise the
1768 wxString
Format(const wxString
& = wxDefaultTimeSpanFormat
) const;
1771 Returns the difference in number of days.
1773 int GetDays() const;
1776 Returns the difference in number of hours.
1778 int GetHours() const;
1781 Returns the difference in number of milliseconds.
1783 wxLongLong
GetMilliseconds() const;
1786 Returns the difference in number of minutes.
1788 int GetMinutes() const;
1791 Returns the difference in number of seconds.
1793 wxLongLong
GetSeconds() const;
1796 Returns the internal representation of timespan.
1798 wxLongLong
GetValue() const;
1801 Returns the difference in number of weeks.
1803 int GetWeeks() const;
1806 Returns the timespan for one hour.
1808 static wxTimeSpan
Hour();
1811 Returns the timespan for the given number of hours.
1813 static wxTimeSpan
Hours(long hours
);
1816 Returns @true if two timespans are equal.
1818 bool IsEqualTo(const wxTimeSpan
& ts
) const;
1821 Compares two timespans: works with the absolute values, i.e. -2 hours
1822 is longer than 1 hour. Also, it will return @false if the timespans are
1823 equal in absolute value.
1825 bool IsLongerThan(const wxTimeSpan
& ts
) const;
1828 Returns @true if the timespan is negative.
1830 bool IsNegative() const;
1833 Returns @true if the timespan is empty.
1835 bool IsNull() const;
1838 Returns @true if the timespan is positive.
1840 bool IsPositive() const;
1843 Compares two timespans: works with the absolute values, i.e. 1 hour is
1844 shorter than -2 hours. Also, it will return @false if the timespans are
1845 equal in absolute value.
1847 bool IsShorterThan(const wxTimeSpan
& ts
) const;
1850 Returns the timespan for one millisecond.
1852 static wxTimeSpan
Millisecond();
1855 Returns the timespan for the given number of milliseconds.
1857 static wxTimeSpan
Milliseconds(wxLongLong ms
);
1860 Returns the timespan for one minute.
1862 static wxTimeSpan
Minute();
1865 Returns the timespan for the given number of minutes.
1867 static wxTimeSpan
Minutes(long min
);
1870 Returns the product of this time span by @a n.
1872 @return A new wxTimeSpan object with the result.
1874 wxTimeSpan
Multiply(int n
) const;
1876 Multiplies this time span by @a n.
1878 @return A reference to this wxTimeSpan object modified in place.
1880 wxTimeSpan
& Multiply(int n
);
1883 Negate the value of the timespan.
1890 Returns timespan with inverted sign.
1894 wxTimeSpan
Negate() const;
1897 Returns the timespan for one second.
1899 static wxTimeSpan
Second();
1902 Returns the timespan for the given number of seconds.
1904 static wxTimeSpan
Seconds(wxLongLong sec
);
1907 Returns the difference of two time spans.
1909 @return A new wxDateSpan object with the result.
1911 wxTimeSpan
Subtract(const wxTimeSpan
& diff
) const;
1913 Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
1914 reference to itself.
1916 wxTimeSpan
& Subtract(const wxTimeSpan
& diff
);
1919 Returns the timespan for one week.
1921 static wxTimeSpan
Week();
1924 Returns the timespan for the given number of weeks.
1926 static wxTimeSpan
Weeks(long weeks
);
1929 Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
1931 wxTimeSpan
& operator+=(const wxTimeSpan
& diff
);
1934 Multiplies this time span by @a n.
1936 @return A reference to this wxTimeSpan object modified in place.
1938 wxTimeSpan
& operator*=(int n
);
1941 Negate the value of the timespan.
1945 wxTimeSpan
& operator-();
1948 Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
1951 wxTimeSpan
& operator-=(const wxTimeSpan
& diff
);
1957 @class wxDateTimeHolidayAuthority
1959 @todo Write wxDateTimeHolidayAuthority documentation.
1964 class wxDateTimeHolidayAuthority