Recognize VC12 (a.k.a. MSVS 2013) and define __VISUALC12__ for it.

[wxWidgets.git] / interface / wx / datetime.h

diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index 8599707e8b670993927e897e62b1dc9eaeeea7dd..f49315e693b819d8e4138d85ad896e7c18058bf6 100644 (file)
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -3,38 +3,102 @@
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxDateTime
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxDateTime
 

-    wxDateTime class represents an absolute moment in the time.
+    wxDateTime class represents an absolute moment in time.

 
     The type @c wxDateTime_t is typedefed as <tt>unsigned short</tt> and is
     used to contain the number of years, hours, minutes, seconds and
     milliseconds.
 
 
     The type @c wxDateTime_t is typedefed as <tt>unsigned short</tt> and is
     used to contain the number of years, hours, minutes, seconds and
     milliseconds.
 

+    Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are
+    defined. This constant will be different from any valid wxDateTime object.

 
 

-    @section datetime_constants Constants

 
 

-    Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
-    defined. This constant will be different from any valid wxDateTime object.
+    @section datetime_static Static Functions
+
+    All static functions either set or return the static variables of
+    wxDateSpan (the country), return the current moment, year, month or number
+    of days in it, or do some general calendar-related actions.
+
+    Please note that although several function accept an extra Calendar
+    parameter, it is currently ignored as only the Gregorian calendar is
+    supported. Future versions will support other calendars.
+
+    @section datetime_formatting Date Formatting and Parsing
+
+    The date formatting and parsing functions convert wxDateTime objects to and
+    from text. The conversions to text are mostly trivial: you can either do it
+    using the default date and time representations for the current locale
+    (FormatDate() and FormatTime()), using the international standard
+    representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and
+    FormatISOCombined()) or by specifying any format at all and using Format()
+    directly.

 
 

-    All the following constants are defined inside wxDateTime class (i.e., to
-    refer to them you should prepend their names with "wxDateTime::").
+    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.

 
 

-    Time zone symbolic names:
+    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".

 
 

-    @code
+    Finally notice that each of the parsing functions is available in several
+    overloads: if the input string is a narrow (@c char *) string, then a
+    narrow pointer is returned. If the input string is a wide string, a wide
+    char pointer is returned. Finally, if the input parameter is a wxString, a
+    narrow char pointer is also returned for backwards compatibility but there
+    is also an additional argument of wxString::const_iterator type in which,
+    if it is not @NULL, an iterator pointing to the end of the scanned string
+    part is returned.
+
+
+    @library{wxbase}
+    @category{data}
+
+    @stdobjects
+    - ::wxDefaultDateTime
+
+    @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
     {
     enum TZ
     {

-        // the time in the current time zone
+        /// the time in the current time zone

         Local,
 
         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,
 
         // underscore stands for minus
         GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,


@@ -44,91 +108,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
         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
 
         // 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
 
         // 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
 
 
         // 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
 
         // 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
     };
         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
     {
     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,
 
         Country_WesternEurope_Start,
         Country_EEC = Country_WesternEurope_Start,


@@ -141,98 +308,122 @@
 
         USA
     };
 
         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_<StaticMethodName>" 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 <code>struct tm</code> 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
     /**
         @name Constructors, Assignment Operators and Setters
 
         Constructors and various Set() methods are collected here. If you
         construct a date object from separate values for day, month and year,
         you should use IsValid() method to check that the values were correct

-        as constructors can not return an error code.
+        as constructors cannot return an error code.

     */
     //@{
 
     */
     //@{
 


@@ -241,45 +432,33 @@ public:
         object later.
     */
     wxDateTime();
         object later.
     */
     wxDateTime();

+
+    /**
+       Copy constructor.
+    */
+    wxDateTime(const wxDateTime& date);
+    

     /**
         Same as Set().
     /**
         Same as Set().

-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromTimeT" in wxPython.
-        @endWxPythonOnly

     */
     */

-    wxDateTime& wxDateTime(time_t timet);
+    wxDateTime(time_t timet);

     /**
         Same as Set().
     /**
         Same as Set().

-
-        @beginWxPythonOnly Unsupported. @endWxPythonOnly

     */
     */

-    wxDateTime& wxDateTime(const struct tm& tm);
+    wxDateTime(const struct tm& tm);

     /**
         Same as Set().
     /**
         Same as Set().

-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromJDN" in wxPython.
-        @endWxPythonOnly

     */
     */

-    wxDateTime& wxDateTime(double jdn);
+    wxDateTime(double jdn);

     /**
         Same as Set().
     /**
         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);
+    wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0,
+               wxDateTime_t second = 0, wxDateTime_t millisec = 0);

     /**
         Same as Set().
     /**
         Same as Set().

-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromDMY" in wxPython.
-        @endWxPythonOnly

     */
     */

-    wxDateTime(wxDateTime_t day, Month month = Inv_Month,
+    wxDateTime(wxDateTime_t day, Month month,

                int year = Inv_Year, wxDateTime_t hour = 0,
                wxDateTime_t minute = 0, wxDateTime_t second = 0,
                wxDateTime_t millisec = 0);
                int year = Inv_Year, wxDateTime_t hour = 0,
                wxDateTime_t minute = 0, wxDateTime_t second = 0,
                wxDateTime_t millisec = 0);


@@ -291,6 +470,7 @@ public:
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only

+        @onlyfor{wxmsw}

     */
     wxDateTime(const struct _SYSTEMTIME& st);
 
     */
     wxDateTime(const struct _SYSTEMTIME& st);
 


@@ -302,20 +482,24 @@ public:
 
     /**
         Constructs the object from @a timet value holding the number of seconds
 
     /**
         Constructs the object from @a timet value holding the number of seconds

-        since Jan 1, 1970.
+        since Jan 1, 1970 UTC.

 
 

-        @beginWxPythonOnly
-        This method is named "SetTimeT" in wxPython.
-        @endWxPythonOnly
+        If @a timet is invalid, i.e. @code (time_t)-1 @endcode, wxDateTime
+        becomes invalid too, i.e. its IsValid() will return @false.

     */
     wxDateTime& Set(time_t timet);
     /**
         Sets the date and time from the broken down representation in the
         standard @a tm structure.
     */
     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);
     */
     wxDateTime& Set(const struct tm& tm);

