]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/datetime.h
no real changes, clarified the usage of WX_GL_DOUBLEBUFFER; documented it and other...
[wxWidgets.git] / interface / datetime.h
index 47cb2d070566524c326bd34498edb7dc435647c3..d964e6e5999da8d0cecfb7711c437228b43ecb61 100644 (file)
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        datetime.h
-// Purpose:     documentation for wxDateTime class
+// Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 
     wxDateTime class represents an absolute moment in the 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.
+
+
+    @section datetime_constants Constants
+
+    Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
+    defined. This constant will be different from any valid wxDateTime object.
+
+    All the following constants are defined inside wxDateTime class (i.e., to
+    refer to them you should prepend their names with "wxDateTime::").
+
+    Time zone symbolic names:
+
+    @code
+    enum TZ
+    {
+        // the time in the current time zone
+        Local,
+
+        // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+        // consequent numbers, so writing something like `GMT0 + offset' is
+        // safe if abs(offset) <= 12
+
+        // underscore stands for minus
+        GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
+        GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
+        GMT0,
+        GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
+        GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
+        // Note that GMT12 and GMT_12 are not the same: there is a difference
+        // of exactly one day between them
+
+        // some symbolic names for TZ
+
+        // Europe
+        WET = GMT0,         // Western Europe Time
+        WEST = GMT1,        // Western Europe Summer Time
+        CET = GMT1,         // Central Europe Time
+        CEST = GMT2,        // Central Europe Summer Time
+        EET = GMT2,         // Eastern Europe Time
+        EEST = GMT3,        // Eastern Europe Summer Time
+        MSK = GMT3,         // Moscow Time
+        MSD = GMT4,         // Moscow Summer Time
+
+        // US and Canada
+        AST = GMT_4,        // Atlantic Standard Time
+        ADT = GMT_3,        // Atlantic Daylight Time
+        EST = GMT_5,        // Eastern Standard Time
+        EDT = GMT_4,        // Eastern Daylight Saving Time
+        CST = GMT_6,        // Central Standard Time
+        CDT = GMT_5,        // Central Daylight Saving Time
+        MST = GMT_7,        // Mountain Standard Time
+        MDT = GMT_6,        // Mountain Daylight Saving Time
+        PST = GMT_8,        // Pacific Standard Time
+        PDT = GMT_7,        // Pacific Daylight Saving Time
+        HST = GMT_10,       // Hawaiian Standard Time
+        AKST = GMT_9,       // Alaska Standard Time
+        AKDT = GMT_8,       // Alaska Daylight Saving Time
+
+        // Australia
+
+        A_WST = GMT8,       // Western Standard Time
+        A_CST = GMT13 + 1,  // Central Standard Time (+9.5)
+        A_EST = GMT10,      // Eastern Standard Time
+        A_ESST = GMT11,     // Eastern Summer Time
+
+        // New Zealand
+        NZST = GMT12,       // Standard Time
+        NZDT = GMT13,       // Daylight Saving Time
+
+        // Universal Coordinated Time = the new and politically correct name
+        // for GMT
+        UTC = GMT0
+    };
+    @endcode
+
+    Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
+    Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
+
+    Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
+    in @c wxDateTime::WeekDay enum.
+
+    Finally, Inv_Year is defined to be an invalid value for year parameter.
+
+    GetMonthName() and GetWeekDayName() functions use the following flags:
+
+    @code
+    enum NameFlags
+    {
+        Name_Full = 0x01,       // return full name
+        Name_Abbr = 0x02        // return abbreviated name
+    };
+    @endcode
+
+    Several functions accept an extra parameter specifying the calendar to use
+    (although most of them only support now the Gregorian calendar). This
+    parameters is one of the following values:
+
+    @code
+    enum Calendar
+    {
+        Gregorian,  // calendar currently in use in Western countries
+        Julian      // calendar in use since -45 until the 1582 (or later)
+    };
+    @endcode
+
+    Date calculations often depend on the country and wxDateTime allows to set
+    the country whose conventions should be used using SetCountry(). It takes
+    one of the following values as parameter:
+
+    @code
+    enum Country
+    {
+        Country_Unknown, // no special information for this country
+        Country_Default, // set the default country with SetCountry() method
+                         // or use the default country with any other
+
+        Country_WesternEurope_Start,
+        Country_EEC = Country_WesternEurope_Start,
+        France,
+        Germany,
+        UK,
+        Country_WesternEurope_End = UK,
+
+        Russia,
+
+        USA
+    };
+    @endcode
+
+    Different parts of the world use different conventions for the week start.
+    In some countries, the week starts on Sunday, while in others -- on Monday.
+    The ISO standard doesn't address this issue, so we support both conventions
+    in the functions whose result depends on it (GetWeekOfYear() and
+    GetWeekOfMonth()).
+
+    The desired behvaiour may be specified by giving one of the following
+    constants as argument to these functions:
+
+    @code
+    enum WeekFlags
+    {
+        Default_First,   // Sunday_First for US, Monday_First for the rest
+        Monday_First,    // week starts with a Monday
+        Sunday_First     // week starts with a Sunday
+    };
+    @endcode
+
+
+    @section datetime_static Static Functions
+
+    All static functions either set or return the static variables of
+    wxDateSpan (the country), return the current moment, year, month or number
+    of days in it, or do some general calendar-related actions.
+
+    Please note that although several function accept an extra Calendar
+    parameter, it is currently ignored as only the Gregorian calendar is
+    supported. Future versions will support other calendars.
+
+    @beginWxPythonOnly
+    These methods are standalone functions named
+    "wxDateTime_<StaticMethodName>" in wxPython.
+    @endWxPythonOnly
+
+
+    @section datetime_formatting Date Formatting and Parsing
+
+    The date formatting and parsing functions convert wxDateTime objects to and
+    from text. The conversions to text are mostly trivial: you can either do it
+    using the default date and time representations for the current locale
+    (FormatDate() and FormatTime()), using the international standard
+    representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and
+    FormatISOCombined()) or by specifying any format at all and using Format()
+    directly.
+
+    The conversions from text are more interesting, as there are much more
+    possibilities to care about. The simplest cases can be taken care of with
+    ParseFormat() which can parse any date in the given (rigid) format.
+    ParseRfc822Date() is another function for parsing dates in predefined
+    format -- the one of RFC 822 which (still...) defines the format of email
+    messages on the Internet. This format can not be described with
+    @c strptime(3)-like format strings used by Format(), hence the need for a
+    separate function.
+
+    But the most interesting functions are ParseTime(), ParseDate() and
+    ParseDateTime(). They try to parse the date and time (or only one of them)
+    in 'free' format, i.e. allow them to be specified in any of possible ways.
+    These functions will usually be used to parse the (interactive) user input
+    which is not bound to be in any predefined format. As an example,
+    ParseDateTime() can parse the strings such as "tomorrow", "March first" and
+    even "next Sunday".
+
+    Finally notice that each of the parsing functions is available in several
+    overloads: if the input string is a narrow (@c char *) string, then a
+    narrow pointer is returned. If the input string is a wide string, a wide
+    char pointer is returned. Finally, if the input parameter is a wxString, a
+    narrow char pointer is also returned for backwards compatibility but there
+    is also an additional argument of wxString::const_iterator type in which,
+    if it is not @NULL, an iterator pointing to the end of the scanned string
+    part is returned.
+
+
     @library{wxbase}
     @category{data}
 
