]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/datetime.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / datetime.h
index 70cf1c5a8998914e0223c3f85db82204b429b634..f7f1906921470b04090aa747cf48beef9c0d02a6 100644 (file)
 // Name:        datetime.h
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxDateTime
 
-    wxDateTime class represents an absolute moment in the time.
+    wxDateTime class represents an absolute moment in time.
 
     The type @c wxDateTime_t is typedefed as <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.
+
+    The conversions from text are more interesting, as there are much more
+    possibilities to care about. The simplest cases can be taken care of with
+    ParseFormat() which can parse any date in the given (rigid) format.
+    ParseRfc822Date() is another function for parsing dates in predefined
+    format -- the one of RFC 822 which (still...) defines the format of email
+    messages on the Internet. This format cannot be described with
+    @c strptime(3)-like format strings used by Format(), hence the need for a
+    separate function.
+
+    But the most interesting functions are ParseTime(), ParseDate() and
+    ParseDateTime(). They try to parse the date and time (or only one of them)
+    in 'free' format, i.e. allow them to be specified in any of possible ways.
+    These functions will usually be used to parse the (interactive) user input
+    which is not bound to be in any predefined format. As an example,
+    ParseDate() can parse the strings such as "tomorrow", "March first" and
+    even "next Sunday".
+
+    Finally notice that each of the parsing functions is available in several
+    overloads: if the input string is a narrow (@c char *) string, then a
+    narrow pointer is returned. If the input string is a wide string, a wide
+    char pointer is returned. Finally, if the input parameter is a wxString, a
+    narrow char pointer is also returned for backwards compatibility but there
+    is also an additional argument of wxString::const_iterator type in which,
+    if it is not @NULL, an iterator pointing to the end of the scanned string
+    part is returned.
+
+
+    @library{wxbase}
+    @category{data}
+
+    @stdobjects
+    - ::wxDefaultDateTime
 