+
+    /**
+       Sets the date and time from the broken down representation in the
+       @a wxDateTime::Tm structure.
+    */
+    wxDateTime& Set(const Tm& tm);
+    

     /**
         Sets the date from the so-called Julian Day Number.
 
     /**
         Sets the date from the so-called Julian Day Number.
 


@@ -323,26 +507,18 @@ public:
         particular instant is the fractional number of days since 12 hours
         Universal Coordinated Time (Greenwich mean noon) on January 1 of the
         year -4712 in the Julian proleptic calendar.
         particular instant is the fractional number of days since 12 hours
         Universal Coordinated Time (Greenwich mean noon) on January 1 of the
         year -4712 in the Julian proleptic calendar.

-
-        @beginWxPythonOnly
-        This method is named "SetJDN" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime& Set(double jdn);
     /**
         Sets the date to be equal to Today() and the time from supplied
         parameters.
     */
     wxDateTime& Set(double jdn);
     /**
         Sets the date to be equal to Today() and the time from supplied
         parameters.

-
-        @beginWxPythonOnly
-        This method is named "SetHMS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0,
                     wxDateTime_t second = 0, wxDateTime_t millisec = 0);
     /**
         Sets the date and time from the parameters.
     */
     */
     wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0,
                     wxDateTime_t second = 0, wxDateTime_t millisec = 0);
     /**
         Sets the date and time from the parameters.
     */

-    wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
+    wxDateTime& Set(wxDateTime_t day, Month month,

                     int year = Inv_Year, wxDateTime_t hour = 0,
                     wxDateTime_t minute = 0, wxDateTime_t second = 0,
                     wxDateTime_t millisec = 0);
                     int year = Inv_Year, wxDateTime_t hour = 0,
                     wxDateTime_t minute = 0, wxDateTime_t second = 0,
                     wxDateTime_t millisec = 0);


@@ -350,7 +526,7 @@ public:
     /**
         Sets the day without changing other date components.
     */
     /**
         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.
 
     /**
         Sets the date from the date and time in DOS format.


@@ -360,17 +536,17 @@ public:
     /**
         Sets the hour without changing other date components.
     */
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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.
 
     /**
         Sets the month without changing other date components.


@@ -380,7 +556,7 @@ public:
     /**
         Sets the second without changing other date components.
     */
     /**
         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
 
     /**
         Sets the date and time of to the current values. Same as assigning the


@@ -418,7 +594,7 @@ public:
     /**
         Returns the date and time in DOS format.
     */
     /**
         Returns the date and time in DOS format.
     */

