X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/882678ebb43804d34d20ba8781647fe136ae67d9..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/datetime.h?ds=sidebyside diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index 9505c3d9a6..c181b9c75e 100644 --- a/interface/wx/datetime.h +++ b/interface/wx/datetime.h @@ -2,39 +2,102 @@ // Name: datetime.h // Purpose: interface of wxDateTime // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// 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 milliseconds. + Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are + defined. This constant will be different from any valid wxDateTime object. - @section datetime_constants Constants - Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are - defined. This constant will be different from any valid wxDateTime object. + @section datetime_static Static Functions + + All static functions either set or return the static variables of + wxDateSpan (the country), return the current moment, year, month or number + of days in it, or do some general calendar-related actions. + + Please note that although several function accept an extra Calendar + parameter, it is currently ignored as only the Gregorian calendar is + supported. Future versions will support other calendars. + + @section datetime_formatting Date Formatting and Parsing + + The date formatting and parsing functions convert wxDateTime objects to and + from text. The conversions to text are mostly trivial: you can either do it + using the default date and time representations for the current locale + (FormatDate() and FormatTime()), using the international standard + representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and + FormatISOCombined()) or by specifying any format at all and using Format() + directly. + + The conversions from text are more interesting, as there are much more + possibilities to care about. The simplest cases can be taken care of with + ParseFormat() which can parse any date in the given (rigid) format. + ParseRfc822Date() is another function for parsing dates in predefined + format -- the one of RFC 822 which (still...) defines the format of email + messages on the Internet. This format cannot be described with + @c strptime(3)-like format strings used by Format(), hence the need for a + separate function. + + But the most interesting functions are ParseTime(), ParseDate() and + ParseDateTime(). They try to parse the date and time (or only one of them) + in 'free' format, i.e. allow them to be specified in any of possible ways. + These functions will usually be used to parse the (interactive) user input + which is not bound to be in any predefined format. As an example, + ParseDate() can parse the strings such as "tomorrow", "March first" and + even "next Sunday". + + Finally notice that each of the parsing functions is available in several + overloads: if the input string is a narrow (@c char *) string, then a + narrow pointer is returned. If the input string is a wide string, a wide + char pointer is returned. Finally, if the input parameter is a wxString, a + narrow char pointer is also returned for backwards compatibility but there + is also an additional argument of wxString::const_iterator type in which, + if it is not @NULL, an iterator pointing to the end of the scanned string + part is returned. + + + @library{wxbase} + @category{data} + + @stdobjects + - ::wxDefaultDateTime - All the following constants are defined inside wxDateTime class (i.e., to - refer to them you should prepend their names with "wxDateTime::"). + @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl +*/ +class wxDateTime +{ +public: + /** + A small unsigned integer type for storing things like minutes, + seconds &c. It should be at least short (i.e. not char) to contain + the number of milliseconds - it may also be 'int' because there is + no size penalty associated with it in our code, we don't store any + data in this format. + */ + typedef unsigned short wxDateTime_t; - Time zone symbolic names: - @code + /** + Time zone symbolic names. + */ enum TZ { - // the time in the current time zone + /// the time in the current time zone Local, - // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be - // consequent numbers, so writing something like `GMT0 + offset' is - // safe if abs(offset) <= 12 + //@{ + /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be + /// consequent numbers, so writing something like `GMT0 + offset' is + /// safe if abs(offset) <= 12 // underscore stands for minus GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7, @@ -44,91 +107,72 @@ GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13, // Note that GMT12 and GMT_12 are not the same: there is a difference // of exactly one day between them + //@} // some symbolic names for TZ // Europe - WET = GMT0, // Western Europe Time - WEST = GMT1, // Western Europe Summer Time - CET = GMT1, // Central Europe Time - CEST = GMT2, // Central Europe Summer Time - EET = GMT2, // Eastern Europe Time - EEST = GMT3, // Eastern Europe Summer Time - MSK = GMT3, // Moscow Time - MSD = GMT4, // Moscow Summer Time + WET = GMT0, //!< Western Europe Time + WEST = GMT1, //!< Western Europe Summer Time + CET = GMT1, //!< Central Europe Time + CEST = GMT2, //!< Central Europe Summer Time + EET = GMT2, //!< Eastern Europe Time + EEST = GMT3, //!< Eastern Europe Summer Time + MSK = GMT3, //!< Moscow Time + MSD = GMT4, //!< Moscow Summer Time // US and Canada - AST = GMT_4, // Atlantic Standard Time - ADT = GMT_3, // Atlantic Daylight Time - EST = GMT_5, // Eastern Standard Time - EDT = GMT_4, // Eastern Daylight Saving Time - CST = GMT_6, // Central Standard Time - CDT = GMT_5, // Central Daylight Saving Time - MST = GMT_7, // Mountain Standard Time - MDT = GMT_6, // Mountain Daylight Saving Time - PST = GMT_8, // Pacific Standard Time - PDT = GMT_7, // Pacific Daylight Saving Time - HST = GMT_10, // Hawaiian Standard Time - AKST = GMT_9, // Alaska Standard Time - AKDT = GMT_8, // Alaska Daylight Saving Time + AST = GMT_4, //!< Atlantic Standard Time + ADT = GMT_3, //!< Atlantic Daylight Time + EST = GMT_5, //!< Eastern Standard Time + EDT = GMT_4, //!< Eastern Daylight Saving Time + CST = GMT_6, //!< Central Standard Time + CDT = GMT_5, //!< Central Daylight Saving Time + MST = GMT_7, //!< Mountain Standard Time + MDT = GMT_6, //!< Mountain Daylight Saving Time + PST = GMT_8, //!< Pacific Standard Time + PDT = GMT_7, //!< Pacific Daylight Saving Time + HST = GMT_10, //!< Hawaiian Standard Time + AKST = GMT_9, //!< Alaska Standard Time + AKDT = GMT_8, //!< Alaska Daylight Saving Time // Australia - A_WST = GMT8, // Western Standard Time - A_CST = GMT13 + 1, // Central Standard Time (+9.5) - A_EST = GMT10, // Eastern Standard Time - A_ESST = GMT11, // Eastern Summer Time + A_WST = GMT8, //!< Western Standard Time + A_CST = GMT13 + 1, //!< Central Standard Time (+9.5) + A_EST = GMT10, //!< Eastern Standard Time + A_ESST = GMT11, //!< Eastern Summer Time // New Zealand - NZST = GMT12, // Standard Time - NZDT = GMT13, // Daylight Saving Time + NZST = GMT12, //!< Standard Time + NZDT = GMT13, //!< Daylight Saving Time - // Universal Coordinated Time = the new and politically correct name - // for GMT + /// Universal Coordinated Time = the new and politically correct name + /// for GMT. UTC = GMT0 }; - @endcode - - Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and - Inv_Month for an invalid month are the values of @c wxDateTime::Month enum. - - Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values - in @c wxDateTime::WeekDay enum. - - Finally, Inv_Year is defined to be an invalid value for year parameter. - - GetMonthName() and GetWeekDayName() functions use the following flags: - - @code - enum NameFlags - { - Name_Full = 0x01, // return full name - Name_Abbr = 0x02 // return abbreviated name - }; - @endcode - - Several functions accept an extra parameter specifying the calendar to use - (although most of them only support now the Gregorian calendar). This - parameters is one of the following values: - @code + /** + Several functions accept an extra parameter specifying the calendar to use + (although most of them only support now the Gregorian calendar). This + parameters is one of the following values. + */ enum Calendar { - Gregorian, // calendar currently in use in Western countries - Julian // calendar in use since -45 until the 1582 (or later) + Gregorian, ///< calendar currently in use in Western countries + Julian ///< calendar in use since -45 until the 1582 (or later) }; - @endcode - - Date calculations often depend on the country and wxDateTime allows to set - the country whose conventions should be used using SetCountry(). It takes - one of the following values as parameter: - @code + /** + Date calculations often depend on the country and wxDateTime allows to set + the country whose conventions should be used using SetCountry(). It takes + one of the following values as parameter. + */ enum Country { - Country_Unknown, // no special information for this country - Country_Default, // set the default country with SetCountry() method - // or use the default country with any other + Country_Unknown, ///< no special information for this country + Country_Default, ///< set the default country with SetCountry() method + ///< or use the default country with any other Country_WesternEurope_Start, Country_EEC = Country_WesternEurope_Start, @@ -141,98 +185,122 @@ USA }; - @endcode - Different parts of the world use different conventions for the week start. - In some countries, the week starts on Sunday, while in others -- on Monday. - The ISO standard doesn't address this issue, so we support both conventions - in the functions whose result depends on it (GetWeekOfYear() and - GetWeekOfMonth()). + /// symbolic names for the months + enum Month + { + Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, - The desired behvaiour may be specified by giving one of the following - constants as argument to these functions: + /// Invalid month value. + Inv_Month + }; - @code - enum WeekFlags + /// symbolic names for the weekdays + enum WeekDay { - Default_First, // Sunday_First for US, Monday_First for the rest - Monday_First, // week starts with a Monday - Sunday_First // week starts with a Sunday - }; - @endcode + Sun, Mon, Tue, Wed, Thu, Fri, Sat, + /// Invalid week day value. + Inv_WeekDay + }; - @section datetime_static Static Functions + /// invalid value for the year + enum Year + { + Inv_Year = SHRT_MIN // should hold in wxDateTime_t + }; - All static functions either set or return the static variables of - wxDateSpan (the country), return the current moment, year, month or number - of days in it, or do some general calendar-related actions. + /** + Flags to be used with GetMonthName() and GetWeekDayName() functions. + */ + enum NameFlags + { + Name_Full = 0x01, ///< return full name + Name_Abbr = 0x02 ///< return abbreviated name + }; - Please note that although several function accept an extra Calendar - parameter, it is currently ignored as only the Gregorian calendar is - supported. Future versions will support other calendars. + /** + Different parts of the world use different conventions for the week start. + In some countries, the week starts on Sunday, while in others -- on Monday. + The ISO standard doesn't address this issue, so we support both conventions + in the functions whose result depends on it (GetWeekOfYear() and + GetWeekOfMonth()). - @beginWxPythonOnly - These methods are standalone functions named - "wxDateTime_" in wxPython. - @endWxPythonOnly + The desired behaviour may be specified by giving one of the following + constants as argument to these functions. + */ + enum WeekFlags + { + Default_First, ///< Sunday_First for US, Monday_First for the rest + Monday_First, ///< week starts with a Monday + Sunday_First ///< week starts with a Sunday + }; - @section datetime_formatting Date Formatting and Parsing + /** + Class representing a time zone. - The date formatting and parsing functions convert wxDateTime objects to and - from text. The conversions to text are mostly trivial: you can either do it - using the default date and time representations for the current locale - (FormatDate() and FormatTime()), using the international standard - representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and - FormatISOCombined()) or by specifying any format at all and using Format() - directly. + The representation is simply the offset, in seconds, from UTC. + */ + class WXDLLIMPEXP_BASE TimeZone + { + public: + /// Constructor for a named time zone. + TimeZone(TZ tz); - The conversions from text are more interesting, as there are much more - possibilities to care about. The simplest cases can be taken care of with - ParseFormat() which can parse any date in the given (rigid) format. - ParseRfc822Date() is another function for parsing dates in predefined - format -- the one of RFC 822 which (still...) defines the format of email - messages on the Internet. This format can not be described with - @c strptime(3)-like format strings used by Format(), hence the need for a - separate function. + /// Constructor for the given offset in seconds. + TimeZone(long offset = 0); - But the most interesting functions are ParseTime(), ParseDate() and - ParseDateTime(). They try to parse the date and time (or only one of them) - in 'free' format, i.e. allow them to be specified in any of possible ways. - These functions will usually be used to parse the (interactive) user input - which is not bound to be in any predefined format. As an example, - ParseDateTime() can parse the strings such as "tomorrow", "March first" and - even "next Sunday". + /// Create a time zone with the given offset in seconds. + static TimeZone Make(long offset); - Finally notice that each of the parsing functions is available in several - overloads: if the input string is a narrow (@c char *) string, then a - narrow pointer is returned. If the input string is a wide string, a wide - char pointer is returned. Finally, if the input parameter is a wxString, a - narrow char pointer is also returned for backwards compatibility but there - is also an additional argument of wxString::const_iterator type in which, - if it is not @NULL, an iterator pointing to the end of the scanned string - part is returned. + /// Return the offset of this time zone from UTC, in seconds. + long GetOffset() const; + }; + /** + Contains broken down date-time representation. - @library{wxbase} - @category{data} + This struct is analogous to standard C struct tm and uses + the same, not always immediately obvious, conventions for its members: + notably its mon and mday fields count from 0 while yday counts from 1. + */ + struct Tm + { + wxDateTime_t msec, ///< Number of milliseconds. + sec, ///< Seconds in 0..59 (60 with leap seconds) range. + min, ///< Minutes in 0..59 range. + hour, ///< Hours since midnight in 0..23 range. + mday, ///< Day of the month in 1..31 range. + yday; ///< Day of the year in 0..365 range. + Month mon; ///< Month, as an enumerated constant. + int year; ///< Year. + + /** + Check if the given date/time is valid (in Gregorian calendar). + + Return @false if the components don't correspond to a correct date. + */ + bool IsValid() const; + + /** + Return the week day corresponding to this date. + + Unlike the other fields, the week day is not always available and + so must be accessed using this method as it is computed on demand + when it is called. + */ + WeekDay GetWeekDay(); + }; - @stdobjects - - ::wxDefaultDateTime - @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl -*/ -class wxDateTime -{ -public: /** @name Constructors, Assignment Operators and Setters Constructors and various Set() methods are collected here. If you construct a date object from separate values for day, month and year, you should use IsValid() method to check that the values were correct - as constructors can not return an error code. + as constructors cannot return an error code. */ //@{ @@ -241,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); @@ -291,6 +347,7 @@ public: Input, Windows SYSTEMTIME reference @since 2.9.0 @remarks MSW only + @onlyfor{wxmsw} */ wxDateTime(const struct _SYSTEMTIME& st); @@ -302,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. @@ -323,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); @@ -418,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. @@ -426,6 +479,7 @@ public: Input, Windows SYSTEMTIME reference @since 2.9.0 @remarks MSW only + @onlyfor{wxmsw} */ wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st); @@ -435,6 +489,7 @@ public: Output, pointer to Windows SYSTEMTIME @since 2.9.0 @remarks MSW only + @onlyfor{wxmsw} */ void GetAsMSWSysTime(struct _SYSTEMTIME* st) const; @@ -456,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). @@ -487,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; @@ -509,8 +566,7 @@ public: Returns the ordinal number of the week in the month (in 1-5 range). As GetWeekOfYear(), this function supports both conventions for the - week start. See the description of these @c WeekFlags in the - @ref datetime_constants section. + week start. */ wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, const TimeZone& tz = Local) const; @@ -524,10 +580,9 @@ public: year. Accordingly, the week number will always be in 1-53 range (52 for non-leap years). - The function depends on the @ref datetime_constants "week start" - convention specified by the @a flags argument but its results for - @c Sunday_First are not well-defined as the ISO definition quoted above - applies to the weeks starting on Monday only. + The function depends on the week start convention specified by the @a flags + argument but its results for @c Sunday_First are not well-defined as the + ISO definition quoted above applies to the weeks starting on Monday only. */ wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, const TimeZone& tz = Local) const; @@ -537,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. */ @@ -578,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; @@ -637,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); /** @@ -705,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); /** Adds the given date span to this object. */ - wxDateTime operator+=(const wxDateSpan& diff); + 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; //@} @@ -736,8 +782,8 @@ public: /** This function does the same as the standard ANSI C @c strftime(3) - function. Please see its description for the meaning of @a format - parameter. + function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html). + Please see its description for the meaning of @a format parameter. It also accepts a few wxWidgets-specific extensions: you can optionally specify the width of the field to follow using @c printf(3)-like syntax @@ -759,7 +805,7 @@ public: Returns the combined date-time representation in the ISO 8601 format @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces the result exactly corresponding to the ISO standard, but it can also - be useful to use a space as seprator if a more human-readable combined + be useful to use a space as separator if a more human-readable combined date-time representation is needed. @see FormatISODate(), FormatISOTime(), ParseISOCombined() @@ -786,67 +832,33 @@ public: /** This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + be specified. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const wxString& date, - wxString::const_iterator* end = NULL); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + It is thus less flexible then ParseDateTime(), but also has less + chances to misinterpret the user input. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const char* date); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + See ParseFormat() for the description of function parameters and return + value. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + @see Format() */ - const wchar_t* ParseDate(const wchar_t* date); + bool ParseDate(const wxString& date, wxString::const_iterator *end); /** Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDateTime(const wxString& datetime, - wxString::const_iterator* end = NULL); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. + format. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDateTime(const char* datetime); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. + This function tries as hard as it can to interpret the given string as + date and time. Unlike ParseRfc822Date(), it will accept anything that + may be accepted and will only reject strings which cannot be parsed in + any way at all. Notice that the function will fail if either date or + time part is present but not both, use ParseDate() or ParseTime() to + parse strings containing just the date or time component. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const wchar_t* ParseDateTime(const wchar_t* datetime); + bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end); /** This function parses the string @a date according to the given @@ -867,63 +879,53 @@ public: @a dateDef. If it is not specified, Today() is used as the default date. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseFormat(const wxString& date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime, - wxString::const_iterator* end = NULL); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. + Example of using this function: + @code + wxDateTime dt; + wxString str = "..."; + wxString::const_iterator end; + if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) ) + ... parsing failed ... + else if ( end == str.end() ) + ... entire string parsed ... + else + ... wxString(end, str.end()) left over ... + @endcode - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. + @param date + The string to be parsed. + @param format + strptime()-like format string. + @param dateDef + Used to fill in the date components not specified in the @a date + string. + @param end + Will be filled with the iterator pointing to the location where the + parsing stopped if the function returns @true. If the entire string + was consumed, it is set to @c date.end(). Notice that this argument + must be non-@NULL. + @return + @true if at least part of the string was parsed successfully, + @false otherwise. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + @see Format() */ - const char* ParseFormat(const char* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. + bool ParseFormat(const wxString& date, + const wxString& format, + const wxDateTime& dateDef, + wxString::const_iterator *end); - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. + /** + @overload + */ + bool ParseFormat(const wxString& date, + const wxString& format, + wxString::const_iterator *end); - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ - const wchar_t* ParseFormat(const wchar_t* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); + bool ParseFormat(const wxString& date, wxString::const_iterator *end); /** This function parses the string containing the date and time in ISO @@ -969,73 +971,20 @@ public: string which is not RFC 822 compliant. If you need to parse date formatted in more free ways, you should use ParseDateTime() or ParseDate() instead. - */ - const char* ParseRfc822Date(const wxString& date, - wxString::const_iterator* end = NULL); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. - */ - const char* ParseRfc822Date(const char* date); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. + See ParseFormat() for the description of function parameters and return + value. */ - const wchar_t* ParseRfc822Date(const wchar_t* date); + bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end); /** This functions is like ParseDateTime(), but only allows the time to be specified in the input string. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const char* ParseTime(const wxString& time, - wxString::const_iterator* end = NULL); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseTime(const char* time); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseTime(const wchar_t* time); + bool ParseTime(const wxString& time, wxString::const_iterator *end); //@} @@ -1158,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. @@ -1283,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. @@ -1325,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); @@ -1351,8 +1300,53 @@ public: static int GetCurrentYear(Calendar cal = Gregorian); /** - Gets the full (default) or abbreviated (specify @c Name_Abbr name of - the given month. + Return the standard English name of the given month. + + This function always returns "January" or "Jan" for January, use + GetMonthName() to retrieve the name of the month in the users current + locale. + + @param month + One of wxDateTime::Jan, ..., wxDateTime::Dec values. + @param flags + Either Name_Full (default) or Name_Abbr. + + @see GetEnglishWeekDayName() + + @since 2.9.0 + */ + static wxString GetEnglishMonthName(Month month, + NameFlags flags = Name_Full); + + /** + Return the standard English name of the given week day. + + This function always returns "Monday" or "Mon" for Monday, use + GetWeekDayName() to retrieve the name of the month in the users current + locale. + + @param weekday + One of wxDateTime::Sun, ..., wxDateTime::Sat values. + @param flags + Either Name_Full (default) or Name_Abbr. + + @see GetEnglishMonthName() + + @since 2.9.0 + */ + static wxString GetEnglishWeekDayName(WeekDay weekday, + NameFlags flags = Name_Full); + + /** + Gets the full (default) or abbreviated name of the given month. + + This function returns the name in the current locale, use + GetEnglishMonthName() to get the untranslated name if necessary. + + @param month + One of wxDateTime::Jan, ..., wxDateTime::Dec values. + @param flags + Either Name_Full (default) or Name_Abbr. @see GetWeekDayName() */ @@ -1361,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); @@ -1385,7 +1371,7 @@ public: static time_t GetTimeNow(); /** - Returns the current time broken down using the buffer whose adress is + Returns the current time broken down using the buffer whose address is passed to the function with @a tm to store the result. */ static tm* GetTmNow(struct tm *tm); @@ -1400,13 +1386,20 @@ public: static tm* GetTmNow(); /** - Gets the full (default) or abbreviated (specify @c Name_Abbr) name of - the given week day. + Gets the full (default) or abbreviated name of the given week day. + + This function returns the name in the current locale, use + GetEnglishWeekDayName() to get the untranslated name if necessary. + + @param weekday + One of wxDateTime::Sun, ..., wxDateTime::Sat values. + @param flags + Either Name_Full (default) or Name_Abbr. @see GetMonthName() */ static wxString GetWeekDayName(WeekDay weekday, - NameFlags flags = Name_Full); + NameFlags flags = Name_Full); /** Returns @true if DST was used in the given year (the current one by @@ -1438,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() */ @@ -1450,9 +1442,6 @@ public: Sets the country to use by default. This setting influences the DST calculations, date formatting and other things. - The possible values for @a country parameter are enumerated in the - @ref datetime_constants section. - @see GetCountry() */ static void SetCountry(Country country); @@ -1471,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(); }; @@ -1495,6 +1486,10 @@ public: */ const wxDateTime wxDefaultDateTime; +/* + wxInvalidDateTime is an alias for wxDefaultDateTime. +*/ +#define wxInvalidDateTime wxDefaultDateTime /** @@ -1604,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. @@ -1761,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 @@ -1769,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; }; @@ -1851,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. @@ -1904,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. */ @@ -1926,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. */ @@ -2045,7 +2050,7 @@ public: @todo Write wxDateTimeHolidayAuthority documentation. @library{wxbase} - @category{misc} + @category{data} */ class wxDateTimeHolidayAuthority {