-    All the following constants are defined inside wxDateTime class (i.e., to
-    refer to them you should prepend their names with "wxDateTime::").
+    @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
+*/
+class wxDateTime
+{
+public:
+    /**
+        A small unsigned integer type for storing things like minutes,
+        seconds &c. It should be at least short (i.e. not char) to contain
+        the number of milliseconds - it may also be 'int' because there is
+        no size penalty associated with it in our code, we don't store any
+        data in this format.
+    */
+    typedef unsigned short wxDateTime_t;
 
-    Time zone symbolic names:
 
-    @code
+    /**
+        Time zone symbolic names.
+    */
     enum TZ
     {
-        // the time in the current time zone
+        /// the time in the current time zone
         Local,
 
-        // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
-        // consequent numbers, so writing something like `GMT0 + offset' is
-        // safe if abs(offset) <= 12
+        //@{
+        /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be
+        /// consequent numbers, so writing something like `GMT0 + offset' is
+        /// safe if abs(offset) <= 12
 
         // underscore stands for minus
         GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
         GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
         // Note that GMT12 and GMT_12 are not the same: there is a difference
         // of exactly one day between them
+        //@}
 
         // some symbolic names for TZ
 
         // Europe
-        WET = GMT0,         // Western Europe Time
-        WEST = GMT1,        // Western Europe Summer Time
-        CET = GMT1,         // Central Europe Time
-        CEST = GMT2,        // Central Europe Summer Time
-        EET = GMT2,         // Eastern Europe Time
-        EEST = GMT3,        // Eastern Europe Summer Time
-        MSK = GMT3,         // Moscow Time
-        MSD = GMT4,         // Moscow Summer Time
+        WET = GMT0,         //!< Western Europe Time
+        WEST = GMT1,        //!< Western Europe Summer Time
+        CET = GMT1,         //!< Central Europe Time
+        CEST = GMT2,        //!< Central Europe Summer Time
+        EET = GMT2,         //!< Eastern Europe Time
+        EEST = GMT3,        //!< Eastern Europe Summer Time
+        MSK = GMT3,         //!< Moscow Time
+        MSD = GMT4,         //!< Moscow Summer Time
 
         // US and Canada
-        AST = GMT_4,        // Atlantic Standard Time
-        ADT = GMT_3,        // Atlantic Daylight Time
-        EST = GMT_5,        // Eastern Standard Time
-        EDT = GMT_4,        // Eastern Daylight Saving Time
-        CST = GMT_6,        // Central Standard Time
-        CDT = GMT_5,        // Central Daylight Saving Time
-        MST = GMT_7,        // Mountain Standard Time
-        MDT = GMT_6,        // Mountain Daylight Saving Time
-        PST = GMT_8,        // Pacific Standard Time
-        PDT = GMT_7,        // Pacific Daylight Saving Time
-        HST = GMT_10,       // Hawaiian Standard Time
-        AKST = GMT_9,       // Alaska Standard Time
-        AKDT = GMT_8,       // Alaska Daylight Saving Time
+        AST = GMT_4,        //!< Atlantic Standard Time
+        ADT = GMT_3,        //!< Atlantic Daylight Time
+        EST = GMT_5,        //!< Eastern Standard Time
+        EDT = GMT_4,        //!< Eastern Daylight Saving Time
+        CST = GMT_6,        //!< Central Standard Time
+        CDT = GMT_5,        //!< Central Daylight Saving Time
+        MST = GMT_7,        //!< Mountain Standard Time
+        MDT = GMT_6,        //!< Mountain Daylight Saving Time
+        PST = GMT_8,        //!< Pacific Standard Time
+        PDT = GMT_7,        //!< Pacific Daylight Saving Time
+        HST = GMT_10,       //!< Hawaiian Standard Time
+        AKST = GMT_9,       //!< Alaska Standard Time
+        AKDT = GMT_8,       //!< Alaska Daylight Saving Time
 
         // Australia
 
-        A_WST = GMT8,       // Western Standard Time
-        A_CST = GMT13 + 1,  // Central Standard Time (+9.5)
-        A_EST = GMT10,      // Eastern Standard Time
-        A_ESST = GMT11,     // Eastern Summer Time
+        A_WST = GMT8,       //!< Western Standard Time
+        A_CST = GMT13 + 1,  //!< Central Standard Time (+9.5)
+        A_EST = GMT10,      //!< Eastern Standard Time
+        A_ESST = GMT11,     //!< Eastern Summer Time
 
         // New Zealand
-        NZST = GMT12,       // Standard Time
-        NZDT = GMT13,       // Daylight Saving Time
+        NZST = GMT12,       //!< Standard Time
+        NZDT = GMT13,       //!< Daylight Saving Time
 
-        // Universal Coordinated Time = the new and politically correct name
-        // for GMT
+        /// Universal Coordinated Time = the new and politically correct name
+        /// for GMT.
         UTC = GMT0
     };
-    @endcode
-
-    Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
-    Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
-
-    Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
-    in @c wxDateTime::WeekDay enum.
-
-    Finally, Inv_Year is defined to be an invalid value for year parameter.
-
-    GetMonthName() and GetWeekDayName() functions use the following flags:
-
-    @code
-    enum NameFlags
-    {
-        Name_Full = 0x01,       // return full name
-        Name_Abbr = 0x02        // return abbreviated name
-    };
-    @endcode
-
-    Several functions accept an extra parameter specifying the calendar to use
-    (although most of them only support now the Gregorian calendar). This
-    parameters is one of the following values:
 
-    @code
+    /**
+        Several functions accept an extra parameter specifying the calendar to use
+        (although most of them only support now the Gregorian calendar). This
+        parameters is one of the following values.
+    */
     enum Calendar
     {
-        Gregorian,  // calendar currently in use in Western countries
-        Julian      // calendar in use since -45 until the 1582 (or later)
+        Gregorian,  ///< calendar currently in use in Western countries
+        Julian      ///< calendar in use since -45 until the 1582 (or later)
     };
-    @endcode
-
-    Date calculations often depend on the country and wxDateTime allows to set
-    the country whose conventions should be used using SetCountry(). It takes
-    one of the following values as parameter:
 
-    @code
+    /**
+        Date calculations often depend on the country and wxDateTime allows to set
+        the country whose conventions should be used using SetCountry(). It takes
+        one of the following values as parameter.
+    */
     enum Country
     {
-        Country_Unknown, // no special information for this country
-        Country_Default, // set the default country with SetCountry() method
-                         // or use the default country with any other
+        Country_Unknown, ///< no special information for this country
+        Country_Default, ///< set the default country with SetCountry() method
+                         ///< or use the default country with any other
 
         Country_WesternEurope_Start,
         Country_EEC = Country_WesternEurope_Start,
 
         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
-        as constructors can not return an error code.
+        as constructors cannot return an error code.
     */
     //@{
 
@@ -241,45 +309,33 @@ public:
         object later.
     */
     wxDateTime();
+
+    /**
+       Copy constructor.
+    */
+    wxDateTime(const wxDateTime& date);
+    
     /**
         Same as Set().
-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromTimeT" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime(time_t timet);
     /**
         Same as Set().
-
-        @beginWxPythonOnly Unsupported. @endWxPythonOnly
     */
     wxDateTime(const struct tm& tm);
     /**
         Same as Set().
-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromJDN" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime(double jdn);
     /**
         Same as Set().
-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromHMS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0,
                wxDateTime_t second = 0, wxDateTime_t millisec = 0);
     /**
         Same as Set().
-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromDMY" in wxPython.
-        @endWxPythonOnly
     */
-    wxDateTime(wxDateTime_t day, Month month = Inv_Month,
+    wxDateTime(wxDateTime_t day, Month month,
                int year = Inv_Year, wxDateTime_t hour = 0,
                wxDateTime_t minute = 0, wxDateTime_t second = 0,
                wxDateTime_t millisec = 0);
@@ -291,6 +347,7 @@ public:
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only
+        @onlyfor{wxmsw}
     */
     wxDateTime(const struct _SYSTEMTIME& st);
 
@@ -302,20 +359,24 @@ public:
 
     /**
         Constructs the object from @a timet value holding the number of seconds
-        since Jan 1, 1970.
+        since Jan 1, 1970 UTC.
 
-        @beginWxPythonOnly
-        This method is named "SetTimeT" in wxPython.
-        @endWxPythonOnly
+        If @a timet is invalid, i.e. @code (time_t)-1 @endcode, wxDateTime
+        becomes invalid too, i.e. its IsValid() will return @false.
     */
     wxDateTime& Set(time_t timet);
     /**
         Sets the date and time from the broken down representation in the
         standard @a tm structure.
-
-        @beginWxPythonOnly Unsupported. @endWxPythonOnly
     */
     wxDateTime& Set(const struct tm& tm);
+
+    /**
+       Sets the date and time from the broken down representation in the
+       @a wxDateTime::Tm structure.
+    */
+    wxDateTime& Set(const Tm& tm);
+    
     /**
         Sets the date from the so-called Julian Day Number.
 
@@ -323,26 +384,32 @@ public:
         particular instant is the fractional number of days since 12 hours
         Universal Coordinated Time (Greenwich mean noon) on January 1 of the
         year -4712 in the Julian proleptic calendar.
-
-        @beginWxPythonOnly
-        This method is named "SetJDN" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime& Set(double jdn);
     /**
         Sets the date to be equal to Today() and the time from supplied
         parameters.
 
-        @beginWxPythonOnly
-        This method is named "SetHMS" in wxPython.
-        @endWxPythonOnly
+        See the full Set() overload for the remarks about DST.
     */
     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.
+
+        If the function parameters are invalid, e.g. @a month is February and
+        @a day is 30, the object is left in an invalid state, i.e. IsValid()
+        method will return @false.
+
+        If the specified time moment is invalid due to DST, i.e. it falls into
+        the "missing" hour on the date on which the DST starts, a valid
+        wxDateTime object is still constructed but its hour component is moved
+        forward to ensure that it corresponds to a valid moment in the local
+        time zone. For example, in the CET time zone the DST started on
+        2013-03-31T02:00:00 in 2013 and so setting the object to 2:30 at this
+        date actually sets the hour to 3, and not 2.
     */
-    wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
+    wxDateTime& Set(wxDateTime_t day, Month month,
                     int year = Inv_Year, wxDateTime_t hour = 0,
                     wxDateTime_t minute = 0, wxDateTime_t second = 0,
                     wxDateTime_t millisec = 0);
@@ -418,7 +485,7 @@ public:
     /**
         Returns the date and time in DOS format.
     */
-    long unsigned int GetAsDOS() const;
+    unsigned long GetAsDOS() const;
 
     /**
         Initialize using the Windows SYSTEMTIME structure.
@@ -426,6 +493,7 @@ public:
             Input, Windows SYSTEMTIME reference
         @since 2.9.0
         @remarks MSW only
+        @onlyfor{wxmsw}
     */
     wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
 
@@ -435,6 +503,7 @@ public:
             Output, pointer to Windows SYSTEMTIME
         @since 2.9.0
         @remarks MSW only
+        @onlyfor{wxmsw}
     */
     void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
 
@@ -456,28 +525,28 @@ public:
     /**
         Returns the day in the given timezone (local one by default).
     */
-    short unsigned int GetDay(const TimeZone& tz = Local) const;
+    unsigned short GetDay(const TimeZone& tz = Local) const;
 
     /**
         Returns the day of the year (in 1-366 range) in the given timezone
         (local one by default).
     */
-    short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
+    unsigned short GetDayOfYear(const TimeZone& tz = Local) const;
 
     /**
         Returns the hour in the given timezone (local one by default).
     */
-    short unsigned int GetHour(const TimeZone& tz = Local) const;
+    unsigned short GetHour(const TimeZone& tz = Local) const;
 
     /**
         Returns the milliseconds in the given timezone (local one by default).
     */
-    short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
+    unsigned short GetMillisecond(const TimeZone& tz = Local) const;
 
     /**
         Returns the minute in the given timezone (local one by default).
     */
-    short unsigned int GetMinute(const TimeZone& tz = Local) const;
+    unsigned short GetMinute(const TimeZone& tz = Local) const;
 
     /**
         Returns the month in the given timezone (local one by default).
@@ -487,11 +556,13 @@ public:
     /**
         Returns the seconds in the given timezone (local one by default).
     */
-    short unsigned int GetSecond(const TimeZone& tz = Local) const;
+    unsigned short GetSecond(const TimeZone& tz = Local) const;
 
     /**
-        Returns the number of seconds since Jan 1, 1970. An assert failure will
-        occur if the date is not in the range covered by @c time_t type.
+        Returns the number of seconds since Jan 1, 1970 UTC.
+
+        An assert failure will occur if the date is not in the range covered by
+        @c time_t type, use GetValue() if you work with dates outside of it.
     */
     time_t GetTicks() const;
 
@@ -509,8 +580,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 +594,9 @@ public:
         year. Accordingly, the week number will always be in 1-53 range (52 for
         non-leap years).
 
-        The function depends on the @ref datetime_constants "week start"
-        convention specified by the @a flags argument but its results for
-        @c Sunday_First are not well-defined as the ISO definition quoted above
-        applies to the weeks starting on Monday only.
+        The function depends on the week start convention specified by the @a flags
+        argument but its results for @c Sunday_First are not well-defined as the
+        ISO definition quoted above applies to the weeks starting on Monday only.
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;
@@ -537,13 +606,6 @@ public:
     */
     int GetYear(const TimeZone& tz = Local) const;
 
-    /**
-        Returns @true if the given date is later than the date of adoption of
-        the Gregorian calendar in the given country (and hence the Gregorian
-        calendar calculations make sense for it).
-    */
-    bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
-
     /**
         Returns @true if the object represents a valid time moment.
     */
@@ -578,7 +640,7 @@ public:
 
     /**
         Returns @true if the date is equal to another one up to the given time
-        interval, i.e. if the absolute difference between the two dates is less
+        interval, i.e.\ if the absolute difference between the two dates is less
         than this interval.
     */
     bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
@@ -637,67 +699,35 @@ public:
 
     /**
         Adds the given date span to this object.
-
-        @beginWxPythonOnly
-        This method is named "AddDS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime Add(const wxDateSpan& diff) const;
     /**
         Adds the given date span to this object.
-
-        @beginWxPythonOnly
-        This method is named "AddDS" in wxPython.
-        @endWxPythonOnly
     */
-    wxDateTime Add(const wxDateSpan& diff);
+    wxDateTime& Add(const wxDateSpan& diff);
     /**
         Adds the given time span to this object.
-
-        @beginWxPythonOnly
-        This method is named "AddTS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime Add(const wxTimeSpan& diff) const;
     /**
         Adds the given time span to this object.
-
-        @beginWxPythonOnly
-        This method is named "AddTS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime& Add(const wxTimeSpan& diff);
 
     /**
         Subtracts the given time span from this object.
-
-        @beginWxPythonOnly
-        This method is named "SubtractTS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime Subtract(const wxTimeSpan& diff) const;
     /**
         Subtracts the given time span from this object.
-
-        @beginWxPythonOnly
-        This method is named "SubtractTS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime& Subtract(const wxTimeSpan& diff);
     /**
         Subtracts the given date span from this object.
-
-        @beginWxPythonOnly
-        This method is named "SubtractDS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime Subtract(const wxDateSpan& diff) const;
     /**
         Subtracts the given date span from this object.
-
-        @beginWxPythonOnly
-        This method is named "SubtractDS" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime& Subtract(const wxDateSpan& diff);
     /**
@@ -705,23 +735,53 @@ public:
         them as a wxTimeSpan.
     */
     wxTimeSpan Subtract(const wxDateTime& dt) const;
+    /**
+       Returns the difference between this object and @a dt as a wxDateSpan.
+
+       This method allows to find the number of entire years, months, weeks and
+       days between @a dt and this date.
+
+       @since 2.9.5
+    */
+    wxDateSpan DiffAsDateSpan(const wxDateTime& dt) const;
 
     /**
         Adds the given date span to this object.
     */
-    wxDateTime operator+=(const wxDateSpan& diff);
+    wxDateTime& operator+=(const wxDateSpan& diff);
+    /**
+        Adds the given date span to this object.
+    */
+    wxDateTime operator+(const wxDateSpan& ds) const;
     /**
         Subtracts the given date span from this object.
     */
     wxDateTime& operator-=(const wxDateSpan& diff);
+    /**
+        Subtracts the given date span from this object.
+    */
+    wxDateTime operator-(const wxDateSpan& ds) const;
     /**
         Adds the given time span to this object.
     */
     wxDateTime& operator+=(const wxTimeSpan& diff);
+    /**
+        Adds the given time span to this object.
+    */
+    wxDateTime operator+(const wxTimeSpan& ts) const;
     /**
         Subtracts the given time span from this object.
     */
     wxDateTime& operator-=(const wxTimeSpan& diff);
+    /**
+        Subtracts the given time span from this object.
+    */
+    wxDateTime operator-(const wxTimeSpan& ts) const;
+    /**
+        Subtracts another date from this one and returns the difference between
+        them as a wxTimeSpan.
+    */
+    wxTimeSpan operator-(const wxDateTime& dt2) const;
 
     //@}
 
@@ -736,8 +796,8 @@ public:
 
     /**
         This function does the same as the standard ANSI C @c strftime(3)
-        function. Please see its description for the meaning of @a format
-        parameter.
+        function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html).
+        Please see its description for the meaning of @a format parameter.
 
         It also accepts a few wxWidgets-specific extensions: you can optionally
         specify the width of the field to follow using @c printf(3)-like syntax
@@ -759,7 +819,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 +846,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);
-
-    /**
-        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.
+    bool ParseDate(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* ParseDateTime(const wxString& datetime,
-                              wxString::const_iterator* end = NULL);
     /**
         Parses the string @a datetime containing the date and time in free
-        format. This function tries as hard as it can to interpret the given
-        string as date and time. Unlike ParseRfc822Date(), it will accept
-        anything that may be accepted and will only reject strings which can
-        not be parsed in any way at all.
+        format.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
-    */
-    const char* ParseDateTime(const char* datetime);
-    /**
-        Parses the string @a datetime containing the date and time in free
-        format. This function tries as hard as it can to interpret the given
-        string as date and time. Unlike ParseRfc822Date(), it will accept
-        anything that may be accepted and will only reject strings which can
-        not be parsed in any way at all.
+        This function tries as hard as it can to interpret the given string as
+        date and time. Unlike ParseRfc822Date(), it will accept anything that
+        may be accepted and will only reject strings which cannot be parsed in
+        any way at all. Notice that the function will fail if either date or
+        time part is present but not both, use ParseDate() or ParseTime() to
+        parse strings containing just the date or time component.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const wchar_t* ParseDateTime(const wchar_t* datetime);
+    bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);
 
     /**
         This function parses the string @a date according to the given
@@ -867,63 +893,53 @@ public:
         @a dateDef. If it is not specified, Today() is used as the default
         date.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
-    */
-    const char* ParseFormat(const wxString& date,
-                             const wxString& format = wxDefaultDateTimeFormat,
-                             const wxDateTime& dateDef = wxDefaultDateTime,
-                             wxString::const_iterator* end = NULL);
-    /**
-        This function parses the string @a date according to the given
-        @e format. The system @c strptime(3) function is used whenever
-        available, but even if it is not, this function is still implemented,
-        although support for locale-dependent format specifiers such as
-        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
-        as @c "%z" and @c "%Z" are not implemented. This function does handle
-        the month and weekday names in the current locale on all platforms,
-        however.
-
-        Please see the description of the ANSI C function @c strftime(3) for
-        the syntax of the format string.
+        Example of using this function:
+        @code
+            wxDateTime dt;
+            wxString str = "...";
+            wxString::const_iterator end;
+            if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) )
+                ... parsing failed ...
+            else if ( end == str.end() )
+                ... entire string parsed ...
+            else
+                ... wxString(end, str.end()) left over ...
+        @endcode
 
-        The @a dateDef parameter is used to fill in the fields which could not
-        be determined from the format string. For example, if the format is
-        @c "%d" (the day of the month), the month and the year are taken from
-        @a dateDef. If it is not specified, Today() is used as the default
-        date.
+        @param date
+            The string to be parsed.
+        @param format
+            strptime()-like format string.
+        @param dateDef
+            Used to fill in the date components not specified in the @a date
+            string.
+        @param end
+            Will be filled with the iterator pointing to the location where the
+            parsing stopped if the function returns @true. If the entire string
+            was consumed, it is set to @c date.end(). Notice that this argument
+            must be non-@NULL.
+        @return
+            @true if at least part of the string was parsed successfully,
+            @false otherwise.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+        @see Format()
     */
-    const char* ParseFormat(const char* date,
-                              const wxString& format = wxDefaultDateTimeFormat,
-                              const wxDateTime& dateDef = wxDefaultDateTime);
-    /**
-        This function parses the string @a date according to the given
-        @e format. The system @c strptime(3) function is used whenever
-        available, but even if it is not, this function is still implemented,
-        although support for locale-dependent format specifiers such as
-        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
-        as @c "%z" and @c "%Z" are not implemented. This function does handle
-        the month and weekday names in the current locale on all platforms,
-        however.
-
-        Please see the description of the ANSI C function @c strftime(3) for
-        the syntax of the format string.
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     const wxDateTime& dateDef,
+                     wxString::const_iterator *end);
 
-        The @a dateDef parameter is used to fill in the fields which could not
-        be determined from the format string. For example, if the format is
-        @c "%d" (the day of the month), the month and the year are taken from
-        @a dateDef. If it is not specified, Today() is used as the default
-        date.
+    /**
+        @overload
+    */
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     wxString::const_iterator *end);
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
-    const wchar_t* ParseFormat(const wchar_t* date,
-                                 const wxString& format = wxDefaultDateTimeFormat,
-                                 const wxDateTime& dateDef = wxDefaultDateTime);
+    bool ParseFormat(const wxString& date, wxString::const_iterator *end);
 
     /**
         This function parses the string containing the date and time in ISO
@@ -969,73 +985,20 @@ public:
         string which is not RFC 822 compliant. If you need to parse date
         formatted in more free ways, you should use ParseDateTime() or
         ParseDate() instead.
-    */
-    const char* ParseRfc822Date(const wxString& date,
-                                  wxString::const_iterator* end = NULL);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
-
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
-    */
-    const char* ParseRfc822Date(const char* date);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
 
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
-
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const wchar_t* ParseRfc822Date(const wchar_t* date);
+    bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
 
     /**
         This functions is like ParseDateTime(), but only allows the time to be
         specified in the input string.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const char* ParseTime(const wxString& time,
-                           wxString::const_iterator* end = NULL);
-    /**
-        This functions is like ParseDateTime(), but only allows the time to be
-        specified in the input string.
-
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
-    */
-    const char* ParseTime(const char* time);
-    /**
-        This functions is like ParseDateTime(), but only allows the time to be
-        specified in the input string.
-
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
-    */
-    const wchar_t* ParseTime(const wchar_t* time);
+    bool ParseTime(const wxString& time, wxString::const_iterator *end);
 
     //@}
 
@@ -1158,7 +1121,7 @@ public:
                                       WeekFlags flags = Monday_First);
 
     /**
-        Sets the date to the day number @a yday in the same year (i.e., unlike
+        Sets the date to the day number @a yday in the same year (i.e.\ unlike
         the other functions, this one does not use the current year). The day
         number should be in the range 1-366 for the leap years and 1-365 for
         the other ones.
@@ -1283,7 +1246,7 @@ public:
 
 
     /**
-        Converts the year in absolute notation (i.e. a number which can be
+        Converts the year in absolute notation (i.e.\ a number which can be
         negative, positive or zero) to the year in BC/AD notation. For the
         positive years, nothing is done, but the year 0 is year 1 BC and so for
         other years there is a difference of 1.
@@ -1325,7 +1288,7 @@ public:
                                  Country country = Country_Default);
 
     /**
-        Get the current century, i.e. first two digits of the year, in given
+        Get the current century, i.e.\ first two digits of the year, in given
         calendar (only Gregorian is currently supported).
     */
     static int GetCentury(int year);
@@ -1351,8 +1314,53 @@ public:
     static int GetCurrentYear(Calendar cal = Gregorian);
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr name of
-        the given month.
+        Return the standard English name of the given month.
+
+        This function always returns "January" or "Jan" for January, use
+        GetMonthName() to retrieve the name of the month in the users current
+        locale.
+
+        @param month
+            One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
+
+        @see GetEnglishWeekDayName()
+
+        @since 2.9.0
+     */
+    static wxString GetEnglishMonthName(Month month,
+                                        NameFlags flags = Name_Full);
+
+    /**
+        Return the standard English name of the given week day.
+
+        This function always returns "Monday" or "Mon" for Monday, use
+        GetWeekDayName() to retrieve the name of the month in the users current
+        locale.
+
+        @param weekday
+            One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
+
+        @see GetEnglishMonthName()
+
+        @since 2.9.0
+     */
+    static wxString GetEnglishWeekDayName(WeekDay weekday,
+                                          NameFlags flags = Name_Full);
+
+    /**
+        Gets the full (default) or abbreviated name of the given month.
+
+        This function returns the name in the current locale, use
+        GetEnglishMonthName() to get the untranslated name if necessary.
+
+        @param month
+            One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
 
         @see GetWeekDayName()
     */
@@ -1361,20 +1369,12 @@ public:
     /**
         Returns the number of days in the given year. The only supported value
         for @a cal currently is @c Gregorian.
-
-        @beginWxPythonOnly
-        This method is named "GetNumberOfDaysInYear" in wxPython.
-        @endWxPythonOnly
     */
     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
 
     /**
         Returns the number of days in the given month of the given year. The
         only supported value for @a cal currently is @c Gregorian.
-
-        @beginWxPythonOnly
-        This method is named "GetNumberOfDaysInMonth" in wxPython.
-        @endWxPythonOnly
     */
     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
                                         Calendar cal = Gregorian);