-    long unsigned int GetAsDOS() const;
+    unsigned long GetAsDOS() const;

 
     /**
         Initialize using the Windows SYSTEMTIME structure.
 
     /**
         Initialize using the Windows SYSTEMTIME structure.


@@ -426,6 +602,7 @@ public:
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only

+        @onlyfor{wxmsw}

     */
     wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
 
     */
     wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
 


@@ -435,6 +612,7 @@ public:
             Output, pointer to Windows SYSTEMTIME
         @since 2.9.0
         @remarks MSW only
             Output, pointer to Windows SYSTEMTIME
         @since 2.9.0
         @remarks MSW only

+        @onlyfor{wxmsw}

     */
     void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
 
     */
     void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
 


@@ -456,28 +634,28 @@ public:
     /**
         Returns the day in the given timezone (local one by default).
     */
     /**
         Returns the day in the given timezone (local one by default).
     */

-    short unsigned int GetDay(const TimeZone& tz = Local) const;
+    unsigned short GetDay(const TimeZone& tz = Local) const;

 
     /**
         Returns the day of the year (in 1-366 range) in the given timezone
         (local one by default).
     */
 
     /**
         Returns the day of the year (in 1-366 range) in the given timezone
         (local one by default).
     */

-    short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
+    unsigned short GetDayOfYear(const TimeZone& tz = Local) const;

 
     /**
         Returns the hour in the given timezone (local one by default).
     */
 
     /**
         Returns the hour in the given timezone (local one by default).
     */

-    short unsigned int GetHour(const TimeZone& tz = Local) const;
+    unsigned short GetHour(const TimeZone& tz = Local) const;

 
     /**
         Returns the milliseconds in the given timezone (local one by default).
     */
 
     /**
         Returns the milliseconds in the given timezone (local one by default).
     */

-    short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
+    unsigned short GetMillisecond(const TimeZone& tz = Local) const;

 
     /**
         Returns the minute in the given timezone (local one by default).
     */
 
     /**
         Returns the minute in the given timezone (local one by default).
     */

-    short unsigned int GetMinute(const TimeZone& tz = Local) const;
+    unsigned short GetMinute(const TimeZone& tz = Local) const;

 
     /**
         Returns the month in the given timezone (local one by default).
 
     /**
         Returns the month in the given timezone (local one by default).


@@ -487,11 +665,13 @@ public:
     /**
         Returns the seconds in the given timezone (local one by default).
     */
     /**
         Returns the seconds in the given timezone (local one by default).
     */

-    short unsigned int GetSecond(const TimeZone& tz = Local) const;
+    unsigned short GetSecond(const TimeZone& tz = Local) const;

 
     /**
 
     /**

-        Returns the number of seconds since Jan 1, 1970. An assert failure will
-        occur if the date is not in the range covered by @c time_t type.
+        Returns the number of seconds since Jan 1, 1970 UTC.
+
+        An assert failure will occur if the date is not in the range covered by
+        @c time_t type, use GetValue() if you work with dates outside of it.

     */
     time_t GetTicks() const;
 
     */
     time_t GetTicks() const;
 


@@ -509,8 +689,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
         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;
     */
     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
                                 const TimeZone& tz = Local) const;


@@ -524,10 +703,9 @@ public:
         year. Accordingly, the week number will always be in 1-53 range (52 for
         non-leap years).
 
         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;
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;


@@ -578,7 +756,7 @@ public:
 
     /**
         Returns @true if the date is equal to another one up to the given time
 
     /**
         Returns @true if the date is equal to another one up to the given time

-        interval, i.e. if the absolute difference between the two dates is less
+        interval, i.e.\ if the absolute difference between the two dates is less

         than this interval.
     */
     bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
         than this interval.
     */
     bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;


@@ -637,67 +815,35 @@ public:
 
     /**
         Adds the given date span to this object.
 
     /**
         Adds the given date span to this object.

-
-        @beginWxPythonOnly
-        This method is named "AddDS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime Add(const wxDateSpan& diff) const;
     /**
         Adds the given date span to this object.
     */
     wxDateTime Add(const wxDateSpan& diff) const;
     /**
         Adds the given date span to this object.

-
-        @beginWxPythonOnly
-        This method is named "AddDS" in wxPython.
-        @endWxPythonOnly

     */
     */

