]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/datetime.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / datetime.h
index 02f28dc731154568f04210371b3de2f106d3dd83..c181b9c75ea17db7bea124be54d529f3929b4264 100644 (file)
@@ -2,14 +2,13 @@
 // Name:        datetime.h
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // Name:        datetime.h
 // 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
 
     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
     parameter, it is currently ignored as only the Gregorian calendar is
     supported. Future versions will support other calendars.
 
     parameter, it is currently ignored as only the Gregorian calendar is
     supported. Future versions will support other calendars.
 
-    @beginWxPythonOnly
-    These methods are standalone functions named
-    "wxDateTime_<StaticMethodName>" in wxPython.
-    @endWxPythonOnly
-
-
     @section datetime_formatting Date Formatting and Parsing
 
     The date formatting and parsing functions convert wxDateTime objects to and
     @section datetime_formatting Date Formatting and Parsing
 
     The date formatting and parsing functions convert wxDateTime objects to and
@@ -50,7 +43,7 @@
     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
     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
+    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.
 
     @c strptime(3)-like format strings used by Format(), hence the need for a
     separate function.
 
@@ -59,7 +52,7 @@
     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,
     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
+    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
     even "next Sunday".
 
     Finally notice that each of the parsing functions is available in several
@@ -102,7 +95,7 @@ public:
         Local,
 
         //@{
         Local,
 
         //@{
-        /// zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+        /// 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
 
         /// consequent numbers, so writing something like `GMT0 + offset' is
         /// safe if abs(offset) <= 12
 
@@ -233,7 +226,7 @@ public:
         in the functions whose result depends on it (GetWeekOfYear() and
         GetWeekOfMonth()).
 
         in the functions whose result depends on it (GetWeekOfYear() and
         GetWeekOfMonth()).
 
-        The desired behvaiour may be specified by giving one of the following
+        The desired behaviour may be specified by giving one of the following
         constants as argument to these functions.
     */
     enum WeekFlags
         constants as argument to these functions.
     */
     enum WeekFlags
@@ -244,13 +237,70 @@ public:
     };
 
 
     };
 
 
+    /**
+        Class representing a time zone.
+
+        The representation is simply the offset, in seconds, from UTC.
+     */
+    class WXDLLIMPEXP_BASE TimeZone
+    {
+    public:
+        /// Constructor for a named time zone.
+        TimeZone(TZ tz);
+
+        /// Constructor for the given offset in seconds.
+        TimeZone(long offset = 0);
+
+        /// Create a time zone with the given offset in seconds.
+        static TimeZone Make(long offset);
+
+        /// Return the offset of this time zone from UTC, in seconds.
+        long GetOffset() const;
+    };
+
+    /**
+        Contains broken down date-time representation.
+
+        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();
+    };
+
+
     /**
         @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.
     */
     //@{
 
     */
     //@{
 
@@ -259,45 +309,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(time_t timet);
     /**
         Same as Set().
     */
     wxDateTime(time_t timet);
     /**
         Same as Set().
-
-        @beginWxPythonOnly Unsupported. @endWxPythonOnly
     */
     wxDateTime(const struct tm& tm);
     /**
         Same as Set().
     */
     wxDateTime(const struct tm& tm);
     /**
         Same as Set().
-
-        @beginWxPythonOnly
-        This constructor is named "wxDateTimeFromJDN" in wxPython.
-        @endWxPythonOnly
     */
     wxDateTime(double jdn);
     /**
         Same as Set().
     */
     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().
     */
     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);
                int year = Inv_Year, wxDateTime_t hour = 0,
                wxDateTime_t minute = 0, wxDateTime_t second = 0,
                wxDateTime_t millisec = 0);
@@ -309,6 +347,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);
 
@@ -320,20 +359,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.
 
@@ -341,26 +384,18 @@ public:
         particular instant is the fractional number of days since 12 hours
         Universal Coordinated Time (Greenwich mean noon) on January 1 of the
         year -4712 in the Julian proleptic calendar.
         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);