-    @seealso
-    @ref overview_wxdatetimeoverview "Date classes overview", wxTimeSpan,
-    wxDateSpan, wxCalendarCtrl
+    @stdobjects
+    - ::wxDefaultDateTime
+
+    @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
 */
 class wxDateTime
 {
 public:
     /**
-        Same as @ref setdate() Set
+        @name Constructors, Assignment Operators and Setters
+
+        Constructors and various Set() methods are collected here. If you
+        construct a date object from separate values for day, month and year,
+        you should use IsValid() method to check that the values were correct
+        as constructors can not return an error code.
+    */
+    //@{
+
+    /**
+        Default constructor. Use one of the Set() functions to initialize the
+        object later.
+    */
+    wxDateTime();
+    /**
+        Same as Set().
+
+        @beginWxPythonOnly
+        This constructor is named "wxDateTimeFromTimeT" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& wxDateTime(time_t timet);
+    /**
+        Same as Set().
+
+        @beginWxPythonOnly Unsupported. @endWxPythonOnly
+    */
+    wxDateTime& wxDateTime(const struct tm& tm);
+    /**
+        Same as Set().
+
+        @beginWxPythonOnly
+        This constructor is named "wxDateTimeFromJDN" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& wxDateTime(double jdn);
+    /**
+        Same as Set().
+
+        @beginWxPythonOnly
+        This constructor is named "wxDateTimeFromHMS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0,
+                           wxDateTime_t second = 0, wxDateTime_t millisec = 0);
+    /**
+        Same as Set().
+
+        @beginWxPythonOnly
+        This constructor is named "wxDateTimeFromDMY" in wxPython.
+        @endWxPythonOnly
     */
     wxDateTime(wxDateTime_t day, Month month = Inv_Month,
-               int Inv_Year, wxDateTime_t hour = 0,
-               wxDateTime_t minute = 0,
-               wxDateTime_t second = 0,
+               int year = Inv_Year, wxDateTime_t hour = 0,
+               wxDateTime_t minute = 0, wxDateTime_t second = 0,
                wxDateTime_t millisec = 0);
 
     /**
-        Here are the trivial accessors. Other functions, which might have to perform
-        some more complicated calculations to find the answer are under the
-        @ref overview_datetimecalculations "Calendar calculations" section.
-        IsValid()
-        
-        GetTicks()
-        
-        GetCentury()
-        
-        GetYear()
-        
-        GetMonth()
-        
-        GetDay()
-        
-        GetWeekDay()
-        
-        GetHour()
-        
-        GetMinute()
-        
-        GetSecond()
-        
-        GetMillisecond()
-        
-        GetDayOfYear()
-        
-        GetWeekOfYear()
-        
-        GetWeekOfMonth()
-        
-        GetYearDay()
-        
-        IsWorkDay()
-        
-        IsGregorianDate()
-        
-        GetAsDOS()
+        Reset time to midnight (00:00:00) without changing the date.
     */
+    wxDateTime& ResetTime();
 
-
-    //@{
     /**
-        Adds the given date span to this object.
+        Constructs the object from @a timet value holding the number of seconds
+        since Jan 1, 1970.
+
+        @beginWxPythonOnly
+        This method is named "SetTimeT" in wxPython.
+        @endWxPythonOnly
     */
-    wxDateTime Add(const wxDateSpan& diff);
-    const wxDateTime&  Add(const wxDateSpan& diff);
-    wxDateTime operator+=(const wxDateSpan& diff);
-    //@}
+    wxDateTime& Set(time_t timet);
+    /**
+        Sets the date and time from the broken down representation in the
+        standard @a tm structure.
 
+        @beginWxPythonOnly Unsupported. @endWxPythonOnly
+    */
+    wxDateTime& Set(const struct tm& tm);
     /**
-        Some degree of support for the date units used in astronomy and/or history is
-        provided. You can construct a wxDateTime object from a
-        @ref setjdn() JDN and you may also get its JDN,
-        @ref getmodifiedjuliandaynumber() MJD or
-        @ref getratadie() "Rata Die number" from it.
-        @ref wxdatetimejdn() "wxDateTime(double jdn)"
-        
-        @ref setjdn() "Set(double jdn)"
-        
-        GetJulianDayNumber()
-        
-        GetJDN()
-        
-        GetModifiedJulianDayNumber()
-        
-        GetMJD()
-        
-        GetRataDie()
-    */
-
-
-    /**
-        The functions in this section perform the basic calendar calculations, mostly
-        related to the week days. They allow to find the given week day in the
-        week with given number (either in the month or in the year) and so on.
-        All (non-const) functions in this section don't modify the time part of the
-        wxDateTime -- they only work with the date part of it.
-        SetToWeekDayInSameWeek()
-        
-        GetWeekDayInSameWeek()
-        
-        SetToNextWeekDay()
-        
-        GetNextWeekDay()
-        
-        SetToPrevWeekDay()
-        
-        GetPrevWeekDay()
-        
-        SetToWeekDay()
-        
-        @ref wxDateTime::getweekday2 GetWeekDay
-        
-        SetToLastWeekDay()
-        
-        GetLastWeekDay()
-        
-        SetToWeekOfYear()
-        
-        SetToLastMonthDay()
-        
-        GetLastMonthDay()
-        
-        SetToYearDay()
-        
-        GetYearDay()
-    */
-
-
-    /**
-        Constructors and various @c Set() methods are collected here. If you
-        construct a date object from separate values for day, month and year, you
-        should use IsValid() method to check that the
-        values were correct as constructors can not return an error code.
-        @ref wxdatetimedef() wxDateTime
-        
-        @ref wxdatetimetimet() wxDateTime(time_t)
-        
-        @ref wxdatetimetm() "wxDateTime(struct tm)"
-        
-        @ref wxdatetimejdn() "wxDateTime(double jdn)"
-        
-        @ref wxdatetimetime() "wxDateTime(h, m, s, ms)"
-        
-        @ref wxdatetimedate() "wxDateTime(day, mon, year, h, m, s, ms)"
-        
-        SetToCurrent()
-        
-        @ref settimet() Set(time_t)
-        
-        @ref settm() "Set(struct tm)"
-        
-        @ref setjdn() "Set(double jdn)"
-        
-        @ref settime() "Set(h, m, s, ms)"
-        
-        @ref setdate() "Set(day, mon, year, h, m, s, ms)"
-        
-        @ref setfromdos() "SetFromDOS(unsigned long ddt)"
-        
-        ResetTime()
-        
-        SetYear()
-        
-        SetMonth()
-        
-        @ref setdate() SetDay
-        
-        SetHour()
-        
-        SetMinute()
-        
-        SetSecond()
-        
-        SetMillisecond()
-        
-        @ref operatoreqtimet() operator=(time_t)
-        
-        @ref operatoreqtm() "operator=(struct tm)"
-    */
-
-
-    /**
-        Converts the year in absolute notation (i.e. a number which can be negative,
-        positive or zero) to the year in BC/AD notation. For the positive years,
-        nothing is done, but the year 0 is year 1 BC and so for other years there is a
-        difference of 1.
-        This function should be used like this:
+        Sets the date from the so-called Julian Day Number.
+
+        By definition, the Julian Day Number, usually abbreviated as JDN, of a
+        particular instant is the fractional number of days since 12 hours
+        Universal Coordinated Time (Greenwich mean noon) on January 1 of the
+        year -4712 in the Julian proleptic calendar.
+
+        @beginWxPythonOnly
+        This method is named "SetJDN" in wxPython.
+        @endWxPythonOnly
     */
-    static int ConvertYearToBC(int year);
+    wxDateTime& Set(double jdn);
+    /**
+        Sets the date to be equal to Today() and the time from supplied
+        parameters.
 
+        @beginWxPythonOnly
+        This method is named "SetHMS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0,
+                    wxDateTime_t second = 0, wxDateTime_t millisec = 0);
     /**
-        These functions carry out arithmetics on the wxDateTime
-        objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be
-        added to wxDateTime, hence all functions are overloaded to accept both
-        arguments.
-        Also, both @c Add() and @c Subtract() have both const and non-const
-        version. The first one returns a new object which represents the
-        sum/difference of the original one with the argument while the second form
-        modifies the object to which it is applied. The operators -= and += are
-        defined to be equivalent to the second forms of these functions.
-        @ref addts() Add(wxTimeSpan)
-        
-        @ref addds() Add(wxDateSpan)
-        
-        @ref subtractts() Subtract(wxTimeSpan)
-        
-        @ref subtractds() Subtract(wxDateSpan)
-        
-        @ref subtractdt() Subtract(wxDateTime)
-        
-        @ref addts() oparator+=(wxTimeSpan)
-        
-        @ref addds() oparator+=(wxDateSpan)
-        
-        @ref subtractts() oparator-=(wxTimeSpan)
-        
-        @ref subtractds() oparator-=(wxDateSpan)
-    */
-
-
-    /**
-        There are several function to allow date comparison. To supplement them, a few
-        global operators ,  etc taking wxDateTime are defined.
-        IsEqualTo()
-        
-        IsEarlierThan()
-        
-        IsLaterThan()
-        
-        IsStrictlyBetween()
-        
-        IsBetween()
-        
-        IsSameDate()
-        
-        IsSameTime()
-        
-        IsEqualUpTo()
-    */
-
-
-    /**
-        This function does the same as the standard ANSI C @c strftime(3) function.
-        Please see its description for the meaning of @a format parameter.
-        It also accepts a few wxWidgets-specific extensions: you can optionally specify
-        the width of the field to follow using @c printf(3)-like syntax and the
-        format specification @c %l can be used to get the number of milliseconds.
-        
-        @see ParseFormat()
+        Sets the date and time from the parameters.
     */
-    wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
-                    const TimeZone& tz = Local) const;
+    wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
+                    int year = Inv_Year, wxDateTime_t hour = 0,
+                    wxDateTime_t minute = 0, wxDateTime_t second = 0,
+                    wxDateTime_t millisec = 0);
 
     /**
-        Identical to calling Format() with @c "%x"
-        argument (which means 'preferred date representation for the current locale').
+        Sets the day without changing other date components.
     */
-    wxString FormatDate() const;
+    wxDateTime& SetDay(short unsigned int);
 
     /**
-        Returns the combined date-time representation in the ISO 8601 format
-        (YYYY-MM-DDTHH:MM:SS). The @a sep parameter default value produces the
-        result exactly corresponding to the ISO standard, but it can also be useful to
-        use a space as seprator if a more human-readable combined date-time
-        representation is needed.
-        
-        @see FormatISODate(), FormatISOTime(),
-             ParseISOCombined()
+        Sets the date from the date and time in DOS format.
     */
-    wxString FormatISOCombined(char sep = 'T') const;
+    wxDateTime& SetFromDOS(unsigned long ddt);
 
     /**
-        This function returns the date representation in the ISO 8601 format
-        (YYYY-MM-DD).
+        Sets the hour without changing other date components.
     */
-    wxString FormatISODate() const;
+    wxDateTime& SetHour(short unsigned int);
 
     /**
-        This function returns the time representation in the ISO 8601 format
-        (HH:MM:SS).
+        Sets the millisecond without changing other date components.
     */
-    wxString FormatISOTime() const;
+    wxDateTime& SetMillisecond(short unsigned int);
 
     /**
-        Identical to calling Format() with @c "%X"
-        argument (which means 'preferred time representation for the current locale').
+        Sets the minute without changing other date components.
     */
-    wxString FormatTime() const;
+    wxDateTime& SetMinute(short unsigned int);
 
     /**
-        Transform the date from the given time zone to the local one. If @a noDST is
-        @true, no DST adjustments will be made.
-        Returns the date in the local time zone.
+        Sets the month without changing other date components.
     */
-    wxDateTime FromTimezone(const TimeZone& tz,
-                            bool noDST = false) const;
+    wxDateTime& SetMonth(Month month);
 
     /**
-        Returns the translations of the strings @c AM and @c PM used for time
-        formatting for the current locale. Either of the pointers may be @NULL if
-        the corresponding value is not needed.
+        Sets the second without changing other date components.
     */
-    static void GetAmPmStrings(wxString* am, wxString* pm);
+    wxDateTime& SetSecond(short unsigned int);
 
     /**
-        Returns the date and time in
-        DOS
-        format.
+        Sets the date and time of to the current values. Same as assigning the
+        result of Now() to this object.
     */
-    unsigned long GetAsDOS() const;
+    wxDateTime& SetToCurrent();
 
     /**
-        Get the beginning of DST for the given country in the given year (current one
-        by default). This function suffers from limitations described in
-        @ref overview_tdatedst "DST overview".
-        
-        @see GetEndDST()
+        Sets the year without changing other date components.
     */
-    static wxDateTime GetBeginDST(int year = Inv_Year,
-                                  Country country = Country_Default);
+    wxDateTime& SetYear(int year);
 
     /**
-        Returns the century of this date.
+        Same as Set().
     */
-    int GetCentury(const TimeZone& tz = Local) const;
+    wxDateTime& operator=(time_t timet);
+    /**
+        Same as Set().
+    */
+    wxDateTime& operator=(const struct tm& tm);
+
+    //@}
+
+
 
     /**
-        Returns the current default country. The default country is used for DST
-        calculations, for example.
-        
-        @see SetCountry()
+        @name Accessors
+
+        Here are the trivial accessors. Other functions, which might have to
+        perform some more complicated calculations to find the answer are under
+        the "Date Arithmetics" section.
     */
-    static Country GetCountry();
+    //@{
 
     /**
-        Get the current month in given calendar (only Gregorian is currently supported).
+        Returns the date and time in DOS format.
     */
-    static Month GetCurrentMonth(Calendar cal = Gregorian);
+    long unsigned int GetAsDOS() const;
 
     /**
-        Get the current year in given calendar (only Gregorian is currently supported).
+        Returns the century of this date.
     */
-    static int GetCurrentYear(Calendar cal = Gregorian);
+    int GetCentury(const TimeZone& tz = Local) const;
 
     /**
-        Returns the object having the same date component as this one but time of
-        00:00:00.
-        This function is new since wxWidgets version 2.8.2
-        
+        Returns the object having the same date component as this one but time
+        of 00:00:00.
+
+        @since 2.8.2
+
         @see ResetTime()
     */
     wxDateTime GetDateOnly() const;
@@ -370,796 +428,1056 @@ public:
     /**
         Returns the day in the given timezone (local one by default).
     */
-    wxDateTime_t GetDay(const TimeZone& tz = Local) const;
+    short unsigned int GetDay(const TimeZone& tz = Local) const;
 
     /**
-        Returns the day of the year (in 1...366 range) in the given timezone
+        Returns the day of the year (in 1-366 range) in the given timezone
         (local one by default).
     */
-    wxDateTime_t GetDayOfYear(const TimeZone& tz = Local) const;
+    short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
 
     /**
-        Returns the end of DST for the given country in the given year (current one by
-        default).
-        
-        @see GetBeginDST()
+        Returns the hour in the given timezone (local one by default).
     */
-    static wxDateTime GetEndDST(int year = Inv_Year,
-                                Country country = Country_Default);
+    short unsigned int GetHour(const TimeZone& tz = Local) const;
 
     /**
-        Returns the hour in the given timezone (local one by default).
+        Returns the milliseconds in the given timezone (local one by default).
     */
-    wxDateTime_t GetHour(const TimeZone& tz = Local) const;
+    short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
 
     /**
-        Synonym for GetJulianDayNumber().
+        Returns the minute in the given timezone (local one by default).
     */
