X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/400930d3445bd8d8745c621b9ad0b352433db622..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/datetime.h?ds=sidebyside
diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index 950ac809e8..c181b9c75e 100644
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -2,14 +2,13 @@
// Name: datetime.h
// Purpose: interface of wxDateTime
// Author: wxWidgets team
-// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxDateTime
- wxDateTime class represents an absolute moment in the time.
+ wxDateTime class represents an absolute moment in time.
The type @c wxDateTime_t is typedefed as unsigned short and is
used to contain the number of years, hours, minutes, seconds and
@@ -29,12 +28,6 @@
parameter, it is currently ignored as only the Gregorian calendar is
supported. Future versions will support other calendars.
- @beginWxPythonOnly
- These methods are standalone functions named
- "wxDateTime_" in wxPython.
- @endWxPythonOnly
-
-
@section datetime_formatting Date Formatting and Parsing
The date formatting and parsing functions convert wxDateTime objects to and
@@ -170,128 +163,6 @@ public:
Julian ///< calendar in use since -45 until the 1582 (or later)
};
- /**
- Values corresponding to different dates of adoption of the Gregorian
- calendar.
-
- @see IsGregorianDate
- */
- enum GregorianAdoption
- {
- Gr_Unknown, ///< no data for this country or it's too uncertain to use
- Gr_Standard, ///< on the day 0 of Gregorian calendar: 15 Oct 1582
-
- Gr_Alaska, ///< Oct 1867 when Alaska became part of the USA
- Gr_Albania, ///< Dec 1912
-
- Gr_Austria = Gr_Unknown, ///< Different regions on different dates
- Gr_Austria_Brixen, ///< 5 Oct 1583 -> 16 Oct 1583
- Gr_Austria_Salzburg = Gr_Austria_Brixen,
- Gr_Austria_Tyrol = Gr_Austria_Brixen,
- Gr_Austria_Carinthia, ///< 14 Dec 1583 -> 25 Dec 1583
- Gr_Austria_Styria = Gr_Austria_Carinthia,
-
- Gr_Belgium, ///< Then part of the Netherlands
-
- Gr_Bulgaria = Gr_Unknown, ///< Unknown precisely (from 1915 to 1920)
- Gr_Bulgaria_1, ///< 18 Mar 1916 -> 1 Apr 1916
- Gr_Bulgaria_2, ///< 31 Mar 1916 -> 14 Apr 1916
- Gr_Bulgaria_3, ///< 3 Sep 1920 -> 17 Sep 1920
-
- Gr_Canada = Gr_Unknown, ///< Different regions followed the changes in
- ///< Great Britain or France
-
- Gr_China = Gr_Unknown, ///< Different authorities say:
- Gr_China_1, ///< 18 Dec 1911 -> 1 Jan 1912
- Gr_China_2, ///< 18 Dec 1928 -> 1 Jan 1929
-
- Gr_Czechoslovakia, ///< (Bohemia and Moravia) 6 Jan 1584 -> 17 Jan 1584
- Gr_Denmark, ///< (including Norway) 18 Feb 1700 -> 1 Mar 1700
- Gr_Egypt, ///< 1875
- Gr_Estonia, ///< 1918
- Gr_Finland, ///< Then part of Sweden
-
- Gr_France, ///< 9 Dec 1582 -> 20 Dec 1582
- Gr_France_Alsace, ///< 4 Feb 1682 -> 16 Feb 1682
- Gr_France_Lorraine, ///< 16 Feb 1760 -> 28 Feb 1760
- Gr_France_Strasbourg, ///< February 1682
-
- Gr_Germany = Gr_Unknown, ///< Different states on different dates:
- Gr_Germany_Catholic, ///< 1583-1585 (we take 1584)
- Gr_Germany_Prussia, ///< 22 Aug 1610 -> 2 Sep 1610
- Gr_Germany_Protestant, ///< 18 Feb 1700 -> 1 Mar 1700
-
- Gr_GreatBritain, ///< 2 Sep 1752 -> 14 Sep 1752 (use 'cal(1)')
-
- Gr_Greece, ///< 9 Mar 1924 -> 23 Mar 1924
- Gr_Hungary, ///< 21 Oct 1587 -> 1 Nov 1587
- Gr_Ireland = Gr_GreatBritain,
- Gr_Italy = Gr_Standard,
-
- Gr_Japan = Gr_Unknown, ///< Different authorities say:
- Gr_Japan_1, ///< 19 Dec 1872 -> 1 Jan 1873
- Gr_Japan_2, ///< 19 Dec 1892 -> 1 Jan 1893
- Gr_Japan_3, ///< 18 Dec 1918 -> 1 Jan 1919
-
- Gr_Latvia, ///< 1915-1918 (we take 1915)
- Gr_Lithuania, ///< 1915
- Gr_Luxemburg, ///< 14 Dec 1582 -> 25 Dec 1582
- Gr_Netherlands = Gr_Belgium, ///< (including Belgium) 1 Jan 1583
-
- /**
- Special case of Groningen.
-
- The Gregorian calendar was introduced twice in Groningen, first
- time 28 Feb 1583 was followed by 11 Mar 1583, then it has gone back
- to Julian in the summer of 1584 and then 13 Dec 1700 was followed
- by 12 Jan 1701 -- which is the date we take into account here.
- */
- Gr_Netherlands_Groningen, ///< 13 Dec 1700 -> 12 Jan 1701
- Gr_Netherlands_Gelderland, ///< 30 Jun 1700 -> 12 Jul 1700
- Gr_Netherlands_Utrecht, ///< (and Overijssel) 30 Nov 1700->12 Dec 1700
- Gr_Netherlands_Friesland, ///< (and Drenthe) 31 Dec 1700 -> 12 Jan 1701
-
- Gr_Norway = Gr_Denmark, ///< Then part of Denmark
- Gr_Poland = Gr_Standard,
- Gr_Portugal = Gr_Standard,
- Gr_Romania, ///< 31 Mar 1919 -> 14 Apr 1919
- Gr_Russia, ///< 31 Jan 1918 -> 14 Feb 1918
- Gr_Scotland = Gr_GreatBritain,
- Gr_Spain = Gr_Standard,
-
- /**
- Special case of Sweden.
-
- Sweden has a curious history. Sweden decided to make a gradual
- change from the Julian to the Gregorian calendar. By dropping every
- leap year from 1700 through 1740 the eleven superfluous days would
- be omitted and from 1 Mar 1740 they would be in sync with the
- Gregorian calendar. (But in the meantime they would be in sync with
- nobody!)
-
- So 1700 (which should have been a leap year in the Julian calendar)
- was not a leap year in Sweden. However, by mistake 1704 and 1708
- became leap years. This left Sweden out of synchronisation with
- both the Julian and the Gregorian world, so they decided to go back
- to the Julian calendar. In order to do this, they inserted an extra
- day in 1712, making that year a double leap year! So in 1712,
- February had 30 days in Sweden.
-
- Later, in 1753, Sweden changed to the Gregorian calendar by
- dropping 11 days like everyone else and this is what we use here.
- */
- Gr_Sweden = Gr_Finland, ///< 17 Feb 1753 -> 1 Mar 1753
-
- Gr_Switzerland = Gr_Unknown,///< Different cantons used different dates
- Gr_Switzerland_Catholic, ///< 1583, 1584 or 1597 (we take 1584)
- Gr_Switzerland_Protestant, ///< 31 Dec 1700 -> 12 Jan 1701
-
- Gr_Turkey, ///< 1 Jan 1927
- Gr_USA = Gr_GreatBritain,
- Gr_Wales = Gr_GreatBritain,
- Gr_Yugoslavia ///< 1919
- };
-
/**
Date calculations often depend on the country and wxDateTime allows to set
the country whose conventions should be used using SetCountry(). It takes
@@ -438,45 +309,33 @@ public:
object later.
*/
wxDateTime();
+
+ /**
+ Copy constructor.
+ */
+ wxDateTime(const wxDateTime& date);
+
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromTimeT" in wxPython.
- @endWxPythonOnly
*/
wxDateTime(time_t timet);
/**
Same as Set().
-
- @beginWxPythonOnly Unsupported. @endWxPythonOnly
*/
wxDateTime(const struct tm& tm);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromJDN" in wxPython.
- @endWxPythonOnly
*/
wxDateTime(double jdn);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromHMS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0,
wxDateTime_t second = 0, wxDateTime_t millisec = 0);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromDMY" in wxPython.
- @endWxPythonOnly
*/
- wxDateTime(wxDateTime_t day, Month month = Inv_Month,
+ wxDateTime(wxDateTime_t day, Month month,
int year = Inv_Year, wxDateTime_t hour = 0,
wxDateTime_t minute = 0, wxDateTime_t second = 0,
wxDateTime_t millisec = 0);
@@ -488,6 +347,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime(const struct _SYSTEMTIME& st);
@@ -499,20 +359,24 @@ public:
/**
Constructs the object from @a timet value holding the number of seconds
- since Jan 1, 1970.
+ since Jan 1, 1970 UTC.
- @beginWxPythonOnly
- This method is named "SetTimeT" in wxPython.
- @endWxPythonOnly
+ If @a timet is invalid, i.e. @code (time_t)-1 @endcode, wxDateTime
+ becomes invalid too, i.e. its IsValid() will return @false.
*/
wxDateTime& Set(time_t timet);
/**
Sets the date and time from the broken down representation in the
standard @a tm structure.
-
- @beginWxPythonOnly Unsupported. @endWxPythonOnly
*/
wxDateTime& Set(const struct tm& tm);
+
+ /**
+ Sets the date and time from the broken down representation in the
+ @a wxDateTime::Tm structure.
+ */
+ wxDateTime& Set(const Tm& tm);
+
/**
Sets the date from the so-called Julian Day Number.
@@ -520,26 +384,18 @@ public:
particular instant is the fractional number of days since 12 hours
Universal Coordinated Time (Greenwich mean noon) on January 1 of the
year -4712 in the Julian proleptic calendar.
-
- @beginWxPythonOnly
- This method is named "SetJDN" in wxPython.
- @endWxPythonOnly
*/
wxDateTime& Set(double jdn);
/**
Sets the date to be equal to Today() and the time from supplied
parameters.
-
- @beginWxPythonOnly
- This method is named "SetHMS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0,
wxDateTime_t second = 0, wxDateTime_t millisec = 0);
/**
Sets the date and time from the parameters.
*/
- wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
+ wxDateTime& Set(wxDateTime_t day, Month month,
int year = Inv_Year, wxDateTime_t hour = 0,
wxDateTime_t minute = 0, wxDateTime_t second = 0,
wxDateTime_t millisec = 0);
@@ -615,7 +471,7 @@ public:
/**
Returns the date and time in DOS format.
*/
- long unsigned int GetAsDOS() const;
+ unsigned long GetAsDOS() const;
/**
Initialize using the Windows SYSTEMTIME structure.
@@ -623,6 +479,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
@@ -632,6 +489,7 @@ public:
Output, pointer to Windows SYSTEMTIME
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
@@ -653,28 +511,28 @@ public:
/**
Returns the day in the given timezone (local one by default).
*/
- short unsigned int GetDay(const TimeZone& tz = Local) const;
+ unsigned short GetDay(const TimeZone& tz = Local) const;
/**
Returns the day of the year (in 1-366 range) in the given timezone
(local one by default).
*/
- short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
+ unsigned short GetDayOfYear(const TimeZone& tz = Local) const;
/**
Returns the hour in the given timezone (local one by default).
*/
- short unsigned int GetHour(const TimeZone& tz = Local) const;
+ unsigned short GetHour(const TimeZone& tz = Local) const;
/**
Returns the milliseconds in the given timezone (local one by default).
*/
- short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
+ unsigned short GetMillisecond(const TimeZone& tz = Local) const;
/**
Returns the minute in the given timezone (local one by default).
*/
- short unsigned int GetMinute(const TimeZone& tz = Local) const;
+ unsigned short GetMinute(const TimeZone& tz = Local) const;
/**
Returns the month in the given timezone (local one by default).
@@ -684,11 +542,13 @@ public:
/**
Returns the seconds in the given timezone (local one by default).
*/
- short unsigned int GetSecond(const TimeZone& tz = Local) const;
+ unsigned short GetSecond(const TimeZone& tz = Local) const;
/**
- Returns the number of seconds since Jan 1, 1970. An assert failure will
- occur if the date is not in the range covered by @c time_t type.
+ Returns the number of seconds since Jan 1, 1970 UTC.
+
+ An assert failure will occur if the date is not in the range covered by
+ @c time_t type, use GetValue() if you work with dates outside of it.
*/
time_t GetTicks() const;
@@ -732,13 +592,6 @@ public:
*/
int GetYear(const TimeZone& tz = Local) const;
- /**
- Returns @true if the given date is later than the date of adoption of
- the Gregorian calendar in the given country (and hence the Gregorian
- calendar calculations make sense for it).
- */
- bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
-
/**
Returns @true if the object represents a valid time moment.
*/
@@ -773,7 +626,7 @@ public:
/**
Returns @true if the date is equal to another one up to the given time
- interval, i.e. if the absolute difference between the two dates is less
+ interval, i.e.\ if the absolute difference between the two dates is less
than this interval.
*/
bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
@@ -832,67 +685,35 @@ public:
/**
Adds the given date span to this object.
-
- @beginWxPythonOnly
- This method is named "AddDS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime Add(const wxDateSpan& diff) const;
/**
Adds the given date span to this object.
-
- @beginWxPythonOnly
- This method is named "AddDS" in wxPython.
- @endWxPythonOnly
*/
- wxDateTime Add(const wxDateSpan& diff);
+ wxDateTime& Add(const wxDateSpan& diff);
/**
Adds the given time span to this object.
-
- @beginWxPythonOnly
- This method is named "AddTS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime Add(const wxTimeSpan& diff) const;
/**
Adds the given time span to this object.
-
- @beginWxPythonOnly
- This method is named "AddTS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime& Add(const wxTimeSpan& diff);
/**
Subtracts the given time span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractTS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime Subtract(const wxTimeSpan& diff) const;
/**
Subtracts the given time span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractTS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime& Subtract(const wxTimeSpan& diff);
/**
Subtracts the given date span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractDS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime Subtract(const wxDateSpan& diff) const;
/**
Subtracts the given date span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractDS" in wxPython.
- @endWxPythonOnly
*/
wxDateTime& Subtract(const wxDateSpan& diff);
/**
@@ -900,23 +721,53 @@ public:
them as a wxTimeSpan.
*/
wxTimeSpan Subtract(const wxDateTime& dt) const;
+ /**
+ Returns the difference between this object and @a dt as a wxDateSpan.
+
+ This method allows to find the number of entire years, months, weeks and
+ days between @a dt and this date.
+
+ @since 2.9.5
+ */
+ wxDateSpan DiffAsDateSpan(const wxDateTime& dt) const;
/**
Adds the given date span to this object.
*/
- wxDateTime operator+=(const wxDateSpan& diff);
+ wxDateTime& operator+=(const wxDateSpan& diff);
+ /**
+ Adds the given date span to this object.
+ */
+ wxDateTime operator+(const wxDateSpan& ds) const;
/**
Subtracts the given date span from this object.
*/
wxDateTime& operator-=(const wxDateSpan& diff);
+ /**
+ Subtracts the given date span from this object.
+ */
+ wxDateTime operator-(const wxDateSpan& ds) const;
/**
Adds the given time span to this object.
*/
wxDateTime& operator+=(const wxTimeSpan& diff);
+ /**
+ Adds the given time span to this object.
+ */
+ wxDateTime operator+(const wxTimeSpan& ts) const;
/**
Subtracts the given time span from this object.
*/
wxDateTime& operator-=(const wxTimeSpan& diff);
+ /**
+ Subtracts the given time span from this object.
+ */
+ wxDateTime operator-(const wxTimeSpan& ts) const;
+ /**
+ Subtracts another date from this one and returns the difference between
+ them as a wxTimeSpan.
+ */
+ wxTimeSpan operator-(const wxDateTime& dt2) const;
//@}
@@ -1256,7 +1107,7 @@ public:
WeekFlags flags = Monday_First);
/**
- Sets the date to the day number @a yday in the same year (i.e., unlike
+ Sets the date to the day number @a yday in the same year (i.e.\ unlike
the other functions, this one does not use the current year). The day
number should be in the range 1-366 for the leap years and 1-365 for
the other ones.
@@ -1381,7 +1232,7 @@ public:
/**
- Converts the year in absolute notation (i.e. a number which can be
+ Converts the year in absolute notation (i.e.\ a number which can be
negative, positive or zero) to the year in BC/AD notation. For the
positive years, nothing is done, but the year 0 is year 1 BC and so for
other years there is a difference of 1.
@@ -1423,7 +1274,7 @@ public:
Country country = Country_Default);
/**
- Get the current century, i.e. first two digits of the year, in given
+ Get the current century, i.e.\ first two digits of the year, in given
calendar (only Gregorian is currently supported).
*/
static int GetCentury(int year);
@@ -1504,20 +1355,12 @@ public:
/**
Returns the number of days in the given year. The only supported value
for @a cal currently is @c Gregorian.
-
- @beginWxPythonOnly
- This method is named "GetNumberOfDaysInYear" in wxPython.
- @endWxPythonOnly
*/
static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
/**
Returns the number of days in the given month of the given year. The
only supported value for @a cal currently is @c Gregorian.
-
- @beginWxPythonOnly
- This method is named "GetNumberOfDaysInMonth" in wxPython.
- @endWxPythonOnly
*/
static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
Calendar cal = Gregorian);
@@ -1588,9 +1431,8 @@ public:
printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
@endcode
- @note This function is accurate up to seconds. UNow() should be used
- for better precision, but it is less efficient and might not be
- available on all platforms.
+ @note This function is accurate up to seconds. UNow() can be used if
+ better precision is required.
@see Today()
*/
@@ -1618,18 +1460,20 @@ public:
/**
Returns the object corresponding to the midnight of the current day
- (i.e. the same as Now(), but the time part is set to 0).
+ (i.e.\ the same as Now(), but the time part is set to 0).
@see Now()
*/
static wxDateTime Today();
/**
- Returns the object corresponding to the current time including the
- milliseconds if a function to get time with such precision is available
- on the current platform (supported under most Unices and Win32).
+ Returns the object corresponding to the current UTC time including the
+ milliseconds.
- @see Now()
+ Notice that unlike Now(), this method creates a wxDateTime object
+ corresponding to UTC, not local, time.
+
+ @see Now(), wxGetUTCTimeMillis()
*/
static wxDateTime UNow();
};
@@ -1755,6 +1599,16 @@ public:
*/
int GetMonths() const;
+ /**
+ Returns the combined number of months in this date span, counting both
+ years and months.
+
+ @see GetYears(), GetMonths()
+
+ @since 2.9.5
+ */
+ int GetTotalMonths() const;
+
/**
Returns the combined number of days in this date span, counting both
weeks and days. This doesn't take months or years into account.
@@ -1912,7 +1766,7 @@ public:
/**
Returns @true if this date span is different from the other one.
*/
- bool operator!=(const wxDateSpan&) const;
+ bool operator!=(const wxDateSpan& other) const;
/**
Returns @true if this date span is equal to the other one. Two date
@@ -1920,7 +1774,7 @@ public:
years and months and the same total number of days (counting both days
and weeks).
*/
- bool operator==(const wxDateSpan&) const;
+ bool operator==(const wxDateSpan& other) const;
};
@@ -2002,7 +1856,7 @@ public:
specifier of larger unit, only the rest part is taken, otherwise the
full value is used.
*/
- wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
+ wxString Format(const wxString& format = wxDefaultTimeSpanFormat) const;
/**
Returns the difference in number of days.
@@ -2055,7 +1909,7 @@ public:
bool IsEqualTo(const wxTimeSpan& ts) const;
/**
- Compares two timespans: works with the absolute values, i.e. -2 hours
+ Compares two timespans: works with the absolute values, i.e.\ -2 hours
is longer than 1 hour. Also, it will return @false if the timespans are
equal in absolute value.
*/
@@ -2077,7 +1931,7 @@ public:
bool IsPositive() const;
/**
- Compares two timespans: works with the absolute values, i.e. 1 hour is
+ Compares two timespans: works with the absolute values, i.e.\ 1 hour is
shorter than -2 hours. Also, it will return @false if the timespans are
equal in absolute value.
*/