-    wxDateTime Add(const wxDateSpan& diff);
+    wxDateTime& Add(const wxDateSpan& diff);

     /**
         Adds the given time span to this object.
     /**
         Adds the given time span to this object.

-
-        @beginWxPythonOnly
-        This method is named "AddTS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime Add(const wxTimeSpan& diff) const;
     /**
         Adds the given time span to this object.
     */
     wxDateTime Add(const wxTimeSpan& diff) const;
     /**
         Adds the given time span to this object.

-
-        @beginWxPythonOnly
-        This method is named "AddTS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime& Add(const wxTimeSpan& diff);
 
     /**
         Subtracts the given time span from this object.
     */
     wxDateTime& Add(const wxTimeSpan& diff);
 
     /**
         Subtracts the given time span from this object.

-
-        @beginWxPythonOnly
-        This method is named "SubtractTS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime Subtract(const wxTimeSpan& diff) const;
     /**
         Subtracts the given time span from this object.
     */
     wxDateTime Subtract(const wxTimeSpan& diff) const;
     /**
         Subtracts the given time span from this object.

-
-        @beginWxPythonOnly
-        This method is named "SubtractTS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime& Subtract(const wxTimeSpan& diff);
     /**
         Subtracts the given date span from this object.
     */
     wxDateTime& Subtract(const wxTimeSpan& diff);
     /**
         Subtracts the given date span from this object.

-
-        @beginWxPythonOnly
-        This method is named "SubtractDS" in wxPython.
-        @endWxPythonOnly

     */
     wxDateTime Subtract(const wxDateSpan& diff) const;
     /**
         Subtracts the given date span from this object.
     */
     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);
     /**
     */
     wxDateTime& Subtract(const wxDateSpan& diff);
     /**


@@ -705,23 +851,53 @@ public:
         them as a wxTimeSpan.
     */
     wxTimeSpan Subtract(const wxDateTime& dt) const;
         them as a wxTimeSpan.
     */
     wxTimeSpan Subtract(const wxDateTime& dt) const;

+    /**
+       Returns the difference between this object and @a dt as a wxDateSpan.
+
+       This method allows to find the number of entire years, months, weeks and
+       days between @a dt and this date.

 
 

+       @since 2.9.5
+    */
+    wxDateSpan DiffAsDateSpan(const wxDateTime& dt) const;
+
+    /**
+        Adds the given date span to this object.
+    */
+    wxDateTime& operator+=(const wxDateSpan& diff);

     /**
         Adds the given date span to this object.
     */
     /**
         Adds the given date span to this object.
     */

-    wxDateTime operator+=(const wxDateSpan& diff);
+    wxDateTime operator+(const wxDateSpan& ds) const;

     /**
         Subtracts the given date span from this object.
     */
     wxDateTime& operator-=(const wxDateSpan& diff);
     /**
         Subtracts the given date span from this object.
     */
     wxDateTime& operator-=(const wxDateSpan& diff);

+    /**
+        Subtracts the given date span from this object.
+    */
+    wxDateTime operator-(const wxDateSpan& ds) const;

     /**
         Adds the given time span to this object.
     */
     wxDateTime& operator+=(const wxTimeSpan& diff);
     /**
         Adds the given time span to this object.
     */
     wxDateTime& operator+=(const wxTimeSpan& diff);

+    /**
+        Adds the given time span to this object.
+    */
+    wxDateTime operator+(const wxTimeSpan& ts) const;

     /**
         Subtracts the given time span from this object.
     */
     wxDateTime& operator-=(const wxTimeSpan& diff);
     /**
         Subtracts the given time span from this object.
     */
     wxDateTime& operator-=(const wxTimeSpan& diff);

+    /**
+        Subtracts the given time span from this object.
+    */
+    wxDateTime operator-(const wxTimeSpan& ts) const;
+    /**
+        Subtracts another date from this one and returns the difference between
+        them as a wxTimeSpan.
+    */
+    wxTimeSpan operator-(const wxDateTime& dt2) const;

 
     //@}
 
 
     //@}
 