@@ -1385,7 +1385,7 @@ public:
     static time_t GetTimeNow();
 
     /**
-        Returns the current time broken down using the buffer whose adress is
+        Returns the current time broken down using the buffer whose address is
         passed to the function with @a tm to store the result.
     */
     static tm* GetTmNow(struct tm *tm);
@@ -1400,13 +1400,20 @@ public:
     static tm* GetTmNow();
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
-        the given week day.
+        Gets the full (default) or abbreviated name of the given week day.
+
+        This function returns the name in the current locale, use
+        GetEnglishWeekDayName() to get the untranslated name if necessary.
+
+        @param weekday
+            One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
 
         @see GetMonthName()
     */
     static wxString GetWeekDayName(WeekDay weekday,
-                                    NameFlags flags = Name_Full);
+                                   NameFlags flags = Name_Full);
 
     /**
         Returns @true if DST was used in the given year (the current one by
@@ -1438,9 +1445,8 @@ public:
         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
         @endcode
 
-        @note This function is accurate up to seconds. UNow() should be used
-              for better precision, but it is less efficient and might not be
-              available on all platforms.
+        @note This function is accurate up to seconds. UNow() can be used if
+              better precision is required.
 
         @see Today()
     */
@@ -1450,9 +1456,6 @@ public:
         Sets the country to use by default. This setting influences the DST
         calculations, date formatting and other things.
 
