Better documentation for the default parameters values.

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

diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index e7ebd8d9470958101b95b9e29bac16b95f8e19e1..b517d4d882081ed110fb6031b0da5fd7a737d56b 100644 (file)
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -9,7 +9,7 @@
 /**
     @class wxDateTime
 
 /**
     @class wxDateTime
 

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

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


@@ -170,6 +170,128 @@ public:
         Julian      ///< calendar in use since -45 until the 1582 (or later)
     };
 
         Julian      ///< calendar in use since -45 until the 1582 (or later)
     };
 

+    /**
+        Values corresponding to different dates of adoption of the Gregorian
+        calendar.
+
+        @see IsGregorianDate
+     */
+    enum GregorianAdoption
+    {
+        Gr_Unknown,    ///< no data for this country or it's too uncertain to use
+        Gr_Standard,   ///< on the day 0 of Gregorian calendar: 15 Oct 1582
+
+        Gr_Alaska,             ///< Oct 1867 when Alaska became part of the USA
+        Gr_Albania,            ///< Dec 1912
+
+        Gr_Austria = Gr_Unknown,    ///< Different regions on different dates
+        Gr_Austria_Brixen,          ///< 5 Oct 1583 -> 16 Oct 1583
+        Gr_Austria_Salzburg = Gr_Austria_Brixen,
+        Gr_Austria_Tyrol = Gr_Austria_Brixen,
+        Gr_Austria_Carinthia,       ///< 14 Dec 1583 -> 25 Dec 1583
+        Gr_Austria_Styria = Gr_Austria_Carinthia,
+
+        Gr_Belgium,            ///< Then part of the Netherlands
+
+        Gr_Bulgaria = Gr_Unknown, ///< Unknown precisely (from 1915 to 1920)
+        Gr_Bulgaria_1,         ///<      18 Mar 1916 -> 1 Apr 1916
+        Gr_Bulgaria_2,         ///<      31 Mar 1916 -> 14 Apr 1916
+        Gr_Bulgaria_3,         ///<      3 Sep 1920 -> 17 Sep 1920
+
+        Gr_Canada = Gr_Unknown,   ///< Different regions followed the changes in
+                               ///< Great Britain or France
+
+        Gr_China = Gr_Unknown,    ///< Different authorities say:
+        Gr_China_1,            ///<      18 Dec 1911 -> 1 Jan 1912
+        Gr_China_2,            ///<      18 Dec 1928 -> 1 Jan 1929
+
+        Gr_Czechoslovakia,     ///< (Bohemia and Moravia) 6 Jan 1584 -> 17 Jan 1584
+        Gr_Denmark,            ///< (including Norway) 18 Feb 1700 -> 1 Mar 1700
+        Gr_Egypt,              ///< 1875
+        Gr_Estonia,            ///< 1918
+        Gr_Finland,            ///< Then part of Sweden
+
+        Gr_France,             ///< 9 Dec 1582 -> 20 Dec 1582
+        Gr_France_Alsace,      ///<      4 Feb 1682 -> 16 Feb 1682
+        Gr_France_Lorraine,    ///<      16 Feb 1760 -> 28 Feb 1760
+        Gr_France_Strasbourg,  ///< February 1682
+
+        Gr_Germany = Gr_Unknown,  ///< Different states on different dates:
+        Gr_Germany_Catholic,   ///<      1583-1585 (we take 1584)
+        Gr_Germany_Prussia,    ///<      22 Aug 1610 -> 2 Sep 1610
+        Gr_Germany_Protestant, ///<      18 Feb 1700 -> 1 Mar 1700
+
+        Gr_GreatBritain,       ///< 2 Sep 1752 -> 14 Sep 1752 (use 'cal(1)')
+
+        Gr_Greece,             ///< 9 Mar 1924 -> 23 Mar 1924
+        Gr_Hungary,            ///< 21 Oct 1587 -> 1 Nov 1587
+        Gr_Ireland = Gr_GreatBritain,
+        Gr_Italy = Gr_Standard,
+
+        Gr_Japan = Gr_Unknown,    ///< Different authorities say:
+        Gr_Japan_1,            ///<      19 Dec 1872 -> 1 Jan 1873
+        Gr_Japan_2,            ///<      19 Dec 1892 -> 1 Jan 1893
+        Gr_Japan_3,            ///<      18 Dec 1918 -> 1 Jan 1919
+
+        Gr_Latvia,             ///< 1915-1918 (we take 1915)
+        Gr_Lithuania,          ///< 1915
+        Gr_Luxemburg,          ///< 14 Dec 1582 -> 25 Dec 1582
+        Gr_Netherlands = Gr_Belgium, ///< (including Belgium) 1 Jan 1583
+
+        /**
+            Special case of Groningen.
+
+            The Gregorian calendar was introduced twice in Groningen, first
+            time 28 Feb 1583 was followed by 11 Mar 1583, then it has gone back
+            to Julian in the summer of 1584 and then 13 Dec 1700 was followed
+            by 12 Jan 1701 -- which is the date we take into account here.
+         */
+        Gr_Netherlands_Groningen,  ///< 13 Dec 1700 -> 12 Jan 1701
+        Gr_Netherlands_Gelderland, ///< 30 Jun 1700 -> 12 Jul 1700
+        Gr_Netherlands_Utrecht,    ///< (and Overijssel) 30 Nov 1700->12 Dec 1700
+        Gr_Netherlands_Friesland,  ///< (and Drenthe) 31 Dec 1700 -> 12 Jan 1701
+
+        Gr_Norway = Gr_Denmark,       ///< Then part of Denmark
+        Gr_Poland = Gr_Standard,
+        Gr_Portugal = Gr_Standard,
+        Gr_Romania,                ///< 31 Mar 1919 -> 14 Apr 1919
+        Gr_Russia,                 ///< 31 Jan 1918 -> 14 Feb 1918
+        Gr_Scotland = Gr_GreatBritain,
+        Gr_Spain = Gr_Standard,
+
+        /**
+            Special case of Sweden.
+
+            Sweden has a curious history. Sweden decided to make a gradual
+            change from the Julian to the Gregorian calendar. By dropping every
+            leap year from 1700 through 1740 the eleven superfluous days would
+            be omitted and from 1 Mar 1740 they would be in sync with the
+            Gregorian calendar. (But in the meantime they would be in sync with
+            nobody!)
+
+            So 1700 (which should have been a leap year in the Julian calendar)
+            was not a leap year in Sweden. However, by mistake 1704 and 1708
+            became leap years. This left Sweden out of synchronisation with
+            both the Julian and the Gregorian world, so they decided to go back
+            to the Julian calendar. In order to do this, they inserted an extra
+            day in 1712, making that year a double leap year! So in 1712,
+            February had 30 days in Sweden.
+
+            Later, in 1753, Sweden changed to the Gregorian calendar by
+            dropping 11 days like everyone else and this is what we use here.
+         */
+        Gr_Sweden = Gr_Finland,       ///< 17 Feb 1753 -> 1 Mar 1753
+
+        Gr_Switzerland = Gr_Unknown,///< Different cantons used different dates
+        Gr_Switzerland_Catholic,    ///<      1583, 1584 or 1597 (we take 1584)
+        Gr_Switzerland_Protestant,  ///<      31 Dec 1700 -> 12 Jan 1701
+
+        Gr_Turkey,                 ///< 1 Jan 1927
+        Gr_USA = Gr_GreatBritain,
+        Gr_Wales = Gr_GreatBritain,
+        Gr_Yugoslavia              ///< 1919
+    };
+

     /**
         Date calculations often depend on the country and wxDateTime allows to set
         the country whose conventions should be used using SetCountry(). It takes
     /**
         Date calculations often depend on the country and wxDateTime allows to set
         the country whose conventions should be used using SetCountry(). It takes


@@ -244,6 +366,27 @@ public:
     };
 
 
     };
 
 

+    /**
+        Class representing a time zone.
+
+        The representation is simply the offset, in seconds, from UTC.
+     */
+    class WXDLLIMPEXP_BASE TimeZone
+    {
+    public:
+        /// Constructor for a named time zone.
+        TimeZone(TZ tz);
+
+        /// Constructor for the given offset in seconds.
+        TimeZone(long offset = 0);
+
+        /// Create a time zone with the given offset in seconds.
+        static TimeZone Make(long offset);
+
+        /// Return the offset of this time zone from UTC, in seconds.
+        long GetOffset() const;
+    };
+

     /**
         Contains broken down date-time representation.
 
     /**
         Contains broken down date-time representation.
 


@@ -295,6 +438,12 @@ public:
         object later.
     */
     wxDateTime();
         object later.
     */
     wxDateTime();

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

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