@@ -736,8 +912,8 @@ public:
 
     /**
         This function does the same as the standard ANSI C @c strftime(3)
 
     /**
         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
 
         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 +922,7 @@ public:
 
         @see ParseFormat()
     */
 
         @see ParseFormat()
     */

-    wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
+    wxString Format(const wxString& format = wxDefaultDateTimeFormat,

                     const TimeZone& tz = Local) const;
 
     /**
                     const TimeZone& tz = Local) const;
 
     /**


@@ -759,7 +935,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
         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()
         date-time representation is needed.
 
         @see FormatISODate(), FormatISOTime(), ParseISOCombined()


@@ -786,67 +962,33 @@ public:
 
     /**
         This function is like ParseDateTime(), but it only allows the date to
 
     /**
         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
 
     /**
         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
 
     /**
         This function parses the string @a date according to the given


@@ -867,63 +1009,53 @@ public:
         @a dateDef. If it is not specified, Today() is used as the default
         date.
 
         @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.
+        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

 
 

-        Please see the description of the ANSI C function @c strftime(3) for
-        the syntax of the format string.
+        @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.

 
 

-        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.
-
-        @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
 
     /**
         This function parses the string containing the date and time in ISO


@@ -969,73 +1101,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.
         string which is not RFC 822 compliant. If you need to parse date
         formatted in more free ways, you should use ParseDateTime() or
         ParseDate() instead.

-    */
-    const char* ParseRfc822Date(const wxString& date,
-                                  wxString::const_iterator* end = NULL);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
-
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
-    */
-    const char* ParseRfc822Date(const char* date);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
-
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
-    */
-    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.
-
-        @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.
+    bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);

 
 

-        @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.
 
     /**
         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 wchar_t* ParseTime(const wchar_t* time);
+    bool ParseTime(const wxString& time, wxString::const_iterator *end);

 
     //@}
 
 
     //@}
 


@@ -1104,8 +1183,7 @@ public:
 
         @return The reference to the modified object itself.
     */
 
         @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
 
     /**
         The effect of calling this function is the same as of calling


@@ -1155,11 +1233,11 @@ public:
 
         @return The reference to the modified object itself.
     */
 
         @return The reference to the modified object itself.
     */

-    wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
+    wxDateTime& SetToWeekDayInSameWeek(WeekDay weekday,

                                       WeekFlags flags = Monday_First);
 
     /**
                                       WeekFlags flags = Monday_First);
 
     /**

-        Sets the date to the day number @a yday in the same year (i.e., unlike
+        Sets the date to the day number @a yday in the same year (i.e.\ unlike

         the other functions, this one does not use the current year). The day
         number should be in the range 1-366 for the leap years and 1-365 for
         the other ones.
         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.


@@ -1251,13 +1329,13 @@ public:
     /**
         Same as FromTimezone() but modifies the object in place.
     */
     /**
         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.
     */
 
     /**
         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.
 
     /**
         This is the same as calling MakeTimezone() with the argument @c GMT0.


@@ -1284,7 +1362,7 @@ public:
 
 
     /**
 
 
     /**

-        Converts the year in absolute notation (i.e. a number which can be
+        Converts the year in absolute notation (i.e.\ a number which can be

         negative, positive or zero) to the year in BC/AD notation. For the
         positive years, nothing is done, but the year 0 is year 1 BC and so for
         other years there is a difference of 1.
         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.


@@ -1326,7 +1404,7 @@ public:
                                  Country country = Country_Default);
 
     /**
                                  Country country = Country_Default);
 
     /**

-        Get the current century, i.e. first two digits of the year, in given
+        Get the current century, i.e.\ first two digits of the year, in given

         calendar (only Gregorian is currently supported).
     */
     static int GetCentury(int year);
         calendar (only Gregorian is currently supported).
     */
     static int GetCentury(int year);


@@ -1352,8 +1430,53 @@ public:
     static int GetCurrentYear(Calendar cal = Gregorian);
 
     /**
     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()
     */
 
         @see GetWeekDayName()
     */