-        The possible values for @a country parameter are enumerated in the
-        @ref datetime_constants section.
-
         @see GetCountry()
     */
     static void SetCountry(Country country);
@@ -1471,18 +1474,20 @@ public:
 
     /**
         Returns the object corresponding to the midnight of the current day
-        (i.e. the same as Now(), but the time part is set to 0).
+        (i.e.\ the same as Now(), but the time part is set to 0).
 
         @see Now()
     */
     static wxDateTime Today();
 
     /**
-        Returns the object corresponding to the current time including the
-        milliseconds if a function to get time with such precision is available
-        on the current platform (supported under most Unices and Win32).
+        Returns the object corresponding to the current UTC time including the
+        milliseconds.
 
-        @see Now()
+        Notice that unlike Now(), this method creates a wxDateTime object
+        corresponding to UTC, not local, time.
+
+        @see Now(), wxGetUTCTimeMillis()
     */
     static wxDateTime UNow();
 };
@@ -1495,6 +1500,10 @@ public:
 */
 const wxDateTime wxDefaultDateTime;
 
+/*
+    wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime
 
 
 /**
@@ -1604,6 +1613,16 @@ public:
     */
     int GetMonths() const;
 
+    /**
+        Returns the combined number of months in this date span, counting both
+        years and months.
+
+        @see GetYears(), GetMonths()
+
+        @since 2.9.5
+    */
+    int GetTotalMonths() const;
+
     /**
         Returns the combined number of days in this date span, counting both
         weeks and days. This doesn't take months or years into account.
@@ -1761,7 +1780,7 @@ public:
     /**
         Returns @true if this date span is different from the other one.
     */
