X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..184abb52a8ae838ef8586ce45a550b4e8ef96e54:/interface/wx/datetime.h diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index c33ec22fb5..950ac809e8 100644 --- a/interface/wx/datetime.h +++ b/interface/wx/datetime.h @@ -3,7 +3,7 @@ // Purpose: interface of wxDateTime // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -15,26 +15,96 @@ used to contain the number of years, hours, minutes, seconds and milliseconds. + Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are + defined. This constant will be different from any valid wxDateTime object. - @section datetime_constants Constants - Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are - defined. This constant will be different from any valid wxDateTime object. + @section datetime_static Static Functions + + All static functions either set or return the static variables of + wxDateSpan (the country), return the current moment, year, month or number + of days in it, or do some general calendar-related actions. + + Please note that although several function accept an extra Calendar + parameter, it is currently ignored as only the Gregorian calendar is + supported. Future versions will support other calendars. + + @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 cannot be described with + @c strptime(3)-like format strings used by Format(), hence the need for a + separate function. + + But the most interesting functions are ParseTime(), ParseDate() and + ParseDateTime(). They try to parse the date and time (or only one of them) + in 'free' format, i.e. allow them to be specified in any of possible ways. + These functions will usually be used to parse the (interactive) user input + which is not bound to be in any predefined format. As an example, + ParseDate() can parse the strings such as "tomorrow", "March first" and + even "next Sunday". + + Finally notice that each of the parsing functions is available in several + overloads: if the input string is a narrow (@c char *) string, then a + narrow pointer is returned. If the input string is a wide string, a wide + char pointer is returned. Finally, if the input parameter is a wxString, a + narrow char pointer is also returned for backwards compatibility but there + is also an additional argument of wxString::const_iterator type in which, + if it is not @NULL, an iterator pointing to the end of the scanned string + part is returned. - 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: + @library{wxbase} + @category{data} + + @stdobjects + - ::wxDefaultDateTime - @code + @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl +*/ +class wxDateTime +{ +public: + /** + A small unsigned integer type for storing things like minutes, + seconds &c. It should be at least short (i.e. not char) to contain + the number of milliseconds - it may also be 'int' because there is + no size penalty associated with it in our code, we don't store any + data in this format. + */ + typedef unsigned short wxDateTime_t; + + + /** + Time zone symbolic names. + */ enum TZ { - // the time in the current time zone + /// the time in the current time zone Local, - // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be - // consequent numbers, so writing something like `GMT0 + offset' is - // safe if abs(offset) <= 12 + //@{ + /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be + /// consequent numbers, so writing something like `GMT0 + offset' is + /// safe if abs(offset) <= 12 // underscore stands for minus GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7, @@ -44,91 +114,194 @@ GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13, // Note that GMT12 and GMT_12 are not the same: there is a difference // of exactly one day between them + //@} // some symbolic names for TZ // Europe - WET = GMT0, // Western Europe Time - WEST = GMT1, // Western Europe Summer Time - CET = GMT1, // Central Europe Time - CEST = GMT2, // Central Europe Summer Time - EET = GMT2, // Eastern Europe Time - EEST = GMT3, // Eastern Europe Summer Time - MSK = GMT3, // Moscow Time - MSD = GMT4, // Moscow Summer Time + WET = GMT0, //!< Western Europe Time + WEST = GMT1, //!< Western Europe Summer Time + CET = GMT1, //!< Central Europe Time + CEST = GMT2, //!< Central Europe Summer Time + EET = GMT2, //!< Eastern Europe Time + EEST = GMT3, //!< Eastern Europe Summer Time + MSK = GMT3, //!< Moscow Time + MSD = GMT4, //!< Moscow Summer Time // US and Canada - AST = GMT_4, // Atlantic Standard Time - ADT = GMT_3, // Atlantic Daylight Time - EST = GMT_5, // Eastern Standard Time - EDT = GMT_4, // Eastern Daylight Saving Time - CST = GMT_6, // Central Standard Time - CDT = GMT_5, // Central Daylight Saving Time - MST = GMT_7, // Mountain Standard Time - MDT = GMT_6, // Mountain Daylight Saving Time - PST = GMT_8, // Pacific Standard Time - PDT = GMT_7, // Pacific Daylight Saving Time - HST = GMT_10, // Hawaiian Standard Time - AKST = GMT_9, // Alaska Standard Time - AKDT = GMT_8, // Alaska Daylight Saving Time + AST = GMT_4, //!< Atlantic Standard Time + ADT = GMT_3, //!< Atlantic Daylight Time + EST = GMT_5, //!< Eastern Standard Time + EDT = GMT_4, //!< Eastern Daylight Saving Time + CST = GMT_6, //!< Central Standard Time + CDT = GMT_5, //!< Central Daylight Saving Time + MST = GMT_7, //!< Mountain Standard Time + MDT = GMT_6, //!< Mountain Daylight Saving Time + PST = GMT_8, //!< Pacific Standard Time + PDT = GMT_7, //!< Pacific Daylight Saving Time + HST = GMT_10, //!< Hawaiian Standard Time + AKST = GMT_9, //!< Alaska Standard Time + AKDT = GMT_8, //!< Alaska Daylight Saving Time // Australia - A_WST = GMT8, // Western Standard Time - A_CST = GMT13 + 1, // Central Standard Time (+9.5) - A_EST = GMT10, // Eastern Standard Time - A_ESST = GMT11, // Eastern Summer Time + A_WST = GMT8, //!< Western Standard Time + A_CST = GMT13 + 1, //!< Central Standard Time (+9.5) + A_EST = GMT10, //!< Eastern Standard Time + A_ESST = GMT11, //!< Eastern Summer Time // New Zealand - NZST = GMT12, // Standard Time - NZDT = GMT13, // Daylight Saving Time + NZST = GMT12, //!< Standard Time + NZDT = GMT13, //!< Daylight Saving Time - // Universal Coordinated Time = the new and politically correct name - // for GMT + /// Universal Coordinated Time = the new and politically correct name + /// for GMT. UTC = GMT0 }; - @endcode - - Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and - Inv_Month for an invalid month are the values of @c wxDateTime::Month enum. - Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values - in @c wxDateTime::WeekDay enum. - - Finally, Inv_Year is defined to be an invalid value for year parameter. - - GetMonthName() and GetWeekDayName() functions use the following flags: - - @code - enum NameFlags + /** + Several functions accept an extra parameter specifying the calendar to use + (although most of them only support now the Gregorian calendar). This + parameters is one of the following values. + */ + enum Calendar { - Name_Full = 0x01, // return full name - Name_Abbr = 0x02 // return abbreviated name + Gregorian, ///< calendar currently in use in Western countries + Julian ///< calendar in use since -45 until the 1582 (or later) }; - @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: + /** + Values corresponding to different dates of adoption of the Gregorian + calendar. - @code - enum Calendar + @see IsGregorianDate + */ + enum GregorianAdoption { - Gregorian, // calendar currently in use in Western countries - Julian // calendar in use since -45 until the 1582 (or later) + Gr_Unknown, ///< no data for this country or it's too uncertain to use + Gr_Standard, ///< on the day 0 of Gregorian calendar: 15 Oct 1582 + + Gr_Alaska, ///< Oct 1867 when Alaska became part of the USA + Gr_Albania, ///< Dec 1912 + + Gr_Austria = Gr_Unknown, ///< Different regions on different dates + Gr_Austria_Brixen, ///< 5 Oct 1583 -> 16 Oct 1583 + Gr_Austria_Salzburg = Gr_Austria_Brixen, + Gr_Austria_Tyrol = Gr_Austria_Brixen, + Gr_Austria_Carinthia, ///< 14 Dec 1583 -> 25 Dec 1583 + Gr_Austria_Styria = Gr_Austria_Carinthia, + + Gr_Belgium, ///< Then part of the Netherlands + + Gr_Bulgaria = Gr_Unknown, ///< Unknown precisely (from 1915 to 1920) + Gr_Bulgaria_1, ///< 18 Mar 1916 -> 1 Apr 1916 + Gr_Bulgaria_2, ///< 31 Mar 1916 -> 14 Apr 1916 + Gr_Bulgaria_3, ///< 3 Sep 1920 -> 17 Sep 1920 + + Gr_Canada = Gr_Unknown, ///< Different regions followed the changes in + ///< Great Britain or France + + Gr_China = Gr_Unknown, ///< Different authorities say: + Gr_China_1, ///< 18 Dec 1911 -> 1 Jan 1912 + Gr_China_2, ///< 18 Dec 1928 -> 1 Jan 1929 + + Gr_Czechoslovakia, ///< (Bohemia and Moravia) 6 Jan 1584 -> 17 Jan 1584 + Gr_Denmark, ///< (including Norway) 18 Feb 1700 -> 1 Mar 1700 + Gr_Egypt, ///< 1875 + Gr_Estonia, ///< 1918 + Gr_Finland, ///< Then part of Sweden + + Gr_France, ///< 9 Dec 1582 -> 20 Dec 1582 + Gr_France_Alsace, ///< 4 Feb 1682 -> 16 Feb 1682 + Gr_France_Lorraine, ///< 16 Feb 1760 -> 28 Feb 1760 + Gr_France_Strasbourg, ///< February 1682 + + Gr_Germany = Gr_Unknown, ///< Different states on different dates: + Gr_Germany_Catholic, ///< 1583-1585 (we take 1584) + Gr_Germany_Prussia, ///< 22 Aug 1610 -> 2 Sep 1610 + Gr_Germany_Protestant, ///< 18 Feb 1700 -> 1 Mar 1700 + + Gr_GreatBritain, ///< 2 Sep 1752 -> 14 Sep 1752 (use 'cal(1)') + + Gr_Greece, ///< 9 Mar 1924 -> 23 Mar 1924 + Gr_Hungary, ///< 21 Oct 1587 -> 1 Nov 1587 + Gr_Ireland = Gr_GreatBritain, + Gr_Italy = Gr_Standard, + + Gr_Japan = Gr_Unknown, ///< Different authorities say: + Gr_Japan_1, ///< 19 Dec 1872 -> 1 Jan 1873 + Gr_Japan_2, ///< 19 Dec 1892 -> 1 Jan 1893 + Gr_Japan_3, ///< 18 Dec 1918 -> 1 Jan 1919 + + Gr_Latvia, ///< 1915-1918 (we take 1915) + Gr_Lithuania, ///< 1915 + Gr_Luxemburg, ///< 14 Dec 1582 -> 25 Dec 1582 + Gr_Netherlands = Gr_Belgium, ///< (including Belgium) 1 Jan 1583 + + /** + Special case of Groningen. + + The Gregorian calendar was introduced twice in Groningen, first + time 28 Feb 1583 was followed by 11 Mar 1583, then it has gone back + to Julian in the summer of 1584 and then 13 Dec 1700 was followed + by 12 Jan 1701 -- which is the date we take into account here. + */ + Gr_Netherlands_Groningen, ///< 13 Dec 1700 -> 12 Jan 1701 + Gr_Netherlands_Gelderland, ///< 30 Jun 1700 -> 12 Jul 1700 + Gr_Netherlands_Utrecht, ///< (and Overijssel) 30 Nov 1700->12 Dec 1700 + Gr_Netherlands_Friesland, ///< (and Drenthe) 31 Dec 1700 -> 12 Jan 1701 + + Gr_Norway = Gr_Denmark, ///< Then part of Denmark + Gr_Poland = Gr_Standard, + Gr_Portugal = Gr_Standard, + Gr_Romania, ///< 31 Mar 1919 -> 14 Apr 1919 + Gr_Russia, ///< 31 Jan 1918 -> 14 Feb 1918 + Gr_Scotland = Gr_GreatBritain, + Gr_Spain = Gr_Standard, + + /** + Special case of Sweden. + + Sweden has a curious history. Sweden decided to make a gradual + change from the Julian to the Gregorian calendar. By dropping every + leap year from 1700 through 1740 the eleven superfluous days would + be omitted and from 1 Mar 1740 they would be in sync with the + Gregorian calendar. (But in the meantime they would be in sync with + nobody!) + + So 1700 (which should have been a leap year in the Julian calendar) + was not a leap year in Sweden. However, by mistake 1704 and 1708 + became leap years. This left Sweden out of synchronisation with + both the Julian and the Gregorian world, so they decided to go back + to the Julian calendar. In order to do this, they inserted an extra + day in 1712, making that year a double leap year! So in 1712, + February had 30 days in Sweden. + + Later, in 1753, Sweden changed to the Gregorian calendar by + dropping 11 days like everyone else and this is what we use here. + */ + Gr_Sweden = Gr_Finland, ///< 17 Feb 1753 -> 1 Mar 1753 + + Gr_Switzerland = Gr_Unknown,///< Different cantons used different dates + Gr_Switzerland_Catholic, ///< 1583, 1584 or 1597 (we take 1584) + Gr_Switzerland_Protestant, ///< 31 Dec 1700 -> 12 Jan 1701 + + Gr_Turkey, ///< 1 Jan 1927 + Gr_USA = Gr_GreatBritain, + Gr_Wales = Gr_GreatBritain, + Gr_Yugoslavia ///< 1919 }; - @endcode - Date calculations often depend on the country and wxDateTime allows to set - the country whose conventions should be used using SetCountry(). It takes - one of the following values as parameter: - - @code + /** + Date calculations often depend on the country and wxDateTime allows to set + the country whose conventions should be used using SetCountry(). It takes + one of the following values as parameter. + */ enum Country { - Country_Unknown, // no special information for this country - Country_Default, // set the default country with SetCountry() method - // or use the default country with any other + Country_Unknown, ///< no special information for this country + Country_Default, ///< set the default country with SetCountry() method + ///< or use the default country with any other Country_WesternEurope_Start, Country_EEC = Country_WesternEurope_Start, @@ -141,98 +314,122 @@ USA }; - @endcode - Different parts of the world use different conventions for the week start. - In some countries, the week starts on Sunday, while in others -- on Monday. - The ISO standard doesn't address this issue, so we support both conventions - in the functions whose result depends on it (GetWeekOfYear() and - GetWeekOfMonth()). + /// symbolic names for the months + enum Month + { + Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, - The desired behvaiour may be specified by giving one of the following - constants as argument to these functions: + /// Invalid month value. + Inv_Month + }; - @code - enum WeekFlags + /// symbolic names for the weekdays + enum WeekDay { - Default_First, // Sunday_First for US, Monday_First for the rest - Monday_First, // week starts with a Monday - Sunday_First // week starts with a Sunday - }; - @endcode + Sun, Mon, Tue, Wed, Thu, Fri, Sat, + /// Invalid week day value. + Inv_WeekDay + }; - @section datetime_static Static Functions + /// invalid value for the year + enum Year + { + Inv_Year = SHRT_MIN // should hold in wxDateTime_t + }; - All static functions either set or return the static variables of - wxDateSpan (the country), return the current moment, year, month or number - of days in it, or do some general calendar-related actions. + /** + Flags to be used with GetMonthName() and GetWeekDayName() functions. + */ + enum NameFlags + { + Name_Full = 0x01, ///< return full name + Name_Abbr = 0x02 ///< return abbreviated name + }; - Please note that although several function accept an extra Calendar - parameter, it is currently ignored as only the Gregorian calendar is - supported. Future versions will support other calendars. + /** + Different parts of the world use different conventions for the week start. + In some countries, the week starts on Sunday, while in others -- on Monday. + The ISO standard doesn't address this issue, so we support both conventions + in the functions whose result depends on it (GetWeekOfYear() and + GetWeekOfMonth()). - @beginWxPythonOnly - These methods are standalone functions named - "wxDateTime_" in wxPython. - @endWxPythonOnly + The desired behaviour may be specified by giving one of the following + constants as argument to these functions. + */ + enum WeekFlags + { + Default_First, ///< Sunday_First for US, Monday_First for the rest + Monday_First, ///< week starts with a Monday + Sunday_First ///< week starts with a Sunday + }; - @section datetime_formatting Date Formatting and Parsing + /** + Class representing a time zone. - The date formatting and parsing functions convert wxDateTime objects to and - from text. The conversions to text are mostly trivial: you can either do it - using the default date and time representations for the current locale - (FormatDate() and FormatTime()), using the international standard - representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and - FormatISOCombined()) or by specifying any format at all and using Format() - directly. + The representation is simply the offset, in seconds, from UTC. + */ + class WXDLLIMPEXP_BASE TimeZone + { + public: + /// Constructor for a named time zone. + TimeZone(TZ tz); - The conversions from text are more interesting, as there are much more - possibilities to care about. The simplest cases can be taken care of with - ParseFormat() which can parse any date in the given (rigid) format. - ParseRfc822Date() is another function for parsing dates in predefined - format -- the one of RFC 822 which (still...) defines the format of email - messages on the Internet. This format can not be described with - @c strptime(3)-like format strings used by Format(), hence the need for a - separate function. + /// Constructor for the given offset in seconds. + TimeZone(long offset = 0); - But the most interesting functions are ParseTime(), ParseDate() and - ParseDateTime(). They try to parse the date and time (or only one of them) - in 'free' format, i.e. allow them to be specified in any of possible ways. - These functions will usually be used to parse the (interactive) user input - which is not bound to be in any predefined format. As an example, - ParseDateTime() can parse the strings such as "tomorrow", "March first" and - even "next Sunday". + /// Create a time zone with the given offset in seconds. + static TimeZone Make(long offset); - Finally notice that each of the parsing functions is available in several - overloads: if the input string is a narrow (@c char *) string, then a - narrow pointer is returned. If the input string is a wide string, a wide - char pointer is returned. Finally, if the input parameter is a wxString, a - narrow char pointer is also returned for backwards compatibility but there - is also an additional argument of wxString::const_iterator type in which, - if it is not @NULL, an iterator pointing to the end of the scanned string - part is returned. + /// Return the offset of this time zone from UTC, in seconds. + long GetOffset() const; + }; + /** + Contains broken down date-time representation. - @library{wxbase} - @category{data} + This struct is analogous to standard C struct tm and uses + the same, not always immediately obvious, conventions for its members: + notably its mon and mday fields count from 0 while yday counts from 1. + */ + struct Tm + { + wxDateTime_t msec, ///< Number of milliseconds. + sec, ///< Seconds in 0..59 (60 with leap seconds) range. + min, ///< Minutes in 0..59 range. + hour, ///< Hours since midnight in 0..23 range. + mday, ///< Day of the month in 1..31 range. + yday; ///< Day of the year in 0..365 range. + Month mon; ///< Month, as an enumerated constant. + int year; ///< Year. + + /** + Check if the given date/time is valid (in Gregorian calendar). + + Return @false if the components don't correspond to a correct date. + */ + bool IsValid() const; + + /** + Return the week day corresponding to this date. + + Unlike the other fields, the week day is not always available and + so must be accessed using this method as it is computed on demand + when it is called. + */ + WeekDay GetWeekDay(); + }; - @stdobjects - - ::wxDefaultDateTime - @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl -*/ -class wxDateTime -{ -public: /** @name Constructors, Assignment Operators and Setters Constructors and various Set() methods are collected here. If you construct a date object from separate values for day, month and year, you should use IsValid() method to check that the values were correct - as constructors can not return an error code. + as constructors cannot return an error code. */ //@{ @@ -248,13 +445,13 @@ public: This constructor is named "wxDateTimeFromTimeT" in wxPython. @endWxPythonOnly */ - wxDateTime& wxDateTime(time_t timet); + wxDateTime(time_t timet); /** Same as Set(). @beginWxPythonOnly Unsupported. @endWxPythonOnly */ - wxDateTime& wxDateTime(const struct tm& tm); + wxDateTime(const struct tm& tm); /** Same as Set(). @@ -262,7 +459,7 @@ public: This constructor is named "wxDateTimeFromJDN" in wxPython. @endWxPythonOnly */ - wxDateTime& wxDateTime(double jdn); + wxDateTime(double jdn); /** Same as Set(). @@ -270,8 +467,8 @@ public: 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); + wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0, + wxDateTime_t second = 0, wxDateTime_t millisec = 0); /** Same as Set(). @@ -350,7 +547,7 @@ public: /** Sets the day without changing other date components. */ - wxDateTime& SetDay(short unsigned int); + wxDateTime& SetDay(unsigned short day); /** Sets the date from the date and time in DOS format. @@ -360,17 +557,17 @@ public: /** Sets the hour without changing other date components. */ - wxDateTime& SetHour(short unsigned int); + wxDateTime& SetHour(unsigned short hour); /** Sets the millisecond without changing other date components. */ - wxDateTime& SetMillisecond(short unsigned int); + wxDateTime& SetMillisecond(unsigned short millisecond); /** Sets the minute without changing other date components. */ - wxDateTime& SetMinute(short unsigned int); + wxDateTime& SetMinute(unsigned short minute); /** Sets the month without changing other date components. @@ -380,7 +577,7 @@ public: /** Sets the second without changing other date components. */ - wxDateTime& SetSecond(short unsigned int); + wxDateTime& SetSecond(unsigned short second); /** Sets the date and time of to the current values. Same as assigning the @@ -509,8 +706,7 @@ public: Returns the ordinal number of the week in the month (in 1-5 range). As GetWeekOfYear(), this function supports both conventions for the - week start. See the description of these @c WeekFlags in the - @ref datetime_constants section. + week start. */ wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, const TimeZone& tz = Local) const; @@ -524,10 +720,9 @@ public: year. Accordingly, the week number will always be in 1-53 range (52 for non-leap years). - The function depends on the @ref datetime_constants "week start" - convention specified by the @a flags argument but its results for - @c Sunday_First are not well-defined as the ISO definition quoted above - applies to the weeks starting on Monday only. + The function depends on the week start convention specified by the @a flags + argument but its results for @c Sunday_First are not well-defined as the + ISO definition quoted above applies to the weeks starting on Monday only. */ wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, const TimeZone& tz = Local) const; @@ -736,8 +931,8 @@ public: /** This function does the same as the standard ANSI C @c strftime(3) - function. Please see its description for the meaning of @a format - parameter. + function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html). + Please see its description for the meaning of @a format parameter. It also accepts a few wxWidgets-specific extensions: you can optionally specify the width of the field to follow using @c printf(3)-like syntax @@ -746,7 +941,7 @@ public: @see ParseFormat() */ - wxString Format(const wxChar* format = wxDefaultDateTimeFormat, + wxString Format(const wxString& format = wxDefaultDateTimeFormat, const TimeZone& tz = Local) const; /** @@ -759,7 +954,7 @@ public: Returns the combined date-time representation in the ISO 8601 format @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces the result exactly corresponding to the ISO standard, but it can also - be useful to use a space as seprator if a more human-readable combined + be useful to use a space as separator if a more human-readable combined date-time representation is needed. @see FormatISODate(), FormatISOTime(), ParseISOCombined() @@ -786,67 +981,33 @@ public: /** This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + be specified. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const wxString& date, - wxString::const_iterator* end = NULL); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + It is thus less flexible then ParseDateTime(), but also has less + chances to misinterpret the user input. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const char* date); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. + See ParseFormat() for the description of function parameters and return + value. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + @see Format() */ - const wchar_t* ParseDate(const wchar_t* date); + bool ParseDate(const wxString& date, wxString::const_iterator *end); /** Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. + format. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDateTime(const wxString& datetime, - wxString::const_iterator* end = NULL); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. + This function tries as hard as it can to interpret the given string as + date and time. Unlike ParseRfc822Date(), it will accept anything that + may be accepted and will only reject strings which cannot be parsed in + any way at all. Notice that the function will fail if either date or + time part is present but not both, use ParseDate() or ParseTime() to + parse strings containing just the date or time component. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const char* ParseDateTime(const char* datetime); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseDateTime(const wchar_t* datetime); + bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end); /** This function parses the string @a date according to the given @@ -867,63 +1028,53 @@ public: @a dateDef. If it is not specified, Today() is used as the default date. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseFormat(const wxString& date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime, - wxString::const_iterator* end = NULL); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. + Example of using this function: + @code + wxDateTime dt; + wxString str = "..."; + wxString::const_iterator end; + if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) ) + ... parsing failed ... + else if ( end == str.end() ) + ... entire string parsed ... + else + ... wxString(end, str.end()) left over ... + @endcode - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. + @param date + The string to be parsed. + @param format + strptime()-like format string. + @param dateDef + Used to fill in the date components not specified in the @a date + string. + @param end + Will be filled with the iterator pointing to the location where the + parsing stopped if the function returns @true. If the entire string + was consumed, it is set to @c date.end(). Notice that this argument + must be non-@NULL. + @return + @true if at least part of the string was parsed successfully, + @false otherwise. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + @see Format() */ - const char* ParseFormat(const char* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. + bool ParseFormat(const wxString& date, + const wxString& format, + const wxDateTime& dateDef, + wxString::const_iterator *end); - 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. + /** + @overload + */ + bool ParseFormat(const wxString& date, + const wxString& format, + wxString::const_iterator *end); - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ - const wchar_t* ParseFormat(const wchar_t* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); + bool ParseFormat(const wxString& date, wxString::const_iterator *end); /** This function parses the string containing the date and time in ISO @@ -969,73 +1120,20 @@ public: string which is not RFC 822 compliant. If you need to parse date formatted in more free ways, you should use ParseDateTime() or ParseDate() instead. - */ - const char* ParseRfc822Date(const wxString& date, - wxString::const_iterator* end = NULL); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. + See ParseFormat() for the description of function parameters and return + value. */ - const char* ParseRfc822Date(const char* date); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. - */ - const wchar_t* ParseRfc822Date(const wchar_t* date); + bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end); /** This functions is like ParseDateTime(), but only allows the time to be specified in the input string. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const char* ParseTime(const wxString& time, - wxString::const_iterator* end = NULL); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseTime(const char* time); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseTime(const wchar_t* time); + bool ParseTime(const wxString& time, wxString::const_iterator *end); //@} @@ -1104,8 +1202,7 @@ public: @return The reference to the modified object itself. */ - wxDateTime SetToLastMonthDay(Month month = Inv_Month, - int year = Inv_Year); + wxDateTime& SetToLastMonthDay(Month month = Inv_Month, int year = Inv_Year); /** The effect of calling this function is the same as of calling @@ -1155,7 +1252,7 @@ public: @return The reference to the modified object itself. */ - wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, + wxDateTime& SetToWeekDayInSameWeek(WeekDay weekday, WeekFlags flags = Monday_First); /** @@ -1202,10 +1299,10 @@ public: /** 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. + 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; @@ -1251,13 +1348,13 @@ public: /** Same as FromTimezone() but modifies the object in place. */ - wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false); + wxDateTime& MakeFromTimezone(const TimeZone& tz, bool noDST = false); /** Modifies the object in place to represent the date in another time zone. If @a noDST is @true, no DST adjustments will be made. */ - wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false); + wxDateTime& MakeTimezone(const TimeZone& tz, bool noDST = false); /** This is the same as calling MakeTimezone() with the argument @c GMT0. @@ -1352,8 +1449,53 @@ public: static int GetCurrentYear(Calendar cal = Gregorian); /** - Gets the full (default) or abbreviated (specify @c Name_Abbr name of - the given month. + Return the standard English name of the given month. + + This function always returns "January" or "Jan" for January, use + GetMonthName() to retrieve the name of the month in the users current + locale. + + @param month + One of wxDateTime::Jan, ..., wxDateTime::Dec values. + @param flags + Either Name_Full (default) or Name_Abbr. + + @see GetEnglishWeekDayName() + + @since 2.9.0 + */ + static wxString GetEnglishMonthName(Month month, + NameFlags flags = Name_Full); + + /** + Return the standard English name of the given week day. + + This function always returns "Monday" or "Mon" for Monday, use + GetWeekDayName() to retrieve the name of the month in the users current + locale. + + @param weekday + One of wxDateTime::Sun, ..., wxDateTime::Sat values. + @param flags + Either Name_Full (default) or Name_Abbr. + + @see GetEnglishMonthName() + + @since 2.9.0 + */ + static wxString GetEnglishWeekDayName(WeekDay weekday, + NameFlags flags = Name_Full); + + /** + Gets the full (default) or abbreviated name of the given month. + + This function returns the name in the current locale, use + GetEnglishMonthName() to get the untranslated name if necessary. + + @param month + One of wxDateTime::Jan, ..., wxDateTime::Dec values. + @param flags + Either Name_Full (default) or Name_Abbr. @see GetWeekDayName() */ @@ -1386,10 +1528,10 @@ public: static time_t GetTimeNow(); /** - Returns the current time broken down using the buffer whose adress is + Returns the current time broken down using the buffer whose address is passed to the function with @a tm to store the result. */ - static struct tm* GetTmNow(struct tm *tm); + static tm* GetTmNow(struct tm *tm); /** Returns the current time broken down. Note that this function returns a @@ -1398,19 +1540,26 @@ public: your code might be used in a multi-threaded application, you really should use GetTmNow(struct tm *) instead. */ - static struct tm* GetTmNow(); + static tm* GetTmNow(); /** - Gets the full (default) or abbreviated (specify @c Name_Abbr) name of - the given week day. + Gets the full (default) or abbreviated name of the given week day. + + This function returns the name in the current locale, use + GetEnglishWeekDayName() to get the untranslated name if necessary. + + @param weekday + One of wxDateTime::Sun, ..., wxDateTime::Sat values. + @param flags + Either Name_Full (default) or Name_Abbr. @see GetMonthName() */ static wxString GetWeekDayName(WeekDay weekday, - NameFlags flags = Name_Full); + NameFlags flags = Name_Full); /** - Returns @true if DST was used n the given year (the current one by + Returns @true if DST was used in the given year (the current one by default) in the given country. */ static bool IsDSTApplicable(int year = Inv_Year, @@ -1451,9 +1600,6 @@ public: Sets the country to use by default. This setting influences the DST calculations, date formatting and other things. - The possible values for @a country parameter are enumerated in the - @ref datetime_constants section. - @see GetCountry() */ static void SetCountry(Country country); @@ -1496,6 +1642,10 @@ public: */ const wxDateTime wxDefaultDateTime; +/* + wxInvalidDateTime is an alias for wxDefaultDateTime. +*/ +#define wxInvalidDateTime wxDefaultDateTime /** @@ -1797,7 +1947,7 @@ public: 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); + wxTimeSpan(long hours, long min = 0, wxLongLong sec = 0, wxLongLong msec = 0); /** Returns the absolute value of the timespan: does not modify the object. @@ -1819,12 +1969,12 @@ public: /** Returns the timespan for one day. */ - static wxTimespan Day(); + static wxTimeSpan Day(); /** Returns the timespan for the given number of days. */ - static wxTimespan Days(long days); + static wxTimeSpan Days(long days); /** Returns the string containing the formatted representation of the time @@ -1892,12 +2042,12 @@ public: /** Returns the timespan for one hour. */ - static wxTimespan Hour(); + static wxTimeSpan Hour(); /** Returns the timespan for the given number of hours. */ - static wxTimespan Hours(long hours); + static wxTimeSpan Hours(long hours); /** Returns @true if two timespans are equal. @@ -1936,22 +2086,22 @@ public: /** Returns the timespan for one millisecond. */ - static wxTimespan Millisecond(); + static wxTimeSpan Millisecond(); /** Returns the timespan for the given number of milliseconds. */ - static wxTimespan Milliseconds(long ms); + static wxTimeSpan Milliseconds(wxLongLong ms); /** Returns the timespan for one minute. */ - static wxTimespan Minute(); + static wxTimeSpan Minute(); /** Returns the timespan for the given number of minutes. */ - static wxTimespan Minutes(long min); + static wxTimeSpan Minutes(long min); /** Returns the product of this time span by @a n. @@ -1983,12 +2133,12 @@ public: /** Returns the timespan for one second. */ - static wxTimespan Second(); + static wxTimeSpan Second(); /** Returns the timespan for the given number of seconds. */ - static wxTimespan Seconds(long sec); + static wxTimeSpan Seconds(wxLongLong sec); /** Returns the difference of two time spans. @@ -2005,12 +2155,12 @@ public: /** Returns the timespan for one week. */ - static wxTimespan Week(); + static wxTimeSpan Week(); /** Returns the timespan for the given number of weeks. */ - static wxTimespan Weeks(long weeks); + static wxTimeSpan Weeks(long weeks); /** Adds the given wxTimeSpan to this wxTimeSpan and returns the result. @@ -2046,7 +2196,7 @@ public: @todo Write wxDateTimeHolidayAuthority documentation. @library{wxbase} - @category{misc} + @category{data} */ class wxDateTimeHolidayAuthority {