-    double GetJDN() const;
+    short unsigned int GetMinute(const TimeZone& tz = Local) const;
 
     /**
-        Returns the @ref setjdn() JDN corresponding to this date. Beware
-        of rounding errors!
-        
-        @see GetModifiedJulianDayNumber()
+        Returns the month in the given timezone (local one by default).
     */
-    double GetJulianDayNumber() const;
+    Month GetMonth(const TimeZone& tz = Local) const;
 
     /**
-        Returns the copy of this object to which
-        SetToLastMonthDay() was applied.
+        Returns the seconds in the given timezone (local one by default).
     */
-    wxDateTime GetLastMonthDay(Month month = Inv_Month,
-                               int year = Inv_Year) const;
+    short unsigned int GetSecond(const TimeZone& tz = Local) const;
 
     /**
-        Returns the copy of this object to which
-        SetToLastWeekDay() was applied.
+        Returns the number of seconds since Jan 1, 1970. An assert failure will
+        occur if the date is not in the range covered by @c time_t type.
     */
-    wxDateTime GetLastWeekDay(WeekDay weekday,
-                              Month month = Inv_Month,
-                              int year = Inv_Year);
+    time_t GetTicks() const;
 
     /**
-        Synonym for GetModifiedJulianDayNumber().
+        Returns broken down representation of the date and time.
     */
-    double GetMJD() const;
+    Tm GetTm(const TimeZone& tz = Local) const;
 
     /**
-        Returns the milliseconds in the given timezone (local one by default).
+        Returns the week day in the given timezone (local one by default).
     */
-    wxDateTime_t GetMillisecond(const TimeZone& tz = Local) const;
+    WeekDay GetWeekDay(const TimeZone& tz = Local) const;
 
     /**
-        Returns the minute in the given timezone (local one by default).
+        Returns the ordinal number of the week in the month (in 1-5 range).
+
+        As GetWeekOfYear(), this function supports both conventions for the
+        week start. See the description of these @c WeekFlags in the
+        @ref datetime_constants section.
     */
-    wxDateTime_t GetMinute(const TimeZone& tz = Local) const;
+    wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
+                                const TimeZone& tz = Local) const;
 
     /**
-        Returns the @e Modified Julian Day Number (MJD) which is, by definition,
-        equal to JDN - 2400000.5. The MJDs are simpler to work with as the integral
-        MJDs correspond to midnights of the dates in the Gregorian calendar and not th
-        noons like JDN. The MJD 0 is Nov 17, 1858.
+        Returns the number of the week of the year this date is in. The first
+        week of the year is, according to international standards, the one
+        containing Jan 4 or, equivalently, the first week which has Thursday in
+        this year. Both of these definitions are the same as saying that the
+        first week of the year must contain more than half of its days in this
+        year. Accordingly, the week number will always be in 1-53 range (52 for
+        non-leap years).
+
+        The function depends on the @ref datetime_constants "week start"
+        convention specified by the @a flags argument but its results for
+        @c Sunday_First are not well-defined as the ISO definition quoted above
+        applies to the weeks starting on Monday only.
     */
-    double GetModifiedJulianDayNumber() const;
+    wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
+                               const TimeZone& tz = Local) const;
 
     /**
-        Returns the month in the given timezone (local one by default).
+        Returns the year in the given timezone (local one by default).
     */
-    Month GetMonth(const TimeZone& tz = Local) const;
+    int GetYear(const TimeZone& tz = Local) const;
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr name of the
-        given month.
-        
-        @see GetWeekDayName()
+        Returns @true if the given date is later than the date of adoption of
+        the Gregorian calendar in the given country (and hence the Gregorian
+        calendar calculations make sense for it).
     */
-    static wxString GetMonthName(Month month,
-                                 NameFlags flags = Name_Full);
+    bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
 
     /**
-        Returns the copy of this object to which
-        SetToNextWeekDay() was applied.
+        Returns @true if the object represents a valid time moment.
     */
-    wxDateTime GetNextWeekDay(WeekDay weekday) const;
+    bool IsValid() const;
 
-    //@{
     /**
-        Returns the number of days in the given year or in the given month of the
-        year.
-        The only supported value for @a cal parameter is currently @c Gregorian.
+        Returns @true is this day is not a holiday in the given country.
     */
-    static wxDateTime_t GetNumberOfDays(int year,
-                                        Calendar cal = Gregorian);
-    static wxDateTime_t GetNumberOfDays(Month month,
-                                        int year = Inv_Year,
-                                        Calendar cal = Gregorian);
+    bool IsWorkDay(Country country = Country_Default) const;
+
     //@}
 
+
+
     /**
-        Returns the copy of this object to which
-        SetToPrevWeekDay() was applied.
+        @name Date Comparison
+
+        There are several functions to allow date comparison. To supplement
+        them, a few global operators, etc taking wxDateTime are defined.
     */
-    wxDateTime GetPrevWeekDay(WeekDay weekday) const;
+    //@{
 
     /**
-        Return the @e Rata Die number of this date.
-        By definition, the Rata Die number is a date specified as the number of days
-        relative to a base date of December 31 of the year 0. Thus January 1 of the
-        year 1 is Rata Die day 1.
+        Returns @true if this date precedes the given one.
     */
-    double GetRataDie() const;
+    bool IsEarlierThan(const wxDateTime& datetime) const;
 
     /**
-        Returns the seconds in the given timezone (local one by default).
+        Returns @true if the two dates are strictly identical.
     */
-    wxDateTime_t GetSecond(const TimeZone& tz = Local) const;
+    bool IsEqualTo(const wxDateTime& datetime) const;
 
     /**
-        Returns the number of seconds since Jan 1, 1970. An assert failure will occur
-        if the date is not in the range covered by @c time_t type.
+        Returns @true if the date is equal to another one up to the given time
+        interval, i.e. if the absolute difference between the two dates is less
+        than this interval.
     */
-    time_t GetTicks() const;
+    bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
 
     /**
-        Returns the current time.
+        Returns @true if this date is later than the given one.
     */
-    static time_t GetTimeNow();
+    bool IsLaterThan(const wxDateTime& datetime) const;
 
     /**
-        Returns broken down representation of the date and time.
+        Returns @true if the date is the same without comparing the time parts.
     */
-    Tm GetTm(const TimeZone& tz = Local) const;
+    bool IsSameDate(const wxDateTime& dt) const;
 
     /**
-        Returns the current time broken down. Note that this function returns a
-        pointer to a static buffer that's reused by calls to this function and
-        certain C library functions (e.g. localtime). If there is any chance your
-        code might be used in a multi-threaded application, you really should use
-        the flavour of function GetTmNow()
-        taking a parameter.
+        Returns @true if the time is the same (although dates may differ).
     */
-    static struct tm* GetTmNow();
+    bool IsSameTime(const wxDateTime& dt) const;
 
     /**
-        Returns the copy of this object to which
-        SetToWeekDay() was applied.
+        Returns @true if this date lies strictly between the two given dates.
+
+        @see IsBetween()
     */
-    wxDateTime GetWeekDay(WeekDay weekday, int n = 1,
-                          Month month = Inv_Month,
-                          int year = Inv_Year) const;
+    bool IsStrictlyBetween(const wxDateTime& t1,
+                            const wxDateTime& t2) const;
 
     /**
-        Returns the copy of this object to which
-        SetToWeekDayInSameWeek() was
-        applied.
+        Returns @true if IsStrictlyBetween() is @true or if the date is equal
+        to one of the limit values.
+
+        @see IsStrictlyBetween()
     */
-    wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
-                                    WeekFlags flags = Monday_First) const;
+    bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const;
+
+    //@}
+
+
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr name of the
-        given week day.
-        
-        @see GetMonthName()
+        @name Date Arithmetics
+
+        These functions carry out
+        @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime
+        objects. As explained in the overview, either wxTimeSpan or wxDateSpan
+        may be added to wxDateTime, hence all functions are overloaded to
+        accept both arguments.
+
+        Also, both Add() and Subtract() have both const and non-const version.
+        The first one returns a new object which represents the sum/difference
+        of the original one with the argument while the second form modifies
+        the object to which it is applied. The operators "-=" and "+=" are
+        defined to be equivalent to the second forms of these functions.
     */
-    static wxString GetWeekDayName(WeekDay weekday,
-                                   NameFlags flags = Name_Full);
+    //@{
 
     /**
-        Returns the ordinal number of the week in the month (in 1...5  range).
-        As GetWeekOfYear(), this function supports
-        both conventions for the week start. See the description of these
-        @ref overview_wxdatetime "week start" conventions.
+        Adds the given date span to this object.
+
+        @beginWxPythonOnly
+        This method is named "AddDS" in wxPython.
+        @endWxPythonOnly
     */
-    wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
-                                const TimeZone& tz = Local) const;
+    wxDateTime Add(const wxDateSpan& diff) const;
+    /**
+        Adds the given date span to this object.
 
+        @beginWxPythonOnly
+        This method is named "AddDS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime Add(const wxDateSpan& diff);
     /**
-        Returns the number of the week of the year this date is in. The first week of
-        the year is, according to international standards, the one containing Jan 4 or,
-        equivalently, the first week which has Thursday in this year. Both of these
-        definitions are the same as saying that the first week of the year must contain
-        more than half of its days in this year. Accordingly, the week number will
-        always be in 1...53 range (52 for non-leap years).
-        The function depends on the @ref overview_wxdatetime "week start" convention
-        specified by the @a flags argument but its results for
-        @c Sunday_First are not well-defined as the ISO definition quoted above
-        applies to the weeks starting on Monday only.
+        Adds the given time span to this object.
+
+        @beginWxPythonOnly
+        This method is named "AddTS" in wxPython.
+        @endWxPythonOnly
     */
-    wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
-                               const TimeZone& tz = Local) const;
+    wxDateTime Add(const wxTimeSpan& diff) const;
+    /**
+        Adds the given time span to this object.
+
+        @beginWxPythonOnly
+        This method is named "AddTS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& Add(const wxTimeSpan& diff);
 
     /**
-        Returns the year in the given timezone (local one by default).
+        Subtracts the given time span from this object.
+
+        @beginWxPythonOnly
+        This method is named "SubtractTS" in wxPython.
+        @endWxPythonOnly
     */
-    int GetYear(const TimeZone& tz = Local) const;
+    wxDateTime Subtract(const wxTimeSpan& diff) const;
+    /**
+        Subtracts the given time span from this object.
 
+        @beginWxPythonOnly
+        This method is named "SubtractTS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& Subtract(const wxTimeSpan& diff);
     /**
-        Returns the copy of this object to which
-        SetToYearDay() was applied.
+        Subtracts the given date span from this object.
+
+        @beginWxPythonOnly
+        This method is named "SubtractDS" in wxPython.
+        @endWxPythonOnly
     */
-    wxDateTime GetYearDay(wxDateTime_t yday) const;
+    wxDateTime Subtract(const wxDateSpan& diff) const;
+    /**
+        Subtracts the given date span from this object.
 
+        @beginWxPythonOnly
+        This method is named "SubtractDS" in wxPython.
+        @endWxPythonOnly
+    */
+    wxDateTime& Subtract(const wxDateSpan& diff);
     /**
-        Returns @true if IsStrictlyBetween()
-        is @true or if the date is equal to one of the limit values.
-        
-        @see IsStrictlyBetween()
+        Subtracts another date from this one and returns the difference between
+        them as a wxTimeSpan.
     */