@@ -333,7 +482,7 @@ public:
         This constructor is named "wxDateTimeFromDMY" in wxPython.
         @endWxPythonOnly
     */
         This constructor is named "wxDateTimeFromDMY" in wxPython.
         @endWxPythonOnly
     */

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

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


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

+        @onlyfor{wxmsw}

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


@@ -370,6 +520,13 @@ public:
         @beginWxPythonOnly Unsupported. @endWxPythonOnly
     */
     wxDateTime& Set(const struct tm& tm);
         @beginWxPythonOnly Unsupported. @endWxPythonOnly
     */
     wxDateTime& Set(const struct tm& tm);

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

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


@@ -396,7 +553,7 @@ public:
     /**
         Sets the date and time from the parameters.
     */
     /**
         Sets the date and time from the parameters.
     */

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

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


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

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

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


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

+        @onlyfor{wxmsw}

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


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

+        @onlyfor{wxmsw}

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


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

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

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

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

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

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

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

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

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

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

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


@@ -541,7 +700,7 @@ public:
     /**
         Returns the seconds in the given timezone (local one by default).
     */
     /**
         Returns the seconds in the given timezone (local one by default).
     */

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

 
     /**
         Returns the number of seconds since Jan 1, 1970. An assert failure will
 
     /**
         Returns the number of seconds since Jan 1, 1970. An assert failure will


@@ -761,7 +920,7 @@ public:
     /**
         Adds the given date span to this object.
     */
     /**
         Adds the given date span to this object.
     */

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

     /**
         Subtracts the given date span from this object.
     */
     /**
         Subtracts the given date span from this object.
     */


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

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

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


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

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

 };
 
 
 };
 
 


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

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

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