@@ -436,7 +471,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.
@@ -444,6 +479,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);
 
@@ -453,6 +489,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;
 
@@ -474,28 +511,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).
@@ -505,11 +542,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;
 
@@ -553,13 +592,6 @@ public:
     */
     int GetYear(const TimeZone& tz = Local) const;
 
     */
     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.
     */
     /**
         Returns @true if the object represents a valid time moment.
     */
@@ -594,7 +626,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;
@@ -653,67 +685,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);
     /**
@@ -721,23 +721,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.
     */
 
     /**
         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& 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;
 
     //@}
 
 
     //@}
 
@@ -775,7 +805,7 @@ public:
         Returns the combined date-time representation in the ISO 8601 format
         @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
         the result exactly corresponding to the ISO standard, but it can also
         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()
@@ -802,49 +832,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.
+        It is thus less flexible then ParseDateTime(), but also has less
+        chances to misinterpret the user input.
 
 
-        @see Format()
-    */
-    const char* ParseDate(const wxString& date,
-                           wxString::const_iterator* end = NULL);
+        See ParseFormat() for the description of function parameters and return
+        value.
 
 
-    /**
-        @overload
-    */
-    const char* ParseDate(const char* date);
-
-    /**
-        @overload
+        @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);
+        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.
 
 
-    /**
-        @overload
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
     */
-    const char* ParseDateTime(const char* datetime);
-
-    /**
-        @overload
-    */
-    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
@@ -865,29 +879,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.
+        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
+
+        @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.
 
         @see Format()
     */
 
         @see Format()
     */
-    const char* ParseFormat(const wxString& date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime,
-                            wxString::const_iterator* end = NULL);
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     const wxDateTime& dateDef,
+                     wxString::const_iterator *end);
 
     /**
         @overload
     */
 
     /**
         @overload
     */
-    const char* ParseFormat(const char* date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime);
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     wxString::const_iterator *end);
 
     /**
         @overload
     */
 
     /**
         @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
@@ -933,39 +971,20 @@ public:
         string which is not RFC 822 compliant. If you need to parse date
         formatted in more free ways, you should use ParseDateTime() or
         ParseDate() instead.
         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);
 
 
-    /**
-        @overload
-    */
-    const char* ParseRfc822Date(const char* date);
-
-    /**
-        @overload
+        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.
 
 
     /**
         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);
-
-    /**
-        @overload
-    */
-    const char* ParseTime(const char* time);
-
-    /**
-        @overload
-    */
-    const wchar_t* ParseTime(const wchar_t* time);
+    bool ParseTime(const wxString& time, wxString::const_iterator *end);
 
     //@}
 
 
     //@}
 
@@ -1088,7 +1107,7 @@ public:
                                       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.
@@ -1213,7 +1232,7 @@ public:
 
 
     /**
 
 
     /**
-        Converts the year in absolute notation (i.e. a number which can be
+        Converts the year in absolute notation (i.e.\ a number which can be
         negative, positive or zero) to the year in BC/AD notation. For the
         positive years, nothing is done, but the year 0 is year 1 BC and so for
         other years there is a difference of 1.
         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.
@@ -1255,7 +1274,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);
@@ -1336,20 +1355,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);
@@ -1360,7 +1371,7 @@ 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.
     */
     static tm* GetTmNow(struct tm *tm);
         passed to the function with @a tm to store the result.
     */
     static tm* GetTmNow(struct tm *tm);
@@ -1420,9 +1431,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()
     */
@@ -1450,18 +1460,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();
 };
@@ -1474,6 +1486,10 @@ public:
 */
 const wxDateTime wxDefaultDateTime;
 
 */
 const wxDateTime wxDefaultDateTime;
 
+/*
+    wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime
 
 
 /**
 
 
 /**
@@ -1583,6 +1599,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.
@@ -1740,7 +1766,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
@@ -1748,7 +1774,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;
 };
 
 
 };
 
 
@@ -1830,7 +1856,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.
@@ -1883,7 +1909,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.
     */
@@ -1905,7 +1931,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.
     */