-    bool operator!=(const wxDateSpan&) const;
+    bool operator!=(const wxDateSpan& other) const;
 
     /**
         Returns @true if this date span is equal to the other one. Two date
@@ -1769,7 +1788,7 @@ public:
         years and months and the same total number of days (counting both days
         and weeks).
     */
-    bool operator==(const wxDateSpan&) const;
+    bool operator==(const wxDateSpan& other) const;
 };
 
 
@@ -1851,7 +1870,7 @@ public:
         specifier of larger unit, only the rest part is taken, otherwise the
         full value is used.
     */
-    wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
+    wxString Format(const wxString& format = wxDefaultTimeSpanFormat) const;
 
     /**
         Returns the difference in number of days.
@@ -1904,7 +1923,7 @@ public:
     bool IsEqualTo(const wxTimeSpan& ts) const;
 
     /**
-        Compares two timespans: works with the absolute values, i.e. -2 hours
+        Compares two timespans: works with the absolute values, i.e.\ -2 hours
         is longer than 1 hour. Also, it will return @false if the timespans are
         equal in absolute value.
     */
@@ -1926,7 +1945,7 @@ public:
     bool IsPositive() const;
 
     /**
-        Compares two timespans: works with the absolute values, i.e. 1 hour is
+        Compares two timespans: works with the absolute values, i.e.\ 1 hour is
         shorter than -2 hours. Also, it will return @false if the timespans are
         equal in absolute value.
     */