-    bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const;
+    wxTimeSpan Subtract(const wxDateTime& dt) const;
 
     /**
-        Returns @true if the DST is applied for this date in the given country.
+        Adds the given date span to this object.
     */
-    int IsDST(Country country = Country_Default) const;
+    wxDateTime operator+=(const wxDateSpan& diff);
+    /**
+        Subtracts the given date span from this object.
+    */
+    wxDateTime& operator-=(const wxDateSpan& diff);
+    /**
+        Adds the given time span to this object.
+    */
+    wxDateTime& operator+=(const wxTimeSpan& diff);
+    /**
+        Subtracts the given time span from this object.
+    */
+    wxDateTime& operator-=(const wxTimeSpan& diff);
+
+    //@}
+
+
 
     /**
-        Returns @true if DST was used n the given year (the current one by
-        default) in the given country.
+        @name Date Formatting and Parsing
+
+        See @ref datetime_formatting
     */
-    static bool IsDSTApplicable(int year = Inv_Year,
-                                Country country = Country_Default);
+    //@{
 
     /**
-        Returns @true if this date precedes the given one.
+        This function does the same as the standard ANSI C @c strftime(3)
+        function. Please see its description for the meaning of @a format
+        parameter.
+
+        It also accepts a few wxWidgets-specific extensions: you can optionally
+        specify the width of the field to follow using @c printf(3)-like syntax
+        and the format specification @c "%l" can be used to get the number of
+        milliseconds.
+
+        @see ParseFormat()
     */
-    bool IsEarlierThan(const wxDateTime& datetime) const;
+    wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
+                    const TimeZone& tz = Local) const;
 
     /**
-        Returns @true if the two dates are strictly identical.
+        Identical to calling Format() with @c "%x" argument (which means
+        "preferred date representation for the current locale").
     */
-    bool IsEqualTo(const wxDateTime& datetime) const;
+    wxString FormatDate() const;
 
     /**
-        Returns @true if the date is equal to another one up to the given time
-        interval, i.e. if the absolute difference between the two dates is less than
-        this interval.
+        Returns the combined date-time representation in the ISO 8601 format
+        @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
+        the result exactly corresponding to the ISO standard, but it can also
+        be useful to use a space as seprator if a more human-readable combined
+        date-time representation is needed.
+
+        @see FormatISODate(), FormatISOTime(), ParseISOCombined()
     */
-    bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
+    wxString FormatISOCombined(char sep = 'T') const;
 
     /**
-        Returns @true if the given date is later than the date of adoption of the
-        Gregorian calendar in the given country (and hence the Gregorian calendar
-        calculations make sense for it).
+        This function returns the date representation in the ISO 8601 format
+        @c "YYYY-MM-DD".
     */
-    bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
+    wxString FormatISODate() const;
 
     /**
-        Returns @true if this date is later than the given one.
+        This function returns the time representation in the ISO 8601 format
+        @c "HH:MM:SS".
     */
-    bool IsLaterThan(const wxDateTime& datetime) const;
+    wxString FormatISOTime() const;
 
     /**
-        Returns @true if the @a year is a leap one in the specified calendar.
-        This functions supports Gregorian and Julian calendars.
+        Identical to calling Format() with @c "%X" argument (which means
+        "preferred time representation for the current locale").
     */
-    static bool IsLeapYear(int year = Inv_Year,
-                           Calendar cal = Gregorian);
+    wxString FormatTime() const;
 
     /**
-        Returns @true if the date is the same without comparing the time parts.
+        This function is like ParseDateTime(), but it only allows the date to
+        be specified. It is thus less flexible then ParseDateTime(), but also
+        has less chances to misinterpret the user input.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    bool IsSameDate(const wxDateTime& dt) const;
+    const char* ParseDate(const wxString& date,
+                           wxString::const_iterator* end = NULL);
+    /**
+        This function is like ParseDateTime(), but it only allows the date to
+        be specified. It is thus less flexible then ParseDateTime(), but also
+        has less chances to misinterpret the user input.
 
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const char* ParseDate(const char* date);
     /**
-        Returns @true if the time is the same (although dates may differ).
+        This function is like ParseDateTime(), but it only allows the date to
+        be specified. It is thus less flexible then ParseDateTime(), but also
+        has less chances to misinterpret the user input.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    bool IsSameTime(const wxDateTime& dt) const;
+    const wchar_t* ParseDate(const wchar_t* date);
 
     /**
-        Returns @true if this date lies strictly between the two others,
-        
-        @see IsBetween()
+        Parses the string @a datetime containing the date and time in free
+        format. This function tries as hard as it can to interpret the given
+        string as date and time. Unlike ParseRfc822Date(), it will accept
+        anything that may be accepted and will only reject strings which can
+        not be parsed in any way at all.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    bool IsStrictlyBetween(const wxDateTime& t1,
-                           const wxDateTime& t2) const;
+    const char* ParseDateTime(const wxString& datetime,
+                              wxString::const_iterator* end = NULL);
+    /**
+        Parses the string @a datetime containing the date and time in free
+        format. This function tries as hard as it can to interpret the given
+        string as date and time. Unlike ParseRfc822Date(), it will accept
+        anything that may be accepted and will only reject strings which can
+        not be parsed in any way at all.
 
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const char* ParseDateTime(const char* datetime);
     /**
-        Returns @true if the object represents a valid time moment.
+        Parses the string @a datetime containing the date and time in free
+        format. This function tries as hard as it can to interpret the given
+        string as date and time. Unlike ParseRfc822Date(), it will accept
+        anything that may be accepted and will only reject strings which can
+        not be parsed in any way at all.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    bool IsValid() const;
+    const wchar_t* ParseDateTime(const wchar_t* datetime);
 
     /**
-        This function returns @true if the specified (or default) country is one
-        of Western European ones. It is used internally by wxDateTime to determine the
-        DST convention and date and time formatting rules.
+        This function parses the string @a date according to the given
+        @e format. The system @c strptime(3) function is used whenever
+        available, but even if it is not, this function is still implemented,
+        although support for locale-dependent format specifiers such as
+        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
+        as @c "%z" and @c "%Z" are not implemented. This function does handle
+        the month and weekday names in the current locale on all platforms,
+        however.
+
+        Please see the description of the ANSI C function @c strftime(3) for
+        the syntax of the format string.
+
+        The @a dateDef parameter is used to fill in the fields which could not
+        be determined from the format string. For example, if the format is
+        @c "%d" (the day of the month), the month and the year are taken from
+        @a dateDef. If it is not specified, Today() is used as the default
+        date.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    static bool IsWestEuropeanCountry(Country country = Country_Default);
+    const char* ParseFormat(const wxString& date,
+                             const wxString& format = wxDefaultDateTimeFormat,
+                             const wxDateTime& dateDef = wxDefaultDateTime,
+                             wxString::const_iterator* end = NULL);
+    /**
+        This function parses the string @a date according to the given
+        @e format. The system @c strptime(3) function is used whenever
+        available, but even if it is not, this function is still implemented,
+        although support for locale-dependent format specifiers such as
+        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
+        as @c "%z" and @c "%Z" are not implemented. This function does handle
+        the month and weekday names in the current locale on all platforms,
+        however.
+
+        Please see the description of the ANSI C function @c strftime(3) for
+        the syntax of the format string.
+
+        The @a dateDef parameter is used to fill in the fields which could not
+        be determined from the format string. For example, if the format is
+        @c "%d" (the day of the month), the month and the year are taken from
+        @a dateDef. If it is not specified, Today() is used as the default
+        date.
 
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const char* ParseFormat(const char* date,
+                              const wxString& format = wxDefaultDateTimeFormat,
+                              const wxDateTime& dateDef = wxDefaultDateTime);
     /**
-        Returns @true is this day is not a holiday in the given country.
+        This function parses the string @a date according to the given
+        @e format. The system @c strptime(3) function is used whenever
+        available, but even if it is not, this function is still implemented,
+        although support for locale-dependent format specifiers such as
+        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
+        as @c "%z" and @c "%Z" are not implemented. This function does handle
+        the month and weekday names in the current locale on all platforms,
+        however.
+
+        Please see the description of the ANSI C function @c strftime(3) for
+        the syntax of the format string.
+
+        The @a dateDef parameter is used to fill in the fields which could not
+        be determined from the format string. For example, if the format is
+        @c "%d" (the day of the month), the month and the year are taken from
+        @a dateDef. If it is not specified, Today() is used as the default
+        date.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
     */
-    bool IsWorkDay(Country country = Country_Default) const;
+    const wchar_t* ParseFormat(const wchar_t* date,
+                                 const wxString& format = wxDefaultDateTimeFormat,
+                                 const wxDateTime& dateDef = wxDefaultDateTime);
 
     /**
-        Same as FromTimezone() but modifies the object
-        in place.
+        This function parses the string containing the date and time in ISO
+        8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between
+        the date and time parts must be equal to @a sep for the function to
+        succeed.
+
+        @returns @true if the entire string was parsed successfully, @false
+                 otherwise.
     */
-    wxDateTime MakeFromTimezone(const TimeZone& tz,
-                                bool noDST = false);
+    bool ParseISOCombined(const wxString& date, char sep = 'T');
 
     /**
-        Modifies the object in place to represent the date in another time zone. If
-        @a noDST is @true, no DST adjustments will be made.
+        This function parses the date in ISO 8601 format @c "YYYY-MM-DD".
+
+        @returns @true if the entire string was parsed successfully, @false
+                 otherwise.
     */
-    wxDateTime MakeTimezone(const TimeZone& tz,
-                            bool noDST = false);
+    bool ParseISODate(const wxString& date);
 
     /**
-        This is the same as calling MakeTimezone() with
-        the argument @c GMT0.
+        This function parses the time in ISO 8601 format @c "HH:MM:SS".
+
+        @returns @true if the entire string was parsed successfully, @false
+                 otherwise.
     */
-    wxDateTime MakeUTC(bool noDST = false);
+    bool ParseISOTime(const wxString& date);
 
     /**
-        Returns the object corresponding to the current time.
-        Example:
-        
-        Note that this function is accurate up to second:
-        UNow() should be used for better precision
-        (but it is less efficient and might not be available on all platforms).
-        
-        @see Today()
+        Parses the string @a date looking for a date formatted according to the
+        RFC 822 in it. The exact description of this format may, of course, be
+        found in the RFC (section 5), but, briefly, this is the format used in
+        the headers of Internet email messages and one of the most common
+        strings expressing date in this format may be something like
+        @c "Sat, 18 Dec 1999 00:48:30 +0100".
+
+        Returns @NULL if the conversion failed, otherwise return the pointer to
+        the character immediately following the part of the string which could
+        be parsed. If the entire string contains only the date in RFC 822
+        format, the returned pointer will be pointing to a @c NUL character.
+
+        This function is intentionally strict, it will return an error for any
+        string which is not RFC 822 compliant. If you need to parse date
+        formatted in more free ways, you should use ParseDateTime() or
+        ParseDate() instead.
     */
