X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e73d7e569fbeac0048ad6d117f6eb047e3d31e2f..e4097f77c440b1f31a80fe273cc732c14d606096:/interface/wx/datetime.h diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index b517d4d882..f7f1906921 100644 --- a/interface/wx/datetime.h +++ b/interface/wx/datetime.h @@ -2,7 +2,6 @@ // Name: datetime.h // Purpose: interface of wxDateTime // Author: wxWidgets team -// RCS-ID: $Id$ // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -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 @@ -446,41 +317,23 @@ public: /** 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, int year = Inv_Year, wxDateTime_t hour = 0, @@ -506,18 +359,15 @@ 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); @@ -534,24 +384,30 @@ 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 + See the full Set() overload for the remarks about DST. */ 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. + + If the function parameters are invalid, e.g. @a month is February and + @a day is 30, the object is left in an invalid state, i.e. IsValid() + method will return @false. + + If the specified time moment is invalid due to DST, i.e. it falls into + the "missing" hour on the date on which the DST starts, a valid + wxDateTime object is still constructed but its hour component is moved + forward to ensure that it corresponds to a valid moment in the local + time zone. For example, in the CET time zone the DST started on + 2013-03-31T02:00:00 in 2013 and so setting the object to 2:30 at this + date actually sets the hour to 3, and not 2. */ wxDateTime& Set(wxDateTime_t day, Month month, int year = Inv_Year, wxDateTime_t hour = 0, @@ -703,8 +559,10 @@ public: 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; @@ -748,13 +606,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. */ @@ -789,7 +640,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; @@ -848,67 +699,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); /** @@ -916,23 +735,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); + /** + 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; //@} @@ -1272,7 +1121,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. @@ -1397,7 +1246,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. @@ -1439,7 +1288,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); @@ -1520,20 +1369,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); @@ -1604,9 +1445,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() */ @@ -1634,18 +1474,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(); }; @@ -1771,6 +1613,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. @@ -2071,7 +1923,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. */ @@ -2093,7 +1945,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. */