X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..4aa59c3df6c324a6e6f9d540eac25e88b9c28acd:/interface/datetime.h?ds=sidebyside diff --git a/interface/datetime.h b/interface/datetime.h index 47cb2d0705..d964e6e599 100644 --- a/interface/datetime.h +++ b/interface/datetime.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: datetime.h -// Purpose: documentation for wxDateTime class +// Purpose: interface of wxDateTime // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -12,357 +12,415 @@ wxDateTime class represents an absolute moment in the 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. + + + @section datetime_constants Constants + + Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are + defined. This constant will be different from any valid wxDateTime object. + + All the following constants are defined inside wxDateTime class (i.e., to + refer to them you should prepend their names with "wxDateTime::"). + + Time zone symbolic names: + + @code + enum TZ + { + // 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 + + // underscore stands for minus + GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7, + GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1, + GMT0, + GMT1, GMT2, GMT3, GMT4, GMT5, GMT6, + 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 + + // 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 + + // 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 + + // New Zealand + NZST = GMT12, // Standard Time + NZDT = GMT13, // Daylight Saving Time + + // 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 + enum Calendar + { + 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 + 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_WesternEurope_Start, + Country_EEC = Country_WesternEurope_Start, + France, + Germany, + UK, + Country_WesternEurope_End = UK, + + Russia, + + 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()). + + The desired behvaiour may be specified by giving one of the following + constants as argument to these functions: + + @code + 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 + }; + @endcode + + + @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. + + @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 + 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 can not 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, + ParseDateTime() 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} - @seealso - @ref overview_wxdatetimeoverview "Date classes overview", wxTimeSpan, - wxDateSpan, wxCalendarCtrl + @stdobjects + - ::wxDefaultDateTime + + @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl */ class wxDateTime { public: /** - Same as @ref setdate() Set + @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. + */ + //@{ + + /** + Default constructor. Use one of the Set() functions to initialize the + object later. + */ + wxDateTime(); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromTimeT" in wxPython. + @endWxPythonOnly + */ + wxDateTime& wxDateTime(time_t timet); + /** + Same as Set(). + + @beginWxPythonOnly Unsupported. @endWxPythonOnly + */ + wxDateTime& wxDateTime(const struct tm& tm); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromJDN" in wxPython. + @endWxPythonOnly + */ + wxDateTime& wxDateTime(double jdn); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromHMS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& 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, - int Inv_Year, wxDateTime_t hour = 0, - wxDateTime_t minute = 0, - wxDateTime_t second = 0, + int year = Inv_Year, wxDateTime_t hour = 0, + wxDateTime_t minute = 0, wxDateTime_t second = 0, wxDateTime_t millisec = 0); /** - Here are the trivial accessors. Other functions, which might have to perform - some more complicated calculations to find the answer are under the - @ref overview_datetimecalculations "Calendar calculations" section. - IsValid() - - GetTicks() - - GetCentury() - - GetYear() - - GetMonth() - - GetDay() - - GetWeekDay() - - GetHour() - - GetMinute() - - GetSecond() - - GetMillisecond() - - GetDayOfYear() - - GetWeekOfYear() - - GetWeekOfMonth() - - GetYearDay() - - IsWorkDay() - - IsGregorianDate() - - GetAsDOS() + Reset time to midnight (00:00:00) without changing the date. */ + wxDateTime& ResetTime(); - - //@{ /** - Adds the given date span to this object. + Constructs the object from @a timet value holding the number of seconds + since Jan 1, 1970. + + @beginWxPythonOnly + This method is named "SetTimeT" in wxPython. + @endWxPythonOnly */ - wxDateTime Add(const wxDateSpan& diff); - const wxDateTime& Add(const wxDateSpan& diff); - wxDateTime operator+=(const wxDateSpan& diff); - //@} + 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); /** - Some degree of support for the date units used in astronomy and/or history is - provided. You can construct a wxDateTime object from a - @ref setjdn() JDN and you may also get its JDN, - @ref getmodifiedjuliandaynumber() MJD or - @ref getratadie() "Rata Die number" from it. - @ref wxdatetimejdn() "wxDateTime(double jdn)" - - @ref setjdn() "Set(double jdn)" - - GetJulianDayNumber() - - GetJDN() - - GetModifiedJulianDayNumber() - - GetMJD() - - GetRataDie() - */ - - - /** - The functions in this section perform the basic calendar calculations, mostly - related to the week days. They allow to find the given week day in the - week with given number (either in the month or in the year) and so on. - All (non-const) functions in this section don't modify the time part of the - wxDateTime -- they only work with the date part of it. - SetToWeekDayInSameWeek() - - GetWeekDayInSameWeek() - - SetToNextWeekDay() - - GetNextWeekDay() - - SetToPrevWeekDay() - - GetPrevWeekDay() - - SetToWeekDay() - - @ref wxDateTime::getweekday2 GetWeekDay - - SetToLastWeekDay() - - GetLastWeekDay() - - SetToWeekOfYear() - - SetToLastMonthDay() - - GetLastMonthDay() - - SetToYearDay() - - GetYearDay() - */ - - - /** - Constructors and various @c 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. - @ref wxdatetimedef() wxDateTime - - @ref wxdatetimetimet() wxDateTime(time_t) - - @ref wxdatetimetm() "wxDateTime(struct tm)" - - @ref wxdatetimejdn() "wxDateTime(double jdn)" - - @ref wxdatetimetime() "wxDateTime(h, m, s, ms)" - - @ref wxdatetimedate() "wxDateTime(day, mon, year, h, m, s, ms)" - - SetToCurrent() - - @ref settimet() Set(time_t) - - @ref settm() "Set(struct tm)" - - @ref setjdn() "Set(double jdn)" - - @ref settime() "Set(h, m, s, ms)" - - @ref setdate() "Set(day, mon, year, h, m, s, ms)" - - @ref setfromdos() "SetFromDOS(unsigned long ddt)" - - ResetTime() - - SetYear() - - SetMonth() - - @ref setdate() SetDay - - SetHour() - - SetMinute() - - SetSecond() - - SetMillisecond() - - @ref operatoreqtimet() operator=(time_t) - - @ref operatoreqtm() "operator=(struct tm)" - */ - - - /** - 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. - This function should be used like this: + Sets the date from the so-called Julian Day Number. + + By definition, the Julian Day Number, usually abbreviated as JDN, of a + 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 */ - static int ConvertYearToBC(int year); + 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); /** - These functions carry out arithmetics on the wxDateTime - objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be - added to wxDateTime, hence all functions are overloaded to accept both - arguments. - Also, both @c Add() and @c Subtract() have both const and non-const - version. The first one returns a new object which represents the - sum/difference of the original one with the argument while the second form - modifies the object to which it is applied. The operators -= and += are - defined to be equivalent to the second forms of these functions. - @ref addts() Add(wxTimeSpan) - - @ref addds() Add(wxDateSpan) - - @ref subtractts() Subtract(wxTimeSpan) - - @ref subtractds() Subtract(wxDateSpan) - - @ref subtractdt() Subtract(wxDateTime) - - @ref addts() oparator+=(wxTimeSpan) - - @ref addds() oparator+=(wxDateSpan) - - @ref subtractts() oparator-=(wxTimeSpan) - - @ref subtractds() oparator-=(wxDateSpan) - */ - - - /** - There are several function to allow date comparison. To supplement them, a few - global operators , etc taking wxDateTime are defined. - IsEqualTo() - - IsEarlierThan() - - IsLaterThan() - - IsStrictlyBetween() - - IsBetween() - - IsSameDate() - - IsSameTime() - - IsEqualUpTo() - */ - - - /** - 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. - 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 and the - format specification @c %l can be used to get the number of milliseconds. - - @see ParseFormat() + Sets the date and time from the parameters. */ - wxString Format(const wxChar* format = wxDefaultDateTimeFormat, - const TimeZone& tz = Local) const; + wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month, + int year = Inv_Year, wxDateTime_t hour = 0, + wxDateTime_t minute = 0, wxDateTime_t second = 0, + wxDateTime_t millisec = 0); /** - Identical to calling Format() with @c "%x" - argument (which means 'preferred date representation for the current locale'). + Sets the day without changing other date components. */ - wxString FormatDate() const; + wxDateTime& SetDay(short unsigned int); /** - Returns the combined date-time representation in the ISO 8601 format - (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 date-time - representation is needed. - - @see FormatISODate(), FormatISOTime(), - ParseISOCombined() + Sets the date from the date and time in DOS format. */ - wxString FormatISOCombined(char sep = 'T') const; + wxDateTime& SetFromDOS(unsigned long ddt); /** - This function returns the date representation in the ISO 8601 format - (YYYY-MM-DD). + Sets the hour without changing other date components. */ - wxString FormatISODate() const; + wxDateTime& SetHour(short unsigned int); /** - This function returns the time representation in the ISO 8601 format - (HH:MM:SS). + Sets the millisecond without changing other date components. */ - wxString FormatISOTime() const; + wxDateTime& SetMillisecond(short unsigned int); /** - Identical to calling Format() with @c "%X" - argument (which means 'preferred time representation for the current locale'). + Sets the minute without changing other date components. */ - wxString FormatTime() const; + wxDateTime& SetMinute(short unsigned int); /** - Transform the date from the given time zone to the local one. If @a noDST is - @true, no DST adjustments will be made. - Returns the date in the local time zone. + Sets the month without changing other date components. */ - wxDateTime FromTimezone(const TimeZone& tz, - bool noDST = false) const; + wxDateTime& SetMonth(Month month); /** - Returns the translations of the strings @c AM and @c PM used for time - formatting for the current locale. Either of the pointers may be @NULL if - the corresponding value is not needed. + Sets the second without changing other date components. */ - static void GetAmPmStrings(wxString* am, wxString* pm); + wxDateTime& SetSecond(short unsigned int); /** - Returns the date and time in - DOS - format. + Sets the date and time of to the current values. Same as assigning the + result of Now() to this object. */ - unsigned long GetAsDOS() const; + wxDateTime& SetToCurrent(); /** - Get the beginning of DST for the given country in the given year (current one - by default). This function suffers from limitations described in - @ref overview_tdatedst "DST overview". - - @see GetEndDST() + Sets the year without changing other date components. */ - static wxDateTime GetBeginDST(int year = Inv_Year, - Country country = Country_Default); + wxDateTime& SetYear(int year); /** - Returns the century of this date. + Same as Set(). */ - int GetCentury(const TimeZone& tz = Local) const; + wxDateTime& operator=(time_t timet); + /** + Same as Set(). + */ + wxDateTime& operator=(const struct tm& tm); + + //@} + + /** - Returns the current default country. The default country is used for DST - calculations, for example. - - @see SetCountry() + @name Accessors + + Here are the trivial accessors. Other functions, which might have to + perform some more complicated calculations to find the answer are under + the "Date Arithmetics" section. */ - static Country GetCountry(); + //@{ /** - Get the current month in given calendar (only Gregorian is currently supported). + Returns the date and time in DOS format. */ - static Month GetCurrentMonth(Calendar cal = Gregorian); + long unsigned int GetAsDOS() const; /** - Get the current year in given calendar (only Gregorian is currently supported). + Returns the century of this date. */ - static int GetCurrentYear(Calendar cal = Gregorian); + int GetCentury(const TimeZone& tz = Local) const; /** - Returns the object having the same date component as this one but time of - 00:00:00. - This function is new since wxWidgets version 2.8.2 - + Returns the object having the same date component as this one but time + of 00:00:00. + + @since 2.8.2 + @see ResetTime() */ wxDateTime GetDateOnly() const; @@ -370,796 +428,1056 @@ public: /** Returns the day in the given timezone (local one by default). */ - wxDateTime_t GetDay(const TimeZone& tz = Local) const; + short unsigned int GetDay(const TimeZone& tz = Local) const; /** - Returns the day of the year (in 1...366 range) in the given timezone + Returns the day of the year (in 1-366 range) in the given timezone (local one by default). */ - wxDateTime_t GetDayOfYear(const TimeZone& tz = Local) const; + short unsigned int GetDayOfYear(const TimeZone& tz = Local) const; /** - Returns the end of DST for the given country in the given year (current one by - default). - - @see GetBeginDST() + Returns the hour in the given timezone (local one by default). */ - static wxDateTime GetEndDST(int year = Inv_Year, - Country country = Country_Default); + short unsigned int GetHour(const TimeZone& tz = Local) const; /** - Returns the hour in the given timezone (local one by default). + Returns the milliseconds in the given timezone (local one by default). */ - wxDateTime_t GetHour(const TimeZone& tz = Local) const; + short unsigned int GetMillisecond(const TimeZone& tz = Local) const; /** - Synonym for GetJulianDayNumber(). + Returns the minute in the given timezone (local one by default). */ - double GetJDN() const; + short unsigned int GetMinute(const TimeZone& tz = Local) const; /** - Returns the @ref setjdn() JDN corresponding to this date. Beware - of rounding errors! - - @see GetModifiedJulianDayNumber() + Returns the month in the given timezone (local one by default). */ - double GetJulianDayNumber() const; + Month GetMonth(const TimeZone& tz = Local) const; /** - Returns the copy of this object to which - SetToLastMonthDay() was applied. + Returns the seconds in the given timezone (local one by default). */ - wxDateTime GetLastMonthDay(Month month = Inv_Month, - int year = Inv_Year) const; + short unsigned int GetSecond(const TimeZone& tz = Local) const; /** - Returns the copy of this object to which - SetToLastWeekDay() was applied. + 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. */ - wxDateTime GetLastWeekDay(WeekDay weekday, - Month month = Inv_Month, - int year = Inv_Year); + time_t GetTicks() const; /** - Synonym for GetModifiedJulianDayNumber(). + Returns broken down representation of the date and time. */ - double GetMJD() const; + Tm GetTm(const TimeZone& tz = Local) const; /** - Returns the milliseconds in the given timezone (local one by default). + Returns the week day in the given timezone (local one by default). */ - wxDateTime_t GetMillisecond(const TimeZone& tz = Local) const; + WeekDay GetWeekDay(const TimeZone& tz = Local) const; /** - Returns the minute in the given timezone (local one by default). + 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. */ - wxDateTime_t GetMinute(const TimeZone& tz = Local) const; + wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, + const TimeZone& tz = Local) const; /** - Returns the @e Modified Julian Day Number (MJD) which is, by definition, - equal to JDN - 2400000.5. The MJDs are simpler to work with as the integral - MJDs correspond to midnights of the dates in the Gregorian calendar and not th - noons like JDN. The MJD 0 is Nov 17, 1858. + Returns the number of the week of the year this date is in. The first + week of the year is, according to international standards, the one + containing Jan 4 or, equivalently, the first week which has Thursday in + this year. Both of these definitions are the same as saying that the + first week of the year must contain more than half of its days in this + 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. */ - double GetModifiedJulianDayNumber() const; + wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, + const TimeZone& tz = Local) const; /** - Returns the month in the given timezone (local one by default). + Returns the year in the given timezone (local one by default). */ - Month GetMonth(const TimeZone& tz = Local) const; + int GetYear(const TimeZone& tz = Local) const; /** - Gets the full (default) or abbreviated (specify @c Name_Abbr name of the - given month. - - @see GetWeekDayName() + 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). */ - static wxString GetMonthName(Month month, - NameFlags flags = Name_Full); + bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const; /** - Returns the copy of this object to which - SetToNextWeekDay() was applied. + Returns @true if the object represents a valid time moment. */ - wxDateTime GetNextWeekDay(WeekDay weekday) const; + bool IsValid() const; - //@{ /** - Returns the number of days in the given year or in the given month of the - year. - The only supported value for @a cal parameter is currently @c Gregorian. + Returns @true is this day is not a holiday in the given country. */ - static wxDateTime_t GetNumberOfDays(int year, - Calendar cal = Gregorian); - static wxDateTime_t GetNumberOfDays(Month month, - int year = Inv_Year, - Calendar cal = Gregorian); + bool IsWorkDay(Country country = Country_Default) const; + //@} + + /** - Returns the copy of this object to which - SetToPrevWeekDay() was applied. + @name Date Comparison + + There are several functions to allow date comparison. To supplement + them, a few global operators, etc taking wxDateTime are defined. */ - wxDateTime GetPrevWeekDay(WeekDay weekday) const; + //@{ /** - Return the @e Rata Die number of this date. - By definition, the Rata Die number is a date specified as the number of days - relative to a base date of December 31 of the year 0. Thus January 1 of the - year 1 is Rata Die day 1. + Returns @true if this date precedes the given one. */ - double GetRataDie() const; + bool IsEarlierThan(const wxDateTime& datetime) const; /** - Returns the seconds in the given timezone (local one by default). + Returns @true if the two dates are strictly identical. */ - wxDateTime_t GetSecond(const TimeZone& tz = Local) const; + bool IsEqualTo(const wxDateTime& datetime) 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 @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 + than this interval. */ - time_t GetTicks() const; + bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const; /** - Returns the current time. + Returns @true if this date is later than the given one. */ - static time_t GetTimeNow(); + bool IsLaterThan(const wxDateTime& datetime) const; /** - Returns broken down representation of the date and time. + Returns @true if the date is the same without comparing the time parts. */ - Tm GetTm(const TimeZone& tz = Local) const; + bool IsSameDate(const wxDateTime& dt) const; /** - Returns the current time broken down. Note that this function returns a - pointer to a static buffer that's reused by calls to this function and - certain C library functions (e.g. localtime). If there is any chance your - code might be used in a multi-threaded application, you really should use - the flavour of function GetTmNow() - taking a parameter. + Returns @true if the time is the same (although dates may differ). */ - static struct tm* GetTmNow(); + bool IsSameTime(const wxDateTime& dt) const; /** - Returns the copy of this object to which - SetToWeekDay() was applied. + Returns @true if this date lies strictly between the two given dates. + + @see IsBetween() */ - wxDateTime GetWeekDay(WeekDay weekday, int n = 1, - Month month = Inv_Month, - int year = Inv_Year) const; + bool IsStrictlyBetween(const wxDateTime& t1, + const wxDateTime& t2) const; /** - Returns the copy of this object to which - SetToWeekDayInSameWeek() was - applied. + Returns @true if IsStrictlyBetween() is @true or if the date is equal + to one of the limit values. + + @see IsStrictlyBetween() */ - wxDateTime GetWeekDayInSameWeek(WeekDay weekday, - WeekFlags flags = Monday_First) const; + bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const; + + //@} + + /** - Gets the full (default) or abbreviated (specify @c Name_Abbr name of the - given week day. - - @see GetMonthName() + @name Date Arithmetics + + These functions carry out + @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime + objects. As explained in the overview, either wxTimeSpan or wxDateSpan + may be added to wxDateTime, hence all functions are overloaded to + accept both arguments. + + Also, both Add() and Subtract() have both const and non-const version. + The first one returns a new object which represents the sum/difference + of the original one with the argument while the second form modifies + the object to which it is applied. The operators "-=" and "+=" are + defined to be equivalent to the second forms of these functions. */ - static wxString GetWeekDayName(WeekDay weekday, - NameFlags flags = Name_Full); + //@{ /** - 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 - @ref overview_wxdatetime "week start" conventions. + Adds the given date span to this object. + + @beginWxPythonOnly + This method is named "AddDS" in wxPython. + @endWxPythonOnly */ - wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, - const TimeZone& tz = Local) const; + 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); /** - Returns the number of the week of the year this date is in. The first week of - the year is, according to international standards, the one containing Jan 4 or, - equivalently, the first week which has Thursday in this year. Both of these - definitions are the same as saying that the first week of the year must contain - more than half of its days in this year. Accordingly, the week number will - always be in 1...53 range (52 for non-leap years). - The function depends on the @ref overview_wxdatetime "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. + Adds the given time span to this object. + + @beginWxPythonOnly + This method is named "AddTS" in wxPython. + @endWxPythonOnly */ - wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, - const TimeZone& tz = Local) const; + 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); /** - Returns the year in the given timezone (local one by default). + Subtracts the given time span from this object. + + @beginWxPythonOnly + This method is named "SubtractTS" in wxPython. + @endWxPythonOnly */ - int GetYear(const TimeZone& tz = Local) const; + 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); /** - Returns the copy of this object to which - SetToYearDay() was applied. + Subtracts the given date span from this object. + + @beginWxPythonOnly + This method is named "SubtractDS" in wxPython. + @endWxPythonOnly */ - wxDateTime GetYearDay(wxDateTime_t yday) const; + 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); /** - Returns @true if IsStrictlyBetween() - is @true or if the date is equal to one of the limit values. - - @see IsStrictlyBetween() + Subtracts another date from this one and returns the difference between + them as a wxTimeSpan. */ - bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const; + wxTimeSpan Subtract(const wxDateTime& dt) const; /** - Returns @true if the DST is applied for this date in the given country. + Adds the given date span to this object. */ - int IsDST(Country country = Country_Default) const; + wxDateTime operator+=(const wxDateSpan& diff); + /** + Subtracts the given date span from this object. + */ + wxDateTime& operator-=(const wxDateSpan& diff); + /** + Adds the given time span to this object. + */ + wxDateTime& operator+=(const wxTimeSpan& diff); + /** + Subtracts the given time span from this object. + */ + wxDateTime& operator-=(const wxTimeSpan& diff); + + //@} + + /** - Returns @true if DST was used n the given year (the current one by - default) in the given country. + @name Date Formatting and Parsing + + See @ref datetime_formatting */ - static bool IsDSTApplicable(int year = Inv_Year, - Country country = Country_Default); + //@{ /** - Returns @true if this date precedes the given one. + 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. + + 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 + and the format specification @c "%l" can be used to get the number of + milliseconds. + + @see ParseFormat() */ - bool IsEarlierThan(const wxDateTime& datetime) const; + wxString Format(const wxChar* format = wxDefaultDateTimeFormat, + const TimeZone& tz = Local) const; /** - Returns @true if the two dates are strictly identical. + Identical to calling Format() with @c "%x" argument (which means + "preferred date representation for the current locale"). */ - bool IsEqualTo(const wxDateTime& datetime) const; + wxString FormatDate() const; /** - 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 than - this interval. + 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 + date-time representation is needed. + + @see FormatISODate(), FormatISOTime(), ParseISOCombined() */ - bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const; + wxString FormatISOCombined(char sep = 'T') 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). + This function returns the date representation in the ISO 8601 format + @c "YYYY-MM-DD". */ - bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const; + wxString FormatISODate() const; /** - Returns @true if this date is later than the given one. + This function returns the time representation in the ISO 8601 format + @c "HH:MM:SS". */ - bool IsLaterThan(const wxDateTime& datetime) const; + wxString FormatISOTime() const; /** - Returns @true if the @a year is a leap one in the specified calendar. - This functions supports Gregorian and Julian calendars. + Identical to calling Format() with @c "%X" argument (which means + "preferred time representation for the current locale"). */ - static bool IsLeapYear(int year = Inv_Year, - Calendar cal = Gregorian); + wxString FormatTime() const; /** - Returns @true if the date is the same without comparing the time parts. + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - bool IsSameDate(const wxDateTime& dt) const; + 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. + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDate(const char* date); /** - Returns @true if the time is the same (although dates may differ). + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - bool IsSameTime(const wxDateTime& dt) const; + const wchar_t* ParseDate(const wchar_t* date); /** - Returns @true if this date lies strictly between the two others, - - @see IsBetween() + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - bool IsStrictlyBetween(const wxDateTime& t1, - const wxDateTime& t2) const; + 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. + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDateTime(const char* datetime); /** - Returns @true if the object represents a valid time moment. + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - bool IsValid() const; + const wchar_t* ParseDateTime(const wchar_t* datetime); /** - This function returns @true if the specified (or default) country is one - of Western European ones. It is used internally by wxDateTime to determine the - DST convention and date and time formatting rules. + 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. + + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - static bool IsWestEuropeanCountry(Country country = Country_Default); + 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. + + 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. + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseFormat(const char* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); /** - Returns @true is this day is not a holiday in the given country. + 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. + + 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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. */ - bool IsWorkDay(Country country = Country_Default) const; + const wchar_t* ParseFormat(const wchar_t* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); /** - Same as FromTimezone() but modifies the object - in place. + This function parses the string containing the date and time in ISO + 8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between + the date and time parts must be equal to @a sep for the function to + succeed. + + @returns @true if the entire string was parsed successfully, @false + otherwise. */ - wxDateTime MakeFromTimezone(const TimeZone& tz, - bool noDST = false); + bool ParseISOCombined(const wxString& date, char sep = 'T'); /** - Modifies the object in place to represent the date in another time zone. If - @a noDST is @true, no DST adjustments will be made. + This function parses the date in ISO 8601 format @c "YYYY-MM-DD". + + @returns @true if the entire string was parsed successfully, @false + otherwise. */ - wxDateTime MakeTimezone(const TimeZone& tz, - bool noDST = false); + bool ParseISODate(const wxString& date); /** - This is the same as calling MakeTimezone() with - the argument @c GMT0. + This function parses the time in ISO 8601 format @c "HH:MM:SS". + + @returns @true if the entire string was parsed successfully, @false + otherwise. */ - wxDateTime MakeUTC(bool noDST = false); + bool ParseISOTime(const wxString& date); /** - Returns the object corresponding to the current time. - Example: - - Note that this function is accurate up to second: - UNow() should be used for better precision - (but it is less efficient and might not be available on all platforms). - - @see Today() + 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. */ - static wxDateTime Now(); + 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); /** - 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. + 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 which stopped the scan. + 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* ParseDate(const wxString& date, - wxString::const_iterator* end = NULL); - const char* ParseDate(const char* date); - const wchar_t* ParseDate(const wchar_t* date); + const wchar_t* ParseRfc822Date(const wchar_t* date); + + /** + This functions is like ParseDateTime(), but only allows the time to be + specified in the input string. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + 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. + + @returns @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. + + @returns @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const wchar_t* ParseTime(const wchar_t* time); + //@} + + + /** + @name Calendar Calculations + + The functions in this section perform the basic calendar calculations, + mostly related to the week days. They allow to find the given week day + in the week with given number (either in the month or in the year) and + so on. + + None of the functions in this section modify the time part of the + wxDateTime, they only work with the date part of it. + */ //@{ + /** - 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 wxDateTime::ParseRfc822Date, it - will accept anything that may be accepted and will only reject strings which - can not be parsed in any way at all. - Returns @NULL if the conversion failed, otherwise return the pointer to - the character which stopped the scan. + Returns the copy of this object to which SetToLastMonthDay() was + applied. */ - const char* ParseDateTime(const wxString& datetime, - wxString::const_iterator* end = NULL); - const char* ParseDateTime(const char* datetime); - const wchar_t* ParseDateTime(const wchar_t* datetime); + wxDateTime GetLastMonthDay(Month month = Inv_Month, + int year = Inv_Year) const; + + /** + Returns the copy of this object to which SetToLastWeekDay() was + applied. + */ + wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month, + int year = Inv_Year); + + /** + Returns the copy of this object to which SetToNextWeekDay() was + applied. + */ + wxDateTime GetNextWeekDay(WeekDay weekday) const; + + /** + Returns the copy of this object to which SetToPrevWeekDay() was + applied. + */ + wxDateTime GetPrevWeekDay(WeekDay weekday) const; + + /** + Returns the copy of this object to which SetToWeekDay() was applied. + */ + wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month, + int year = Inv_Year) const; + + /** + Returns the copy of this object to which SetToWeekDayInSameWeek() was + applied. + */ + wxDateTime GetWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First) const; + + /** + Returns the copy of this object to which SetToYearDay() was applied. + */ + wxDateTime GetYearDay(wxDateTime_t yday) const; + + /** + Sets the date to the last day in the specified month (the current one + by default). + + @returns The reference to the modified object itself. + */ + wxDateTime SetToLastMonthDay(Month month = Inv_Month, + int year = Inv_Year); + + /** + The effect of calling this function is the same as of calling + @c SetToWeekDay(-1, weekday, month, year). The date will be set to the + last @a weekday in the given month and year (the current ones by + default). Always returns @true. + */ + bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, + int year = Inv_Year); + + /** + Sets the date so that it will be the first @a weekday following the + current date. + + @returns The reference to the modified object itself. + */ + wxDateTime& SetToNextWeekDay(WeekDay weekday); + + /** + Sets the date so that it will be the last @a weekday before the current + date. + + @returns The reference to the modified object itself. + */ + wxDateTime& SetToPrevWeekDay(WeekDay weekday); + + /** + Sets the date to the @e n-th @a weekday in the given month of the given + year (the current month and year are used by default). The parameter + @a n may be either positive (counting from the beginning of the month) + or negative (counting from the end of it). + + For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the + second Wednesday in the current month and + SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday + in the current month. + + @returns @true if the date was modified successfully, @false otherwise + meaning that the specified date doesn't exist. + */ + bool SetToWeekDay(WeekDay weekday, int n = 1, + Month month = Inv_Month, int year = Inv_Year); + + /** + Adjusts the date so that it will still lie in the same week as before, + but its week day will be the given one. + + @returns The reference to the modified object itself. + */ + wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First); + + /** + 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. + + @returns The reference to the modified object itself. + */ + wxDateTime& SetToYearDay(wxDateTime_t yday); + //@} - //@{ + + + /** + @name Astronomical/Historical Functions + + Some degree of support for the date units used in astronomy and/or + history is provided. You can construct a wxDateTime object from a + JDN and you may also get its JDN, MJD or Rata Die number from it. + + Related functions in other groups: wxDateTime(double), Set(double) + */ + //@{ + + /** + Synonym for GetJulianDayNumber(). + */ + double GetJDN() const; + + /** + Returns the JDN corresponding to this date. Beware of rounding errors! + + @see GetModifiedJulianDayNumber() + */ + double GetJulianDayNumber() const; + + /** + Synonym for GetModifiedJulianDayNumber(). + */ + double GetMJD() const; + + /** + Returns the @e "Modified Julian Day Number" (MJD) which is, by + definition, is equal to JDN - 2400000.5. The MJDs are simpler to work + with as the integral MJDs correspond to midnights of the dates in the + Gregorian calendar and not the noons like JDN. The MJD 0 represents + Nov 17, 1858. + */ + double GetModifiedJulianDayNumber() const; + /** - 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. - 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 - ay of the month), the month and the year are taken from @e dateDef. If - it is not specified, Today() is used as the - default date. - Returns @NULL if the conversion failed, otherwise return the pointer to - the character which stopped the scan. + Return the @e Rata Die number of this date. + + By definition, the Rata Die number is a date specified as the number of + days relative to a base date of December 31 of the year 0. Thus January + 1 of the year 1 is Rata Die day 1. */ - const char* ParseFormat(const wxString& date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime, - wxString::const_iterator* end = NULL); - const char* ParseFormat(const char* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - const wchar_t* ParseFormat(const wchar_t* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); + double GetRataDie() const; + //@} + + /** - This function parses the string containing the date and time in ISO 8601 - combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time - parts must be equal to @a sep for the function to succeed. - Returns @true if the entire string was parsed successfully, @false - otherwise. + @name Time Zone and DST Support + + Please see the @ref overview_datetime_timezones "time zone overview" + for more information about time zones. Normally, these functions should + be rarely used. + + Related functions in other groups: GetBeginDST(), GetEndDST() */ - bool ParseISOCombined(const wxString& date, char sep = 'T'); + //@{ /** - This function parses the date in ISO 8601 format (YYYY-MM-DD). - Returns @true if the entire string was parsed successfully, @false - otherwise. + Transform the date from the given time zone to the local one. If + @a noDST is @true, no DST adjustments will be made. + + @returns The date in the local time zone. */ - bool ParseISODate(const wxString& date); + wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const; /** - This function parses the time in ISO 8601 format (HH:MM:SS). - Returns @true if the entire string was parsed successfully, @false - otherwise. + Returns @true if the DST is applied for this date in the given country. + + @see GetBeginDST(), GetEndDST() */ - bool ParseISOTime(const wxString& date); + int IsDST(Country country = Country_Default) const; - //@{ /** - 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. + Same as FromTimezone() but modifies the object in place. */ - const char* ParseRfc822Date(const wxString& date, - wxString::const_iterator* end = NULL); - const char* ParseRfc822Date(const char* date); - const wchar_t* ParseRfc822Date(const wchar_t* date); - //@} + wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false); - //@{ /** - This functions is like ParseDateTime(), but - only allows the time to be specified in the input string. - Returns @NULL if the conversion failed, otherwise return the pointer to - the character which stopped the scan. + Modifies the object in place to represent the date in another time + zone. If @a noDST is @true, no DST adjustments will be made. */ - const char* ParseTime(const wxString& time, - wxString::const_iterator* end = NULL); - const char* ParseTime(const char* time); - const wchar_t* ParseTime(const wchar_t* time); - //@} + wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false); /** - These 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 - wxDateTime::FormatTime), using the international standard - representation defined by ISO 8601 ( - FormatISODate(), - FormatISOTime() and - wxDateTime::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. wxDateTime::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. - But the most interesting functions are - ParseTime(), - ParseDate() and - ParseDateTime(). They try to parse the date - ans 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 @c "tomorrow", @c "March first" and even - @c "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. - ParseFormat() - - ParseDateTime() - - ParseDate() - - ParseTime() - - ParseISODate() - - ParseISOTime() - - ParseISOCombined() - - wxDateTime::ParseRfc822Date - - Format() - - FormatDate() - - FormatTime() - - FormatISOCombined() - - FormatISODate() - - FormatISOTime() + This is the same as calling MakeTimezone() with the argument @c GMT0. */ - + wxDateTime& MakeUTC(bool noDST = false); /** - Reset time to midnight (00:00:00) without changing the date. + Transform the date to the given time zone. If @a noDST is @true, no DST + adjustments will be made. + + @returns The date in the new time zone. */ - wxDateTime ResetTime(); + wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const; /** - Sets the date and time from the parameters. + This is the same as calling ToTimezone() with the argument @c GMT0. */ - wxDateTime Set(wxDateTime_t day, Month month = Inv_Month, - int year = Inv_Year, - wxDateTime_t hour = 0, - wxDateTime_t minute = 0, - wxDateTime_t second = 0, - wxDateTime_t millisec = 0); + wxDateTime ToUTC(bool noDST = false) const; + + //@} + + + + /** - 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 - @ref overview_wxdatetime "wxDateTime constants section". - - @see GetCountry() + 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. + + This function should be used like this: + + @code + wxDateTime dt(...); + int y = dt.GetYear(); + printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC"); + @endcode */ - static void SetCountry(Country country); + static int ConvertYearToBC(int year); /** - Sets the day without changing other date components. + Returns the translations of the strings @c AM and @c PM used for time + formatting for the current locale. Either of the pointers may be @NULL + if the corresponding value is not needed. */ - wxDateTime SetDay(wxDateTime_t day); + static void GetAmPmStrings(wxString* am, wxString* pm); /** - Sets the date from the date and time in - DOS - format. + Get the beginning of DST for the given country in the given year + (current one by default). This function suffers from limitations + described in the @ref overview_datetime_dst "DST overview". + + @see GetEndDST() */ - wxDateTime Set(unsigned long ddt); + static wxDateTime GetBeginDST(int year = Inv_Year, + Country country = Country_Default); /** - Sets the hour without changing other date components. + Returns the end of DST for the given country in the given year (current + one by default). + + @see GetBeginDST() */ - wxDateTime SetHour(wxDateTime_t hour); + static wxDateTime GetEndDST(int year = Inv_Year, + Country country = Country_Default); /** - Sets the millisecond without changing other date components. + Get the current century, i.e. first two digits of the year, in given + calendar (only Gregorian is currently supported). */ - wxDateTime SetMillisecond(wxDateTime_t millisecond); + static int GetCentury(int year); /** - Sets the minute without changing other date components. + Returns the current default country. The default country is used for + DST calculations, for example. + + @see SetCountry() */ - wxDateTime SetMinute(wxDateTime_t minute); + static Country GetCountry(); /** - Sets the month without changing other date components. + Get the current month in given calendar (only Gregorian is currently + supported). */ - wxDateTime SetMonth(Month month); + static Month GetCurrentMonth(Calendar cal = Gregorian); /** - Sets the second without changing other date components. + Get the current year in given calendar (only Gregorian is currently + supported). */ - wxDateTime SetSecond(wxDateTime_t second); + static int GetCurrentYear(Calendar cal = Gregorian); /** - Sets the date and time of to the current values. Same as assigning the result - of Now() to this object. + Gets the full (default) or abbreviated (specify @c Name_Abbr name of + the given month. + + @see GetWeekDayName() */ - wxDateTime SetToCurrent(); + static wxString GetMonthName(Month month, NameFlags flags = Name_Full); /** - Sets the date to the last day in the specified month (the current one by - default). - Returns the reference to the modified object itself. + 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 */ - wxDateTime SetToLastMonthDay(Month month = Inv_Month, - int year = Inv_Year); + static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian); /** - The effect of calling this function is the same as of calling - @c SetToWeekDay(-1, weekday, month, year). The date will be set to the last - @a weekday in the given month and year (the current ones by default). - Always returns @true. + 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 */ - bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, - int year = Inv_Year); + static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year, + Calendar cal = Gregorian); /** - Sets the date so that it will be the first @a weekday following the current - date. - Returns the reference to the modified object itself. + Returns the current time. */ - wxDateTime SetToNextWeekDay(WeekDay weekday); + static time_t GetTimeNow(); /** - Sets the date so that it will be the last @a weekday before the current - date. - Returns the reference to the modified object itself. + Returns the current time broken down using the buffer whose adress is + passed to the function with @a tm to store the result. */ - wxDateTime SetToPrevWeekDay(WeekDay weekday); + static struct tm* GetTmNow(struct tm *tm); /** - Sets the date to the @e n-th @a weekday in the given month of the given - year (the current month and year are used by default). The parameter @e n - may be either positive (counting from the beginning of the month) or negative - (counting from the end of it). - For example, @c SetToWeekDay(2, wxDateTime::Wed) will set the date to the - second Wednesday in the current month and - @c SetToWeekDay(-1, wxDateTime::Sun) -- to the last Sunday in it. - Returns @true if the date was modified successfully, @false - otherwise meaning that the specified date doesn't exist. + Returns the current time broken down. Note that this function returns a + pointer to a static buffer that's reused by calls to this function and + certain C library functions (e.g. localtime). If there is any chance + your code might be used in a multi-threaded application, you really + should use GetTmNow(struct tm *) instead. */ - bool SetToWeekDay(WeekDay weekday, int n = 1, - Month month = Inv_Month, - int year = Inv_Year); + static struct tm* GetTmNow(); /** - Adjusts the date so that it will still lie in the same week as before, but its - week day will be the given one. - Returns the reference to the modified object itself. + Gets the full (default) or abbreviated (specify @c Name_Abbr) name of + the given week day. + + @see GetMonthName() */ - wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, - WeekFlags flags = Monday_First); + static wxString GetWeekDayName(WeekDay weekday, + NameFlags flags = Name_Full); /** - Set the date to the given @a weekday in the week number @a numWeek of the - given @a year . The number should be in range 1...53. - Note that the returned date may be in a different year than the one passed to - this function because both the week 1 and week 52 or 53 (for leap years) - contain days from different years. See - GetWeekOfYear() for the explanation of how the - year weeks are counted. + Returns @true if DST was used n the given year (the current one by + default) in the given country. */ - static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek, - WeekDay weekday = Mon); + static bool IsDSTApplicable(int year = Inv_Year, + Country country = Country_Default); /** - 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. - Returns the reference to the modified object itself. + Returns @true if the @a year is a leap one in the specified calendar. + This functions supports Gregorian and Julian calendars. */ - wxDateTime SetToYearDay(wxDateTime_t yday); + static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian); /** - Sets the year without changing other date components. - */ - wxDateTime SetYear(int year); - - /** - For convenience, all static functions are collected here. These 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 @e Calendar - parameter, it is currently ignored as only the Gregorian calendar is - supported. Future versions will support other calendars. - - SetCountry() - - GetCountry() - - IsWestEuropeanCountry() - - GetCurrentYear() - - ConvertYearToBC() - - GetCurrentMonth() - - IsLeapYear() - - @ref getcenturystatic() GetCentury - - GetNumberOfDays() - - GetNumberOfDays() - - GetMonthName() - - GetWeekDayName() - - GetAmPmStrings() - - IsDSTApplicable() - - GetBeginDST() - - GetEndDST() - - Now() - - UNow() - - Today() - */ - - - /** - Subtracts another date from this one and returns the difference between them - as wxTimeSpan. + This function returns @true if the specified (or default) country is + one of Western European ones. It is used internally by wxDateTime to + determine the DST convention and date and time formatting rules. */ - wxTimeSpan Subtract(const wxDateTime& dt) const; + static bool IsWestEuropeanCountry(Country country = Country_Default); /** - Please see the @ref overview_tdatetimezones "time zone overview" for more - information about time zones. Normally, these functions should be rarely used. - FromTimezone() - - ToTimezone() - - MakeTimezone() - - MakeFromTimezone() - - ToUTC() - - MakeUTC() - - GetBeginDST() - - GetEndDST() - - IsDST() - */ + Returns the object corresponding to the current time. + + Example: + + @code + wxDateTime now = wxDateTime::Now(); + 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. + @see Today() + */ + static wxDateTime Now(); /** - Transform the date to the given time zone. If @a noDST is @true, no - DST adjustments will be made. - Returns the date in the new time zone. + 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() */ - wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const; + static void SetCountry(Country country); /** - This is the same as calling ToTimezone() with - the argument @c GMT0. + Set the date to the given @a weekday in the week number @a numWeek of + the given @a year . The number should be in range 1-53. + + Note that the returned date may be in a different year than the one + passed to this function because both the week 1 and week 52 or 53 (for + leap years) contain days from different years. See GetWeekOfYear() for + the explanation of how the year weeks are counted. */ - wxDateTime ToUTC(bool noDST = false) const; + static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek, + WeekDay weekday = Mon); /** - 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). - + 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). + @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). - + milliseconds if a function to get time with such precision is available + on the current platform (supported under most Unices and Win32). + @see Now() */ static wxDateTime UNow(); - - /** - Same as @ref settm() Set. - */ - wxDateTime operator(const struct tm& tm); }; +/** + Global instance of an empty wxDateTime object. + + @todo Would it be better to rename this wxNullDateTime so it's consistent + with the rest of the "empty/invalid/null" global objects? +*/ +const wxDateTime wxDefaultDateTime; + + /** @class wxDateTimeWorkDays @wxheader{datetime.h} + @todo Write wxDateTimeWorkDays documentation. @library{wxbase} - @category{FIXME} + @category{data} */ class wxDateTimeWorkDays { @@ -1168,6 +1486,7 @@ public: }; + /** @class wxDateSpan @wxheader{datetime.h} @@ -1183,94 +1502,94 @@ public: Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31. Because of this feature, adding and subtracting back again the same - wxDateSpan will @b not, in general give back the original date: Feb 28 - 1 + wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1 month will be Jan 28, not Jan 31! wxDateSpan objects can be either positive or negative. They may be multiplied by scalars which multiply all deltas by the scalar: i.e. - 2*(1 month and 1 day) is 2 months and 2 days. They can - be added together and with wxDateTime or - wxTimeSpan, but the type of result is different for each + 2*(1 month and 1 day) is 2 months and 2 days. They can be added together + with wxDateTime or wxTimeSpan, but the type of result is different for each case. - Beware about weeks: if you specify both weeks and days, the total number of - days added will be 7*weeks + days! See also GetTotalDays() - function. + @warning If you specify both weeks and days, the total number of days added + will be 7*weeks + days! See also GetTotalDays(). - Equality operators are defined for wxDateSpans. Two datespans are equal if - and only if they both give the same target date when added to @b every - source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30), - because they don't give the same date when added to 1 Feb. But - wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2) + Equality operators are defined for wxDateSpans. Two wxDateSpans are equal + if and only if they both give the same target date when added to @b every + source date. Thus wxDateSpan::Months(1) is not equal to + wxDateSpan::Days(30), because they don't give the same date when added to + Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2). - Finally, notice that for adding hours, minutes and so on you don't need this - class at all: wxTimeSpan will do the job because there - are no subtleties associated with those (we don't support leap seconds). + Finally, notice that for adding hours, minutes and so on you don't need + this class at all: wxTimeSpan will do the job because there are no + subtleties associated with those (we don't support leap seconds). @library{wxbase} @category{data} - @seealso - @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime + @see @ref overview_datetime, wxDateTime */ class wxDateSpan { public: /** - Constructs the date span object for the given number of years, months, weeks - and days. Note that the weeks and days add together if both are given. + Constructs the date span object for the given number of years, months, + weeks and days. Note that the weeks and days add together if both are + given. */ - wxDateSpan(int years = 0, int months = 0, int weeks = 0, - int days = 0); + wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0); - //@{ /** - Returns the sum of two date spans. The first version returns a new object, the - second and third ones modify this object in place. + Returns the sum of two date spans. + + @returns A new wxDateSpan object with the result. */ - wxDateSpan Add(const wxDateSpan& other); - const wxDateSpan& Add(const wxDateSpan& other); - wxDateSpan operator+=(const wxDateSpan& other); - //@} + wxDateSpan Add(const wxDateSpan& other) const; + /** + Adds the given wxDateSpan to this wxDateSpan and returns a reference + to itself. + */ + wxDateSpan& Add(const wxDateSpan& other); /** Returns a date span object corresponding to one day. - + @see Days() */ static wxDateSpan Day(); /** Returns a date span object corresponding to the given number of days. - + @see Day() */ static wxDateSpan Days(int days); /** - Returns the number of days (only, that it not counting the weeks component!) - in this date span. - + Returns the number of days (not counting the weeks component) in this + date span. + @see GetTotalDays() */ int GetDays() const; /** - Returns the number of the months (not counting the years) in this date span. + Returns the number of the months (not counting the years) in this date + span. */ int GetMonths() const; /** - Returns the combined number of days in this date span, counting both weeks and - days. It still doesn't take neither months nor years into the account. - + Returns the combined number of days in this date span, counting both + weeks and days. This doesn't take months or years into account. + @see GetWeeks(), GetDays() */ int GetTotalDays() const; /** Returns the number of weeks in this date span. - + @see GetTotalDays() */ int GetWeeks() const; @@ -1282,123 +1601,154 @@ public: /** Returns a date span object corresponding to one month. - + @see Months() */ static wxDateSpan Month(); /** Returns a date span object corresponding to the given number of months. - + @see Month() */ static wxDateSpan Months(int mon); - //@{ /** - Returns the product of the date span by the specified @e factor. The - product is computed by multiplying each of the components by the factor. - The first version returns a new object, the second and third ones modify this - object in place. + Returns the product of the date span by the specified @a factor. The + product is computed by multiplying each of the components by the + @a factor. + + @returns A new wxDateSpan object with the result. */ - wxDateSpan Multiply(int factor); - const wxDateSpan& Multiply(int factor); - wxDateSpan operator*=(int factor); - //@} + wxDateSpan Multiply(int factor) const; + /** + Multiplies this date span by the specified @a factor. The product is + computed by multiplying each of the components by the @a factor. + + @returns A reference to this wxDateSpan object modified in place. + */ + wxDateSpan& Multiply(int factor); - //@{ /** Changes the sign of this date span. - + @see Negate() */ - wxDateSpan Neg(); - wxDateSpan operator-(); - //@} + wxDateSpan& Neg(); /** - Returns the date span with the opposite sign. - + Returns a date span with the opposite sign. + @see Neg() */ wxDateSpan Negate() const; /** - Sets the number of days (without modifying any other components) in this date - span. + Sets the number of days (without modifying any other components) in + this date span. */ - wxDateSpan SetDays(int n); + wxDateSpan& SetDays(int n); /** - Sets the number of months (without modifying any other components) in this - date span. + Sets the number of months (without modifying any other components) in + this date span. */ - wxDateSpan SetMonths(int n); + wxDateSpan& SetMonths(int n); /** - Sets the number of weeks (without modifying any other components) in this date - span. + Sets the number of weeks (without modifying any other components) in + this date span. */ - wxDateSpan SetWeeks(int n); + wxDateSpan& SetWeeks(int n); /** - Sets the number of years (without modifying any other components) in this date - span. + Sets the number of years (without modifying any other components) in + this date span. */ - wxDateSpan SetYears(int n); + wxDateSpan& SetYears(int n); - //@{ /** - Returns the difference of two date spans. The first version returns a new - object, the second and third ones modify this object in place. + Returns the difference of two date spans. + + @returns A new wxDateSpan object with the result. */ - wxDateSpan Subtract(const wxDateSpan& other); - const wxDateSpan& Subtract(const wxDateSpan& other); - wxDateSpan operator+=(const wxDateSpan& other); - //@} + wxDateSpan Subtract(const wxDateSpan& other) const; + /** + Subtracts the given wxDateSpan to this wxDateSpan and returns a + reference to itself. + */ + wxDateSpan& Subtract(const wxDateSpan& other); /** Returns a date span object corresponding to one week. - + @see Weeks() */ static wxDateSpan Week(); /** Returns a date span object corresponding to the given number of weeks. - + @see Week() */ static wxDateSpan Weeks(int weeks); /** Returns a date span object corresponding to one year. - + @see Years() */ static wxDateSpan Year(); /** Returns a date span object corresponding to the given number of years. - + @see Year() */ static wxDateSpan Years(int years); + /** + Adds the given wxDateSpan to this wxDateSpan and returns the result. + */ + wxDateSpan& operator+=(const wxDateSpan& other); + + /** + Subtracts the given wxDateSpan to this wxDateSpan and returns the + result. + */ + wxDateSpan& operator-=(const wxDateSpan& other); + + /** + Changes the sign of this date span. + + @see Negate() + */ + wxDateSpan& operator-(); + + /** + Multiplies this date span by the specified @a factor. The product is + computed by multiplying each of the components by the @a factor. + + @returns A reference to this wxDateSpan object modified in place. + */ + wxDateSpan& operator*=(int factor); + /** Returns @true if this date span is different from the other one. */ - bool operator!=(wxDateSpan& other) const; + bool operator!=(const wxDateSpan&) const; /** - Returns @true if this date span is equal to the other one. Two date spans - are considered equal if and only if they have the same number of years and - months and the same total number of days (counting both days and weeks). + Returns @true if this date span is equal to the other one. Two date + spans are considered equal if and only if they have the same number of + years and months and the same total number of days (counting both days + and weeks). */ - bool operator==(wxDateSpan& other) const; + bool operator==(const wxDateSpan&) const; }; + /** @class wxTimeSpan @wxheader{datetime.h} @@ -1408,56 +1758,38 @@ public: @library{wxbase} @category{data} - @seealso - @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime + @see @ref overview_datetime, wxDateTime */ class wxTimeSpan { public: - //@{ /** - Constructs timespan from separate values for each component, with the date - set to 0. Hours are not restricted to 0..24 range, neither are - minutes, seconds or milliseconds. + Default constructor, constructs a zero timespan. */ wxTimeSpan(); + /** + Constructs timespan from separate values for each component, with the + date set to 0. Hours are not restricted to 0-24 range, neither are + minutes, seconds or milliseconds. + */ wxTimeSpan(long hours, long min, long sec, long msec); - //@} /** - Returns the absolute value of the timespan: does not modify the - object. + Returns the absolute value of the timespan: does not modify the object. */ wxTimeSpan Abs() const; /** - GetSeconds() - - GetMinutes() - - GetHours() - - GetDays() - - GetWeeks() - - GetValue() - */ + Returns the sum of two time spans. - - //@{ - /** - Returns the sum of two timespans. + @returns A new wxDateSpan object with the result. */ - wxTimeSpan Add(const wxTimeSpan& diff); - const wxTimeSpan& Add(const wxTimeSpan& diff); - wxTimeSpan operator+=(const wxTimeSpan& diff); - //@} - + wxTimeSpan Add(const wxTimeSpan& diff) const; /** - @ref ctor() wxTimeSpan + Adds the given wxTimeSpan to this wxTimeSpan and returns a reference + to itself. */ - + wxTimeSpan& Add(const wxTimeSpan& diff); /** Returns the timespan for one day. @@ -1470,54 +1802,32 @@ public: static wxTimespan Days(long days); /** - Returns the string containing the formatted representation of the time span. - The following format specifiers are allowed after %: - - H - - number of @b Hours - - M - - number of @b Minutes - - S - - number of @b Seconds - - l - - number of mi@b lliseconds - - D - - number of @b Days - - E - - number of w@b Eeks - - % - - the percent character - - Note that, for example, the number of hours in the description above is not - well defined: it can be either the total number of hours (for example, for a - time span of 50 hours this would be 50) or just the hour part of the time - span, which would be 2 in this case as 50 hours is equal to 2 days and - 2 hours. - wxTimeSpan resolves this ambiguity in the following way: if there had been, - indeed, the @c %D format specified preceding the @c %H, then it is - interpreted as 2. Otherwise, it is 50. - The same applies to all other format specifiers: if they follow a specifier of - larger unit, only the rest part is taken, otherwise the full value is used. - */ - wxString Format(const wxChar* format = wxDefaultTimeSpanFormat); - - /** - Format() - */ + Returns the string containing the formatted representation of the time + span. The following format specifiers are allowed after %: + + - @c H - Number of Hours + - @c M - Number of Minutes + - @c S - Number of Seconds + - @c l - Number of Milliseconds + - @c D - Number of Days + - @c E - Number of Weeks + - @c % - The percent character + + Note that, for example, the number of hours in the description above is + not well defined: it can be either the total number of hours (for + example, for a time span of 50 hours this would be 50) or just the hour + part of the time span, which would be 2 in this case as 50 hours is + equal to 2 days and 2 hours. + + wxTimeSpan resolves this ambiguity in the following way: if there had + been, indeed, the @c %D format specified preceding the @c %H, then it + is interpreted as 2. Otherwise, it is 50. + The same applies to all other format specifiers: if they follow a + specifier of larger unit, only the rest part is taken, otherwise the + full value is used. + */ + wxString Format(const wxString& = wxDefaultTimeSpanFormat) const; /** Returns the difference in number of days. @@ -1570,9 +1880,9 @@ public: bool IsEqualTo(const wxTimeSpan& ts) const; /** - 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. + 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. */ bool IsLongerThan(const wxTimeSpan& ts) const; @@ -1592,9 +1902,9 @@ public: bool IsPositive() const; /** - 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. + 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. */ bool IsShorterThan(const wxTimeSpan& ts) const; @@ -1618,42 +1928,32 @@ public: */ static wxTimespan Minutes(long min); - //@{ /** - Multiplies timespan by a scalar. + Returns the product of this time span by @a n. + + @returns A new wxTimeSpan object with the result. */ - wxTimeSpan Multiply(int n); - const wxTimeSpan& Multiply(int n); - wxTimeSpan operator*=(int n); - //@} + wxTimeSpan Multiply(int n) const; + /** + Multiplies this time span by @a n. + + @returns A reference to this wxTimeSpan object modified in place. + */ + wxTimeSpan& Multiply(int n); - //@{ /** Negate the value of the timespan. + + @see Negate() */ - wxTimeSpan Neg(); - wxTimeSpan operator-(); - //@} + wxTimeSpan& Neg(); /** Returns timespan with inverted sign. - */ - wxTimeSpan Negate() const; - /** - Add() - - Subtract() - - Multiply() - - Negate() - - Neg() - - Abs() + @see Neg() */ - + wxTimeSpan Negate() const; /** Returns the timespan for one second. @@ -1666,78 +1966,67 @@ public: static wxTimespan Seconds(long sec); /** - Milliseconds() - - Millisecond() - - Seconds() - - Second() - - Minutes() - - Minute() - - Hours() - - Hour() - - Days() - - Day() - - Weeks() - - Week() + Returns the difference of two time spans. + + @returns A new wxDateSpan object with the result. + */ + wxTimeSpan Subtract(const wxTimeSpan& diff) const; + /** + Subtracts the given wxTimeSpan to this wxTimeSpan and returns a + reference to itself. */ + wxTimeSpan& Subtract(const wxTimeSpan& diff); + /** + Returns the timespan for one week. + */ + static wxTimespan Week(); - //@{ /** - Returns the difference of two timespans. + Returns the timespan for the given number of weeks. */ - wxTimeSpan Subtract(const wxTimeSpan& diff); - const wxTimeSpan& Subtract(const wxTimeSpan& diff); - wxTimeSpan operator-=(const wxTimeSpan& diff); - //@} + static wxTimespan Weeks(long weeks); /** - IsNull() - - IsPositive() - - IsNegative() - - IsEqualTo() - - IsLongerThan() - - IsShorterThan() + Adds the given wxTimeSpan to this wxTimeSpan and returns the result. */ + wxTimeSpan& operator+=(const wxTimeSpan& diff); + /** + Multiplies this time span by @a n. + + @returns A reference to this wxTimeSpan object modified in place. + */ + wxTimeSpan& operator*=(int n); /** - Returns the timespan for one week. + Negate the value of the timespan. + + @see Negate() */ - static wxTimespan Week(); + wxTimeSpan& operator-(); /** - Returns the timespan for the given number of weeks. + Subtracts the given wxTimeSpan to this wxTimeSpan and returns the + result. */ - static wxTimespan Weeks(long weeks); + wxTimeSpan& operator-=(const wxTimeSpan& diff); }; + /** @class wxDateTimeHolidayAuthority @wxheader{datetime.h} + @todo Write wxDateTimeHolidayAuthority documentation. @library{wxbase} - @category{FIXME} + @category{misc} */ class wxDateTimeHolidayAuthority { public: }; +