-    static wxDateTime Now();
+    const char* ParseRfc822Date(const wxString& date,
+                                  wxString::const_iterator* end = NULL);
+    /**
+        Parses the string @a date looking for a date formatted according to the
+        RFC 822 in it. The exact description of this format may, of course, be
+        found in the RFC (section 5), but, briefly, this is the format used in
+        the headers of Internet email messages and one of the most common
+        strings expressing date in this format may be something like
+        @c "Sat, 18 Dec 1999 00:48:30 +0100".
 
-    //@{
+        Returns @NULL if the conversion failed, otherwise return the pointer to
+        the character immediately following the part of the string which could
+        be parsed. If the entire string contains only the date in RFC 822
+        format, the returned pointer will be pointing to a @c NUL character.
+
+        This function is intentionally strict, it will return an error for any
+        string which is not RFC 822 compliant. If you need to parse date
+        formatted in more free ways, you should use ParseDateTime() or
+        ParseDate() instead.
+    */
+    const char* ParseRfc822Date(const char* date);
     /**
-        This function is like ParseDateTime(), but it
-        only allows the date to be specified. It is thus less flexible then
-        ParseDateTime(), but also has less chances to
-        misinterpret the user input.
+        Parses the string @a date looking for a date formatted according to the
+        RFC 822 in it. The exact description of this format may, of course, be
+        found in the RFC (section 5), but, briefly, this is the format used in
+        the headers of Internet email messages and one of the most common
+        strings expressing date in this format may be something like
+        @c "Sat, 18 Dec 1999 00:48:30 +0100".
+
         Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character which stopped the scan.
+        the character immediately following the part of the string which could
+        be parsed. If the entire string contains only the date in RFC 822
+        format, the returned pointer will be pointing to a @c NUL character.
+
+        This function is intentionally strict, it will return an error for any
+        string which is not RFC 822 compliant. If you need to parse date
+        formatted in more free ways, you should use ParseDateTime() or
+        ParseDate() instead.
     */
-    const char* ParseDate(const wxString& date,
-                          wxString::const_iterator* end = NULL);
-    const char* ParseDate(const char* date);
-    const wchar_t* ParseDate(const wchar_t* date);
+    const wchar_t* ParseRfc822Date(const wchar_t* date);
+
+    /**
+        This functions is like ParseDateTime(), but only allows the time to be
+        specified in the input string.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const char* ParseTime(const wxString& time,
+                           wxString::const_iterator* end = NULL);
+    /**
+        This functions is like ParseDateTime(), but only allows the time to be
+        specified in the input string.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const char* ParseTime(const char* time);
+    /**
+        This functions is like ParseDateTime(), but only allows the time to be
+        specified in the input string.
+
+        @returns @NULL if the conversion failed, otherwise return the pointer
+                 to the character which stopped the scan.
+    */
+    const wchar_t* ParseTime(const wchar_t* time);
+
     //@}
 
+
+
+    /**
+        @name Calendar Calculations
+
+        The functions in this section perform the basic calendar calculations,
+        mostly related to the week days. They allow to find the given week day
+        in the week with given number (either in the month or in the year) and
+        so on.
+
+        None of the functions in this section modify the time part of the
+        wxDateTime, they only work with the date part of it.
+    */
     //@{
+
     /**
-        Parses the string @a datetime containing the date and time in free format.
-        This function tries as hard as it can to interpret the given string as date
-        and time. Unlike wxDateTime::ParseRfc822Date, it
-        will accept anything that may be accepted and will only reject strings which
-        can not be parsed in any way at all.
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character which stopped the scan.
+        Returns the copy of this object to which SetToLastMonthDay() was
+        applied.
     */
-    const char* ParseDateTime(const wxString& datetime,
-                              wxString::const_iterator* end = NULL);
-    const char* ParseDateTime(const char* datetime);
-    const wchar_t* ParseDateTime(const wchar_t* datetime);
+    wxDateTime GetLastMonthDay(Month month = Inv_Month,
+                               int year = Inv_Year) const;
+
+    /**
+        Returns the copy of this object to which SetToLastWeekDay() was
+        applied.
+    */
+    wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month,
+                              int year = Inv_Year);
+
+    /**
+        Returns the copy of this object to which SetToNextWeekDay() was
+        applied.
+    */
+    wxDateTime GetNextWeekDay(WeekDay weekday) const;
+
+    /**
+        Returns the copy of this object to which SetToPrevWeekDay() was
+        applied.
+    */
+    wxDateTime GetPrevWeekDay(WeekDay weekday) const;
+
+    /**
+        Returns the copy of this object to which SetToWeekDay() was applied.
+    */
+    wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month,
+                          int year = Inv_Year) const;
+
+    /**
+        Returns the copy of this object to which SetToWeekDayInSameWeek() was
+        applied.
+    */
+    wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
+                                    WeekFlags flags = Monday_First) const;
+
+    /**
+        Returns the copy of this object to which SetToYearDay() was applied.
+    */
+    wxDateTime GetYearDay(wxDateTime_t yday) const;
+
+    /**
+        Sets the date to the last day in the specified month (the current one
+        by default).
+
+        @returns The reference to the modified object itself.
+    */
+    wxDateTime SetToLastMonthDay(Month month = Inv_Month,
+                                 int year = Inv_Year);
+
+    /**
+        The effect of calling this function is the same as of calling
+        @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
+        last @a weekday in the given month and year (the current ones by
+        default). Always returns @true.
+    */
+    bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
+                          int year = Inv_Year);
+
+    /**
+        Sets the date so that it will be the first @a weekday following the
+        current date.
+
+        @returns The reference to the modified object itself.
+    */
+    wxDateTime& SetToNextWeekDay(WeekDay weekday);
+
+    /**
+        Sets the date so that it will be the last @a weekday before the current
+        date.
+
+        @returns The reference to the modified object itself.
+    */
+    wxDateTime& SetToPrevWeekDay(WeekDay weekday);
+
+    /**
+        Sets the date to the @e n-th @a weekday in the given month of the given
+        year (the current month and year are used by default). The parameter
+        @a n may be either positive (counting from the beginning of the month)
+        or negative (counting from the end of it).
+
+        For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
+        second Wednesday in the current month and
+        SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
+        in the current month.
+
+        @returns @true if the date was modified successfully, @false otherwise
+                 meaning that the specified date doesn't exist.
+    */
+    bool SetToWeekDay(WeekDay weekday, int n = 1,
+                       Month month = Inv_Month, int year = Inv_Year);
+
+    /**
+        Adjusts the date so that it will still lie in the same week as before,
+        but its week day will be the given one.
+
+        @returns The reference to the modified object itself.
+    */
+    wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
+                                      WeekFlags flags = Monday_First);
+
+    /**
+        Sets the date to the day number @a yday in the same year (i.e., unlike
+        the other functions, this one does not use the current year). The day
+        number should be in the range 1-366 for the leap years and 1-365 for
+        the other ones.
+
+        @returns The reference to the modified object itself.
+    */
+    wxDateTime& SetToYearDay(wxDateTime_t yday);
+
     //@}
 
-    //@{
+
+
+    /**
+        @name Astronomical/Historical Functions
+
+        Some degree of support for the date units used in astronomy and/or
+        history is provided. You can construct a wxDateTime object from a
+        JDN and you may also get its JDN, MJD or Rata Die number from it.
+
+        Related functions in other groups: wxDateTime(double), Set(double)
+    */
+    //@{
+
+    /**
+        Synonym for GetJulianDayNumber().
+    */
+    double GetJDN() const;
+
+    /**
+        Returns the JDN corresponding to this date. Beware of rounding errors!
+
+        @see GetModifiedJulianDayNumber()
+    */
+    double GetJulianDayNumber() const;
+
+    /**
+        Synonym for GetModifiedJulianDayNumber().
+    */
+    double GetMJD() const;
+
+    /**
+        Returns the @e "Modified Julian Day Number" (MJD) which is, by
+        definition, is equal to JDN - 2400000.5. The MJDs are simpler to work
+        with as the integral MJDs correspond to midnights of the dates in the
+        Gregorian calendar and not the noons like JDN. The MJD 0 represents
+        Nov 17, 1858.
+    */
+    double GetModifiedJulianDayNumber() const;
+
     /**
-        This function parses the string @a date according to the given
-        @e format. The system @c strptime(3) function is used whenever available,
-        but even if it is not, this function is still implemented, although support
-        for locale-dependent format specifiers such as @c "%c", @c "%x" or @c "%X" may
-        not be perfect and GNU extensions such as @c "%z" and @c "%Z" are
-        not implemented. This function does handle the month and weekday
-        names in the current locale on all platforms, however.
-        Please see the description of the ANSI C function @c strftime(3) for the syntax
-        of the format string.
-        The @a dateDef parameter is used to fill in the fields which could not be
-        determined from the format string. For example, if the format is @c "%d" (the
-        ay of the month), the month and the year are taken from @e dateDef. If
-        it is not specified, Today() is used as the
-        default date.
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character which stopped the scan.
+        Return the @e Rata Die number of this date.
+
+        By definition, the Rata Die number is a date specified as the number of
+        days relative to a base date of December 31 of the year 0. Thus January
+        1 of the year 1 is Rata Die day 1.
     */
-    const char* ParseFormat(const wxString& date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime,
-                            wxString::const_iterator* end = NULL);
-    const char* ParseFormat(const char* date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime);
-    const wchar_t* ParseFormat(const wchar_t* date,
-                               const wxString& format = wxDefaultDateTimeFormat,
-                               const wxDateTime& dateDef = wxDefaultDateTime);
+    double GetRataDie() const;
+
     //@}
 
+
+
     /**
-        This function parses the string containing the date and time in ISO 8601
-        combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time
-        parts must be equal to @a sep for the function to succeed.
-        Returns @true if the entire string was parsed successfully, @false
-        otherwise.
+        @name Time Zone and DST Support
+
+        Please see the @ref overview_datetime_timezones "time zone overview"
+        for more information about time zones. Normally, these functions should
+        be rarely used.
+
+        Related functions in other groups: GetBeginDST(), GetEndDST()
     */
-    bool ParseISOCombined(const wxString& date, char sep = 'T');
+    //@{
 
     /**
-        This function parses the date in ISO 8601 format (YYYY-MM-DD).
-        Returns @true if the entire string was parsed successfully, @false
-        otherwise.
+        Transform the date from the given time zone to the local one. If
+        @a noDST is @true, no DST adjustments will be made.
+
+        @returns The date in the local time zone.
     */
-    bool ParseISODate(const wxString& date);
+    wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const;
 
     /**
-        This function parses the time in ISO 8601 format (HH:MM:SS).
-        Returns @true if the entire string was parsed successfully, @false
-        otherwise.
+        Returns @true if the DST is applied for this date in the given country.
+
+        @see GetBeginDST(), GetEndDST()
     */
-    bool ParseISOTime(const wxString& date);
+    int IsDST(Country country = Country_Default) const;
 
-    //@{
     /**
-        Parses the string @a date looking for a date formatted according to the RFC
-        822 in it. The exact description of this format may, of course, be found in
-        the RFC (section 5), but, briefly, this is the format used in the headers of
-        Internet email messages and one of the most common strings expressing date in
-        this format may be something like @c "Sat, 18 Dec 1999 00:48:30 +0100".
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could be
-        parsed. If the entire string contains only the date in RFC 822 format,
-        the returned pointer will be pointing to a @c NUL character.
-        This function is intentionally strict, it will return an error for any string
-        which is not RFC 822 compliant. If you need to parse date formatted in more
-        free ways, you should use ParseDateTime() or
-        ParseDate() instead.
+        Same as FromTimezone() but modifies the object in place.
     */
