X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e73d7e569fbeac0048ad6d117f6eb047e3d31e2f..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/datetime.h diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index b517d4d882..ecd0b73b3c 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 @@ -446,41 +439,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 +481,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,19 +506,11 @@ 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); @@ -703,8 +667,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; @@ -789,7 +755,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 +814,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 +850,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 +1236,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 +1361,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 +1403,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 +1484,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 +1560,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 +1589,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 +1728,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 +2038,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 +2060,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. */