@@ -1362,20 +1485,12 @@ public:
     /**
         Returns the number of days in the given year. The only supported value
         for @a cal currently is @c Gregorian.
     /**
         Returns the number of days in the given year. The only supported value
         for @a cal currently is @c Gregorian.

-
-        @beginWxPythonOnly
-        This method is named "GetNumberOfDaysInYear" in wxPython.
-        @endWxPythonOnly

     */
     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
 
     /**
         Returns the number of days in the given month of the given year. The
         only supported value for @a cal currently is @c Gregorian.
     */
     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
 
     /**
         Returns the number of days in the given month of the given year. The
         only supported value for @a cal currently is @c Gregorian.

-
-        @beginWxPythonOnly
-        This method is named "GetNumberOfDaysInMonth" in wxPython.
-        @endWxPythonOnly

     */
     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
                                         Calendar cal = Gregorian);
     */
     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
                                         Calendar cal = Gregorian);


@@ -1386,10 +1501,10 @@ public:
     static time_t GetTimeNow();
 
     /**
     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.
     */
         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
 
     /**
         Returns the current time broken down. Note that this function returns a


@@ -1398,16 +1513,23 @@ public:
         your code might be used in a multi-threaded application, you really
         should use GetTmNow(struct tm *) instead.
     */
         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,
 
         @see GetMonthName()
     */
     static wxString GetWeekDayName(WeekDay weekday,

-                                    NameFlags flags = Name_Full);
+                                   NameFlags flags = Name_Full);

 
     /**
         Returns @true if DST was used in the given year (the current one by
 
     /**
         Returns @true if DST was used in the given year (the current one by


@@ -1439,9 +1561,8 @@ public:
         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
         @endcode
 
         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
         @endcode
 

-        @note This function is accurate up to seconds. UNow() should be used
-              for better precision, but it is less efficient and might not be
-              available on all platforms.
+        @note This function is accurate up to seconds. UNow() can be used if
+              better precision is required.

 
         @see Today()
     */
 
         @see Today()
     */


@@ -1451,9 +1572,6 @@ public:
         Sets the country to use by default. This setting influences the DST
         calculations, date formatting and other things.
 
         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);
         @see GetCountry()
     */
     static void SetCountry(Country country);


@@ -1472,18 +1590,20 @@ public:
 
     /**
         Returns the object corresponding to the midnight of the current day
 
     /**
         Returns the object corresponding to the midnight of the current day

-        (i.e. the same as Now(), but the time part is set to 0).
+        (i.e.\ the same as Now(), but the time part is set to 0).

 
         @see Now()
     */
     static wxDateTime Today();
 
     /**
 
         @see Now()
     */
     static wxDateTime Today();
 
     /**

-        Returns the object corresponding to the current time including the
-        milliseconds if a function to get time with such precision is available
-        on the current platform (supported under most Unices and Win32).
+        Returns the object corresponding to the current UTC time including the
+        milliseconds.

 
 

-        @see Now()
+        Notice that unlike Now(), this method creates a wxDateTime object
+        corresponding to UTC, not local, time.
+
+        @see Now(), wxGetUTCTimeMillis()

     */
     static wxDateTime UNow();
 };
     */
     static wxDateTime UNow();
 };


@@ -1496,6 +1616,10 @@ public:
 */
 const wxDateTime wxDefaultDateTime;
 
 */
 const wxDateTime wxDefaultDateTime;
 

+/*
+    wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime

 
 
 /**
 
 
 /**


@@ -1605,6 +1729,16 @@ public:
     */
     int GetMonths() const;
 
     */
     int GetMonths() const;
 

+    /**
+        Returns the combined number of months in this date span, counting both
+        years and months.
+
+        @see GetYears(), GetMonths()
+
+        @since 2.9.5
+    */
+    int GetTotalMonths() const;
+

     /**
         Returns the combined number of days in this date span, counting both
         weeks and days. This doesn't take months or years into account.
     /**
         Returns the combined number of days in this date span, counting both
         weeks and days. This doesn't take months or years into account.


@@ -1762,7 +1896,7 @@ public:
     /**
         Returns @true if this date span is different from the other one.
     */
     /**
         Returns @true if this date span is different from the other one.
     */

-    bool operator!=(const wxDateSpan&) const;
+    bool operator!=(const wxDateSpan& other) const;

 
     /**
         Returns @true if this date span is equal to the other one. Two date
 
     /**
         Returns @true if this date span is equal to the other one. Two date


@@ -1770,7 +1904,7 @@ public:
         years and months and the same total number of days (counting both days
         and weeks).
     */
         years and months and the same total number of days (counting both days
         and weeks).
     */