-    const char* ParseRfc822Date(const wxString& date,
-                                wxString::const_iterator* end = NULL);
-    const char* ParseRfc822Date(const char* date);
-    const wchar_t* ParseRfc822Date(const wchar_t* date);
-    //@}
+    wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false);
 
-    //@{
     /**
-        This functions is like ParseDateTime(), but
-        only allows the time to be specified in the input string.
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character which stopped the scan.
+        Modifies the object in place to represent the date in another time
+        zone. If @a noDST is @true, no DST adjustments will be made.
     */
-    const char* ParseTime(const wxString& time,
-                          wxString::const_iterator* end = NULL);
-    const char* ParseTime(const char* time);
-    const wchar_t* ParseTime(const wchar_t* time);
-    //@}
+    wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false);
 
     /**
-        These functions convert wxDateTime objects to and from text. The
-        conversions to text are mostly trivial: you can either do it using the default
-        date and time representations for the current locale (
-        FormatDate() and
-        wxDateTime::FormatTime), using the international standard
-        representation defined by ISO 8601 (
-        FormatISODate(),
-        FormatISOTime() and
-        wxDateTime::FormatISOCombined) or by specifying any
-        format at all and using Format() directly.
-        The conversions from text are more interesting, as there are much more
-        possibilities to care about. The simplest cases can be taken care of with
-        ParseFormat() which can parse any date in the
-        given (rigid) format. wxDateTime::ParseRfc822Date is
-        another function for parsing dates in predefined format -- the one of RFC 822
-        which (still...) defines the format of email messages on the Internet. This
-        format can not be described with @c strptime(3)-like format strings used by
-        Format(), hence the need for a separate function.
-        But the most interesting functions are
-        ParseTime(),
-        ParseDate() and
-        ParseDateTime(). They try to parse the date
-        ans time (or only one of them) in 'free' format, i.e. allow them to be
-        specified in any of possible ways. These functions will usually be used to
-        parse the (interactive) user input which is not bound to be in any predefined
-        format. As an example, ParseDateTime() can
-        parse the strings such as @c "tomorrow", @c "March first" and even
-        @c "next Sunday".
-        Finally notice that each of the parsing functions is available in several
-        overloads: if the input string is a narrow (@c char *) string, then a
-        narrow pointer is returned. If the input string is a wide string, a wide char
-        pointer is returned. Finally, if the input parameter is a wxString, a narrow
-        char pointer is also returned for backwards compatibility but there is also an
-        additional argument of wxString::const_iterator type in which, if it is not
-        @NULL, an iterator pointing to the end of the scanned string part is returned.
-        ParseFormat()
-        
-        ParseDateTime()
-        
-        ParseDate()
-        
-        ParseTime()
-        
-        ParseISODate()
-        
-        ParseISOTime()
-        
-        ParseISOCombined()
-        
-        wxDateTime::ParseRfc822Date
-        
-        Format()
-        
-        FormatDate()
-        
-        FormatTime()
-        
-        FormatISOCombined()
-        
-        FormatISODate()
-        
-        FormatISOTime()
+        This is the same as calling MakeTimezone() with the argument @c GMT0.
     */
-
+    wxDateTime& MakeUTC(bool noDST = false);
 
     /**
-        Reset time to midnight (00:00:00) without changing the date.
+        Transform the date to the given time zone. If @a noDST is @true, no DST
+        adjustments will be made.
+
+        @returns The date in the new time zone.
     */
-    wxDateTime ResetTime();
+    wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
 
     /**
-        Sets the date and time from the parameters.
+        This is the same as calling ToTimezone() with the argument @c GMT0.
     */
-    wxDateTime Set(wxDateTime_t day, Month month = Inv_Month,
-                   int year = Inv_Year,
-                   wxDateTime_t hour = 0,
-                   wxDateTime_t minute = 0,
-                   wxDateTime_t second = 0,
-                   wxDateTime_t millisec = 0);
+    wxDateTime ToUTC(bool noDST = false) const;
+
+    //@}
+
+
+
+
 
     /**
-        Sets the country to use by default. This setting influences the DST
-        calculations, date formatting and other things.
-        The possible values for @a country parameter are enumerated in
-        @ref overview_wxdatetime "wxDateTime constants section".
-        
-        @see GetCountry()
+        Converts the year in absolute notation (i.e. a number which can be
+        negative, positive or zero) to the year in BC/AD notation. For the
+        positive years, nothing is done, but the year 0 is year 1 BC and so for
+        other years there is a difference of 1.
+
+        This function should be used like this:
+
+        @code
+        wxDateTime dt(...);
+        int y = dt.GetYear();
+        printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
+        @endcode
     */
-    static void SetCountry(Country country);
+    static int ConvertYearToBC(int year);
 
     /**
-        Sets the day without changing other date components.
+        Returns the translations of the strings @c AM and @c PM used for time
+        formatting for the current locale. Either of the pointers may be @NULL
+        if the corresponding value is not needed.
     */
-    wxDateTime SetDay(wxDateTime_t day);
+    static void GetAmPmStrings(wxString* am, wxString* pm);
 
     /**
-        Sets the date from the date and time in
-        DOS
-        format.
+        Get the beginning of DST for the given country in the given year
+        (current one by default). This function suffers from limitations
+        described in the @ref overview_datetime_dst "DST overview".
+
+        @see GetEndDST()
     */
-    wxDateTime Set(unsigned long ddt);
+    static wxDateTime GetBeginDST(int year = Inv_Year,
+                                   Country country = Country_Default);
 
     /**
-        Sets the hour without changing other date components.
+        Returns the end of DST for the given country in the given year (current
+        one by default).
+
+        @see GetBeginDST()
     */
-    wxDateTime SetHour(wxDateTime_t hour);
+    static wxDateTime GetEndDST(int year = Inv_Year,
+                                 Country country = Country_Default);
 
     /**
-        Sets the millisecond without changing other date components.
+        Get the current century, i.e. first two digits of the year, in given
+        calendar (only Gregorian is currently supported).
     */
-    wxDateTime SetMillisecond(wxDateTime_t millisecond);
+    static int GetCentury(int year);
 
     /**
-        Sets the minute without changing other date components.
+        Returns the current default country. The default country is used for
+        DST calculations, for example.
+
+        @see SetCountry()
     */
-    wxDateTime SetMinute(wxDateTime_t minute);
+    static Country GetCountry();
 
     /**
-        Sets the month without changing other date components.
+        Get the current month in given calendar (only Gregorian is currently
+        supported).
     */
-    wxDateTime SetMonth(Month month);
+    static Month GetCurrentMonth(Calendar cal = Gregorian);
 
     /**
-        Sets the second without changing other date components.
+        Get the current year in given calendar (only Gregorian is currently
+        supported).
     */
-    wxDateTime SetSecond(wxDateTime_t second);
+    static int GetCurrentYear(Calendar cal = Gregorian);
 
     /**
-        Sets the date and time of to the current values. Same as assigning the result
-        of Now() to this object.
+        Gets the full (default) or abbreviated (specify @c Name_Abbr name of
+        the given month.
+
+        @see GetWeekDayName()
     */
-    wxDateTime SetToCurrent();
+    static wxString GetMonthName(Month month, NameFlags flags = Name_Full);
 
     /**
-        Sets the date to the last day in the specified month (the current one by
-        default).
-        Returns the reference to the modified object itself.
+        Returns the number of days in the given year. The only supported value
+        for @a cal currently is @c Gregorian.
+
+        @beginWxPythonOnly
+        This method is named "GetNumberOfDaysInYear" in wxPython.
+        @endWxPythonOnly
     */
-    wxDateTime SetToLastMonthDay(Month month = Inv_Month,
-                                 int year = Inv_Year);
+    static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
 
     /**
-        The effect of calling this function is the same as of calling
-        @c SetToWeekDay(-1, weekday, month, year). The date will be set to the last
-        @a weekday in the given month and year (the current ones by default).
-        Always returns @true.
+        Returns the number of days in the given month of the given year. The
+        only supported value for @a cal currently is @c Gregorian.
+
+        @beginWxPythonOnly
+        This method is named "GetNumberOfDaysInMonth" in wxPython.
+        @endWxPythonOnly
     */
-    bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
-                          int year = Inv_Year);
+    static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
+                                        Calendar cal = Gregorian);
 
     /**
-        Sets the date so that it will be the first @a weekday following the current
-        date.
-        Returns the reference to the modified object itself.
+        Returns the current time.
     */
-    wxDateTime SetToNextWeekDay(WeekDay weekday);
+    static time_t GetTimeNow();
 
     /**
-        Sets the date so that it will be the last @a weekday before the current
-        date.
-        Returns the reference to the modified object itself.
+        Returns the current time broken down using the buffer whose adress is
+        passed to the function with @a tm to store the result.
     */
-    wxDateTime SetToPrevWeekDay(WeekDay weekday);
+    static struct tm* GetTmNow(struct tm *tm);
 
     /**
-        Sets the date to the @e n-th @a weekday in the given month of the given
-        year (the current month and year are used by default). The parameter @e n
-        may be either positive (counting from the beginning of the month) or negative
-        (counting from the end of it).
-        For example, @c SetToWeekDay(2, wxDateTime::Wed) will set the date to the
-        second Wednesday in the current month and
-        @c SetToWeekDay(-1, wxDateTime::Sun) -- to the last Sunday in it.
-        Returns @true if the date was modified successfully, @false
-        otherwise meaning that the specified date doesn't exist.
+        Returns the current time broken down. Note that this function returns a
+        pointer to a static buffer that's reused by calls to this function and
+        certain C library functions (e.g. localtime). If there is any chance
+        your code might be used in a multi-threaded application, you really
+        should use GetTmNow(struct tm *) instead.
     */
-    bool SetToWeekDay(WeekDay weekday, int n = 1,
-                      Month month = Inv_Month,
-                      int year = Inv_Year);
+    static struct tm* GetTmNow();
 
     /**
-        Adjusts the date so that it will still lie in the same week as before, but its
-        week day will be the given one.
-        Returns the reference to the modified object itself.
+        Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
+        the given week day.
+
+        @see GetMonthName()
     */
-    wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
-                                      WeekFlags flags = Monday_First);
+    static wxString GetWeekDayName(WeekDay weekday,
+                                    NameFlags flags = Name_Full);
 
     /**
-        Set the date to the given @a weekday in the week number @a numWeek of the
-        given @a year . The number should be in range 1...53.
-        Note that the returned date may be in a different year than the one passed to
-        this function because both the week 1 and week 52 or 53 (for leap years)
-        contain days from different years. See
-        GetWeekOfYear() for the explanation of how the
-        year weeks are counted.
+        Returns @true if DST was used n the given year (the current one by
+        default) in the given country.
     */
-    static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
-                                      WeekDay weekday = Mon);
+    static bool IsDSTApplicable(int year = Inv_Year,
+                                  Country country = Country_Default);
 
     /**
-        Sets the date to the day number @a yday in the same year (i.e., unlike the
-        other functions, this one does not use the current year). The day number
-        should be in the range 1...366 for the leap years and 1...365 for
-        the other ones.
-        Returns the reference to the modified object itself.
+        Returns @true if the @a year is a leap one in the specified calendar.
+        This functions supports Gregorian and Julian calendars.
     */
-    wxDateTime SetToYearDay(wxDateTime_t yday);
+    static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian);
 
     /**
-        Sets the year without changing other date components.
-    */
-    wxDateTime SetYear(int year);
-
-    /**
-        For convenience, all static functions are collected here. These functions
-        either set or return the static variables of wxDateSpan (the country), return
-        the current moment, year, month or number of days in it, or do some general
-        calendar-related actions.
-        Please note that although several function accept an extra @e Calendar
-        parameter, it is currently ignored as only the Gregorian calendar is
-        supported. Future versions will support other calendars.
-        
-        SetCountry()
-        
-        GetCountry()
-        
-        IsWestEuropeanCountry()
-        
-        GetCurrentYear()
-        
-        ConvertYearToBC()
-        
-        GetCurrentMonth()
-        
-        IsLeapYear()
-        
-        @ref getcenturystatic() GetCentury
-        
-        GetNumberOfDays()
-        
-        GetNumberOfDays()
-        
-        GetMonthName()
-        
-        GetWeekDayName()
-        
-        GetAmPmStrings()
-        
-        IsDSTApplicable()
-        
-        GetBeginDST()
-        
-        GetEndDST()
-        
-        Now()
-        
-        UNow()
-        
-        Today()
-    */
-
-
-    /**
-        Subtracts another date from this one and returns the difference between them
-        as wxTimeSpan.
+        This function returns @true if the specified (or default) country is
+        one of Western European ones. It is used internally by wxDateTime to
+        determine the DST convention and date and time formatting rules.
     */
-    wxTimeSpan Subtract(const wxDateTime& dt) const;
+    static bool IsWestEuropeanCountry(Country country = Country_Default);
 
     /**
-        Please see the @ref overview_tdatetimezones "time zone overview" for more
-        information about time zones. Normally, these functions should be rarely used.
-        FromTimezone()
-        
-        ToTimezone()
-        
-        MakeTimezone()
-        
-        MakeFromTimezone()
-        
-        ToUTC()
-        
-        MakeUTC()
-        
-        GetBeginDST()
-        
-        GetEndDST()
-        
-        IsDST()
-    */
+        Returns the object corresponding to the current time.
+
+        Example:
+
+        @code
+        wxDateTime now = wxDateTime::Now();
+        printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
+        @endcode
+
+        @note This function is accurate up to seconds. UNow() should be used
+              for better precision, but it is less efficient and might not be
+              available on all platforms.
 
+        @see Today()
+    */
+    static wxDateTime Now();
 
     /**
-        Transform the date to the given time zone. If @a noDST is @true, no
-        DST adjustments will be made.
-        Returns the date in the new time zone.
+        Sets the country to use by default. This setting influences the DST
+        calculations, date formatting and other things.
+
+        The possible values for @a country parameter are enumerated in the
+        @ref datetime_constants section.
+
+        @see GetCountry()
     */
-    wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
+    static void SetCountry(Country country);
 
     /**
-        This is the same as calling ToTimezone() with
-        the argument @c GMT0.
+        Set the date to the given @a weekday in the week number @a numWeek of
+        the given @a year . The number should be in range 1-53.
+
+        Note that the returned date may be in a different year than the one
+        passed to this function because both the week 1 and week 52 or 53 (for
+        leap years) contain days from different years. See GetWeekOfYear() for
+        the explanation of how the year weeks are counted.
     */
-    wxDateTime ToUTC(bool noDST = false) const;
+    static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
+                                       WeekDay weekday = Mon);
 
     /**
-        Returns the object corresponding to the midnight of the current day (i.e. the
-        same as Now(), but the time part is set to 0).
-        
+        Returns the object corresponding to the midnight of the current day
+        (i.e. the same as Now(), but the time part is set to 0).
+
         @see Now()
     */
     static wxDateTime Today();
 
     /**
         Returns the object corresponding to the current time including the
-        milliseconds if a function to get time with such precision is available on the
-        current platform (supported under most Unices and Win32).
-        
+        milliseconds if a function to get time with such precision is available
+        on the current platform (supported under most Unices and Win32).
+
         @see Now()
     */
     static wxDateTime UNow();
-
-    /**
-        Same as @ref settm() Set.
-    */
-    wxDateTime operator(const struct tm& tm);
 };
 
+/**
+    Global instance of an empty wxDateTime object.
+
+    @todo Would it be better to rename this wxNullDateTime so it's consistent
+          with the rest of the "empty/invalid/null" global objects?
+*/
+const wxDateTime wxDefaultDateTime;
+
+
 
 /**
     @class wxDateTimeWorkDays
     @wxheader{datetime.h}
 
+    @todo Write wxDateTimeWorkDays documentation.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{data}
 */
 class wxDateTimeWorkDays
 {
@@ -1168,6 +1486,7 @@ public:
 };
 
 
+
 /**
     @class wxDateSpan
     @wxheader{datetime.h}
@@ -1183,94 +1502,94 @@ public:
     Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
 
     Because of this feature, adding and subtracting back again the same
-    wxDateSpan will @b not, in general give back the original date: Feb 28 - 1
+    wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
     month will be Jan 28, not Jan 31!
 
     wxDateSpan objects can be either positive or negative. They may be
     multiplied by scalars which multiply all deltas by the scalar: i.e.
-    2*(1  month and  1  day) is 2 months and 2 days. They can
-    be added together and with wxDateTime or
-    wxTimeSpan, but the type of result is different for each
+    2*(1  month and  1  day) is 2 months and 2 days. They can be added together
+    with wxDateTime or wxTimeSpan, but the type of result is different for each
     case.
 
-    Beware about weeks: if you specify both weeks and days, the total number of
-    days added will be 7*weeks + days! See also GetTotalDays()
-    function.
+    @warning If you specify both weeks and days, the total number of days added
+             will be 7*weeks + days! See also GetTotalDays().
 
-    Equality operators are defined for wxDateSpans. Two datespans are equal if
-    and only if they both give the same target date when added to @b every
-    source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30),
-    because they don't give the same date when added to 1 Feb. But
-    wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2)
+    Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
+    if and only if they both give the same target date when added to @b every
+    source date. Thus wxDateSpan::Months(1) is not equal to
+    wxDateSpan::Days(30), because they don't give the same date when added to
+    Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
 
-    Finally, notice that for adding hours, minutes and so on you don't need this
-    class at all: wxTimeSpan will do the job because there
-    are no subtleties associated with those (we don't support leap seconds).
+    Finally, notice that for adding hours, minutes and so on you don't need
+    this class at all: wxTimeSpan will do the job because there are no
+    subtleties associated with those (we don't support leap seconds).
 
     @library{wxbase}
     @category{data}
 
-    @seealso
-    @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime
+    @see @ref overview_datetime, wxDateTime
 */
 class wxDateSpan
 {
 public:
     /**
-        Constructs the date span object for the given number of years, months, weeks
-        and days. Note that the weeks and days add together if both are given.
+        Constructs the date span object for the given number of years, months,
+        weeks and days. Note that the weeks and days add together if both are
+        given.
     */
-    wxDateSpan(int years = 0, int months = 0, int weeks = 0,
-               int days = 0);
+    wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0);
 
-    //@{
     /**
-        Returns the sum of two date spans. The first version returns a new object, the
-        second and third ones modify this object in place.
+        Returns the sum of two date spans.
+
+        @returns A new wxDateSpan object with the result.
     */
-    wxDateSpan Add(const wxDateSpan& other);
-    const wxDateSpan&  Add(const wxDateSpan& other);
-    wxDateSpan operator+=(const wxDateSpan& other);
-    //@}
+    wxDateSpan Add(const wxDateSpan& other) const;
+    /**
+        Adds the given wxDateSpan to this wxDateSpan and returns a reference
+        to itself.
+    */
+    wxDateSpan& Add(const wxDateSpan& other);
 
     /**
         Returns a date span object corresponding to one day.
-        
+
         @see Days()
     */
     static wxDateSpan Day();
 
     /**
         Returns a date span object corresponding to the given number of days.
-        
+
         @see Day()
     */
     static wxDateSpan Days(int days);
 
     /**
-        Returns the number of days (only, that it not counting the weeks component!)
-        in this date span.
-        
+        Returns the number of days (not counting the weeks component) in this
+        date span.
+
         @see GetTotalDays()
     */
     int GetDays() const;
 
     /**
-        Returns the number of the months (not counting the years) in this date span.
+        Returns the number of the months (not counting the years) in this date
+        span.
     */
     int GetMonths() const;
 
     /**
-        Returns the combined number of days in this date span, counting both weeks and
-        days. It still doesn't take neither months nor years into the account.
-        
+        Returns the combined number of days in this date span, counting both
+        weeks and days. This doesn't take months or years into account.
+
         @see GetWeeks(), GetDays()
     */
     int GetTotalDays() const;
 
     /**
         Returns the number of weeks in this date span.
-        
+
         @see GetTotalDays()
     */
     int GetWeeks() const;
@@ -1282,123 +1601,154 @@ public:
 
     /**
         Returns a date span object corresponding to one month.
-        
+
         @see Months()
     */
     static wxDateSpan Month();
 
     /**
         Returns a date span object corresponding to the given number of months.
-        
+
         @see Month()
     */
     static wxDateSpan Months(int mon);
 
-    //@{
     /**
-        Returns the product of the date span by the specified @e factor. The
-        product is computed by multiplying each of the components by the factor.
-        The first version returns a new object, the second and third ones modify this
-        object in place.
+        Returns the product of the date span by the specified @a factor. The
+        product is computed by multiplying each of the components by the
+        @a factor.
+
+        @returns A new wxDateSpan object with the result.
     */
-    wxDateSpan Multiply(int factor);
-    const wxDateSpan&  Multiply(int factor);
-    wxDateSpan operator*=(int factor);
-    //@}
+    wxDateSpan Multiply(int factor) const;
+    /**
+        Multiplies this date span by the specified @a factor. The product is
+        computed by multiplying each of the components by the @a factor.
+
+        @returns A reference to this wxDateSpan object modified in place.
+    */
+    wxDateSpan& Multiply(int factor);
 
-    //@{
     /**
         Changes the sign of this date span.
-        
+
         @see Negate()
     */
-    wxDateSpan Neg();
-    wxDateSpan operator-();
-    //@}
+    wxDateSpan& Neg();
 
     /**
-        Returns the date span with the opposite sign.
-        
+        Returns a date span with the opposite sign.
+
         @see Neg()
     */
     wxDateSpan Negate() const;
 
     /**
-        Sets the number of days (without modifying any other components) in this date
-        span.
+        Sets the number of days (without modifying any other components) in
+        this date span.
     */
-    wxDateSpan SetDays(int n);
+    wxDateSpan& SetDays(int n);
 
     /**
-        Sets the number of months (without modifying any other components) in this
-        date span.
+        Sets the number of months (without modifying any other components) in
+        this date span.
     */
-    wxDateSpan SetMonths(int n);
+    wxDateSpan& SetMonths(int n);
 
     /**
-        Sets the number of weeks (without modifying any other components) in this date
-        span.
+        Sets the number of weeks (without modifying any other components) in
+        this date span.
     */
-    wxDateSpan SetWeeks(int n);
+    wxDateSpan& SetWeeks(int n);
 
     /**
-        Sets the number of years (without modifying any other components) in this date
-        span.
+        Sets the number of years (without modifying any other components) in
+        this date span.
     */
-    wxDateSpan SetYears(int n);
+    wxDateSpan& SetYears(int n);
 
-    //@{
     /**
-        Returns the difference of two date spans. The first version returns a new
-        object, the second and third ones modify this object in place.
+        Returns the difference of two date spans.
+
+        @returns A new wxDateSpan object with the result.
     */