-    bool operator==(const wxDateSpan&) const;
+    bool operator==(const wxDateSpan& other) const;

 };
 
 
 };
 
 


@@ -1819,12 +1953,12 @@ public:
     /**
         Returns the timespan for one day.
     */
     /**
         Returns the timespan for one day.
     */

-    static wxTimespan Day();
+    static wxTimeSpan Day();

 
     /**
         Returns the timespan for the given number of days.
     */
 
     /**
         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
 
     /**
         Returns the string containing the formatted representation of the time


@@ -1852,7 +1986,7 @@ public:
         specifier of larger unit, only the rest part is taken, otherwise the
         full value is used.
     */
         specifier of larger unit, only the rest part is taken, otherwise the
         full value is used.
     */

-    wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
+    wxString Format(const wxString& format = wxDefaultTimeSpanFormat) const;

 
     /**
         Returns the difference in number of days.
 
     /**
         Returns the difference in number of days.


@@ -1892,12 +2026,12 @@ public:
     /**
         Returns the timespan for one hour.
     */
     /**
         Returns the timespan for one hour.
     */

-    static wxTimespan Hour();
+    static wxTimeSpan Hour();

 
     /**
         Returns the timespan for the given number of hours.
     */
 
     /**
         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.
 
     /**
         Returns @true if two timespans are equal.


@@ -1905,7 +2039,7 @@ public:
     bool IsEqualTo(const wxTimeSpan& ts) const;
 
     /**
     bool IsEqualTo(const wxTimeSpan& ts) const;
 
     /**

-        Compares two timespans: works with the absolute values, i.e. -2 hours
+        Compares two timespans: works with the absolute values, i.e.\ -2 hours

         is longer than 1 hour. Also, it will return @false if the timespans are
         equal in absolute value.
     */
         is longer than 1 hour. Also, it will return @false if the timespans are
         equal in absolute value.
     */


@@ -1927,7 +2061,7 @@ public:
     bool IsPositive() const;
 
     /**
     bool IsPositive() const;
 
     /**

-        Compares two timespans: works with the absolute values, i.e. 1 hour is
+        Compares two timespans: works with the absolute values, i.e.\ 1 hour is

         shorter than -2 hours. Also, it will return @false if the timespans are
         equal in absolute value.
     */
         shorter than -2 hours. Also, it will return @false if the timespans are
         equal in absolute value.
     */


@@ -1936,22 +2070,22 @@ public:
     /**
         Returns the timespan for one millisecond.
     */
     /**
         Returns the timespan for one millisecond.
     */

-    static wxTimespan Millisecond();
+    static wxTimeSpan Millisecond();

 
     /**
         Returns the timespan for the given number of milliseconds.
     */
 
     /**
         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.
     */
 
     /**
         Returns the timespan for one minute.
     */

-    static wxTimespan Minute();
+    static wxTimeSpan Minute();

 
     /**
         Returns the timespan for the given number of minutes.
     */
 
     /**
         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.
 
     /**
         Returns the product of this time span by @a n.


@@ -1983,12 +2117,12 @@ public:
     /**
         Returns the timespan for one second.
     */
     /**
         Returns the timespan for one second.
     */

-    static wxTimespan Second();
+    static wxTimeSpan Second();

 
     /**
         Returns the timespan for the given number of seconds.
     */
 
     /**
         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.
 
     /**
         Returns the difference of two time spans.


@@ -2005,12 +2139,12 @@ public:
     /**
         Returns the timespan for one week.
     */
     /**
         Returns the timespan for one week.
     */

-    static wxTimespan Week();
+    static wxTimeSpan Week();

 
     /**
         Returns the timespan for the given number of weeks.
     */
 
     /**
         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.
 
     /**
         Adds the given wxTimeSpan to this wxTimeSpan and returns the result.


@@ -2046,7 +2180,7 @@ public:
     @todo Write wxDateTimeHolidayAuthority documentation.
 
     @library{wxbase}
     @todo Write wxDateTimeHolidayAuthority documentation.
 
     @library{wxbase}

-    @category{misc}
+    @category{data}

 */
 class wxDateTimeHolidayAuthority
 {
 */
 class wxDateTimeHolidayAuthority
 {