-    wxDateSpan Subtract(const wxDateSpan& other);
-    const wxDateSpan&  Subtract(const wxDateSpan& other);
-    wxDateSpan operator+=(const wxDateSpan& other);
-    //@}
+    wxDateSpan Subtract(const wxDateSpan& other) const;
+    /**
+        Subtracts the given wxDateSpan to this wxDateSpan and returns a
+        reference to itself.
+    */
+    wxDateSpan& Subtract(const wxDateSpan& other);
 
     /**
         Returns a date span object corresponding to one week.
-        
+
         @see Weeks()
     */
     static wxDateSpan Week();
 
     /**
         Returns a date span object corresponding to the given number of weeks.
-        
+
         @see Week()
     */
     static wxDateSpan Weeks(int weeks);
 
     /**
         Returns a date span object corresponding to one year.
-        
+
         @see Years()
     */
     static wxDateSpan Year();
 
     /**
         Returns a date span object corresponding to the given number of years.
-        
+
         @see Year()
     */
     static wxDateSpan Years(int years);
 
+    /**
+        Adds the given wxDateSpan to this wxDateSpan and returns the result.
+    */
+    wxDateSpan& operator+=(const wxDateSpan& other);
+
+    /**
+        Subtracts the given wxDateSpan to this wxDateSpan and returns the
+        result.
+    */
+    wxDateSpan& operator-=(const wxDateSpan& other);
+
+    /**
+        Changes the sign of this date span.
+
+        @see Negate()
+    */
+    wxDateSpan& operator-();
+
+    /**
+        Multiplies this date span by the specified @a factor. The product is
+        computed by multiplying each of the components by the @a factor.
+
+        @returns A reference to this wxDateSpan object modified in place.
+    */
+    wxDateSpan& operator*=(int factor);
+
     /**
         Returns @true if this date span is different from the other one.
     */
-    bool operator!=(wxDateSpan& other) const;
+    bool operator!=(const wxDateSpan&) const;
 
     /**
-        Returns @true if this date span is equal to the other one. Two date spans
-        are considered equal if and only if they have the same number of years and
-        months and the same total number of days (counting both days and weeks).
+        Returns @true if this date span is equal to the other one. Two date
+        spans are considered equal if and only if they have the same number of
+        years and months and the same total number of days (counting both days
+        and weeks).
     */
-    bool operator==(wxDateSpan& other) const;
+    bool operator==(const wxDateSpan&) const;
 };
 
 
+
 /**
     @class wxTimeSpan
     @wxheader{datetime.h}
@@ -1408,56 +1758,38 @@ public:
     @library{wxbase}
     @category{data}
 
-    @seealso
-    @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime
+    @see @ref overview_datetime, wxDateTime
 */
 class wxTimeSpan
 {
 public:
-    //@{
     /**
-        Constructs timespan from separate values for each component, with the date
-        set to 0. Hours are not restricted to 0..24 range, neither are
-        minutes, seconds or milliseconds.
+        Default constructor, constructs a zero timespan.
     */
     wxTimeSpan();
+    /**
+        Constructs timespan from separate values for each component, with the
+        date set to 0. Hours are not restricted to 0-24 range, neither are
+        minutes, seconds or milliseconds.
+    */
     wxTimeSpan(long hours, long min, long sec, long msec);
-    //@}
 
     /**
-        Returns the absolute value of the timespan: does not modify the
-        object.
+        Returns the absolute value of the timespan: does not modify the object.
     */
     wxTimeSpan Abs() const;
 
     /**
-        GetSeconds()
-        
-        GetMinutes()
-        
-        GetHours()
-        
-        GetDays()
-        
-        GetWeeks()
-        
-        GetValue()
-    */
+        Returns the sum of two time spans.
 
-
-    //@{
-    /**
-        Returns the sum of two timespans.
+        @returns A new wxDateSpan object with the result.
     */
-    wxTimeSpan Add(const wxTimeSpan& diff);
-    const wxTimeSpan&  Add(const wxTimeSpan& diff);
-    wxTimeSpan operator+=(const wxTimeSpan& diff);
-    //@}
-
+    wxTimeSpan Add(const wxTimeSpan& diff) const;
     /**
-        @ref ctor() wxTimeSpan
+        Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
+        to itself.
     */
-
+    wxTimeSpan& Add(const wxTimeSpan& diff);
 
     /**
         Returns the timespan for one day.
@@ -1470,54 +1802,32 @@ public:
     static wxTimespan Days(long days);
 
     /**
-        Returns the string containing the formatted representation of the time span.
-        The following format specifiers are allowed after %:
-        
-        H
-        
-        number of @b Hours
-        
-        M
-        
-        number of @b Minutes
-        
-        S
-        
-        number of @b Seconds
-        
-        l
-        
-        number of mi@b lliseconds
-        
-        D
-        
-        number of @b Days
-        
-        E
-        
-        number of w@b Eeks
-        
-        %
-        
-        the percent character
-        
-        Note that, for example, the number of hours in the description above is not
-        well defined: it can be either the total number of hours (for example, for a
-        time span of 50 hours this would be 50) or just the hour part of the time
-        span, which would be 2 in this case as 50 hours is equal to 2 days and
-        2 hours.
-        wxTimeSpan resolves this ambiguity in the following way: if there had been,
-        indeed, the @c %D format specified preceding the @c %H, then it is
-        interpreted as 2. Otherwise, it is 50.
-        The same applies to all other format specifiers: if they follow a specifier of
-        larger unit, only the rest part is taken, otherwise the full value is used.
-    */
-    wxString Format(const wxChar* format = wxDefaultTimeSpanFormat);
-
-    /**
-        Format()
-    */
+        Returns the string containing the formatted representation of the time
+        span. The following format specifiers are allowed after %:
+
+        - @c H - Number of Hours
+        - @c M - Number of Minutes
+        - @c S - Number of Seconds
+        - @c l - Number of Milliseconds
+        - @c D - Number of Days
+        - @c E - Number of Weeks
+        - @c % - The percent character
+
+        Note that, for example, the number of hours in the description above is
+        not well defined: it can be either the total number of hours (for
+        example, for a time span of 50 hours this would be 50) or just the hour
+        part of the time span, which would be 2 in this case as 50 hours is
+        equal to 2 days and 2 hours.
+
+        wxTimeSpan resolves this ambiguity in the following way: if there had
+        been, indeed, the @c %D format specified preceding the @c %H, then it
+        is interpreted as 2. Otherwise, it is 50.
 
+        The same applies to all other format specifiers: if they follow a
+        specifier of larger unit, only the rest part is taken, otherwise the
+        full value is used.
+    */
+    wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
 
     /**
         Returns the difference in number of days.
@@ -1570,9 +1880,9 @@ public:
     bool IsEqualTo(const wxTimeSpan& ts) const;
 
     /**
-        Compares two timespans: works with the absolute values, i.e. -2
-        hours is longer than 1 hour. Also, it will return @false if
-        the timespans are equal in absolute value.
+        Compares two timespans: works with the absolute values, i.e. -2 hours
+        is longer than 1 hour. Also, it will return @false if the timespans are
+        equal in absolute value.
     */
     bool IsLongerThan(const wxTimeSpan& ts) const;
 
@@ -1592,9 +1902,9 @@ public:
     bool IsPositive() const;
 
     /**
-        Compares two timespans: works with the absolute values, i.e. 1
-        hour is shorter than -2 hours. Also, it will return @false if
-        the timespans are equal in absolute value.
+        Compares two timespans: works with the absolute values, i.e. 1 hour is
+        shorter than -2 hours. Also, it will return @false if the timespans are
+        equal in absolute value.
     */
     bool IsShorterThan(const wxTimeSpan& ts) const;
 
@@ -1618,42 +1928,32 @@ public:
     */
     static wxTimespan Minutes(long min);
 
-    //@{
     /**
-        Multiplies timespan by a scalar.
+        Returns the product of this time span by @a n.
+
+        @returns A new wxTimeSpan object with the result.
     */
-    wxTimeSpan Multiply(int n);
-    const wxTimeSpan&  Multiply(int n);
-    wxTimeSpan operator*=(int n);
-    //@}
+    wxTimeSpan Multiply(int n) const;
+    /**
+        Multiplies this time span by @a n.
+
+        @returns A reference to this wxTimeSpan object modified in place.
+    */
+    wxTimeSpan& Multiply(int n);
 
-    //@{
     /**
         Negate the value of the timespan.
+
+        @see Negate()
     */
-    wxTimeSpan Neg();
-    wxTimeSpan operator-();
-    //@}
+    wxTimeSpan& Neg();
 
     /**
         Returns timespan with inverted sign.
-    */
-    wxTimeSpan Negate() const;
 
-    /**
-        Add()
-        
-        Subtract()
-        
-        Multiply()
-        
-        Negate()
-        
-        Neg()
-        
-        Abs()
+        @see Neg()
     */
-
+    wxTimeSpan Negate() const;
 
     /**
         Returns the timespan for one second.
@@ -1666,78 +1966,67 @@ public:
     static wxTimespan Seconds(long sec);
 
     /**
-        Milliseconds()
-        
-        Millisecond()
-        
-        Seconds()
-        
-        Second()
-        
-        Minutes()
-        
-        Minute()
-        
-        Hours()
-        
-        Hour()
-        
-        Days()
-        
-        Day()
-        
-        Weeks()
-        
-        Week()
+        Returns the difference of two time spans.
+
+        @returns A new wxDateSpan object with the result.
+    */
+    wxTimeSpan Subtract(const wxTimeSpan& diff) const;
+    /**
+        Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
+        reference to itself.
     */
+    wxTimeSpan& Subtract(const wxTimeSpan& diff);
 
+    /**
+        Returns the timespan for one week.
+    */
+    static wxTimespan Week();
 
-    //@{
     /**
-        Returns the difference of two timespans.
+        Returns the timespan for the given number of weeks.
     */
-    wxTimeSpan Subtract(const wxTimeSpan& diff);
-    const wxTimeSpan&  Subtract(const wxTimeSpan& diff);
-    wxTimeSpan operator-=(const wxTimeSpan& diff);
-    //@}
+    static wxTimespan Weeks(long weeks);
 
     /**
-        IsNull()
-        
-        IsPositive()
-        
-        IsNegative()
-        
-        IsEqualTo()
-        
-        IsLongerThan()
-        
-        IsShorterThan()
+        Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
     */
+    wxTimeSpan& operator+=(const wxTimeSpan& diff);
 
+    /**
+        Multiplies this time span by @a n.
+
+        @returns A reference to this wxTimeSpan object modified in place.
+    */
+    wxTimeSpan& operator*=(int n);
 
     /**
-        Returns the timespan for one week.
+        Negate the value of the timespan.
+
+        @see Negate()
     */
-    static wxTimespan Week();
+    wxTimeSpan& operator-();
 
     /**
-        Returns the timespan for the given number of weeks.
+        Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
+        result.
     */
-    static wxTimespan Weeks(long weeks);
+    wxTimeSpan& operator-=(const wxTimeSpan& diff);
 };
 
 
+
 /**
     @class wxDateTimeHolidayAuthority
     @wxheader{datetime.h}
 
+    @todo Write wxDateTimeHolidayAuthority documentation.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{misc}
 */
 class wxDateTimeHolidayAuthority
 {
 public:
 
 };
+