]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/datetime.h
don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / datetime.h
index 01e3d676f0c4246f02115898c6ddf2807eb65900..e8eb26d46d23bc69ea7180e9acb117143b36ec30 100644 (file)
     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
+    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
 
 class wxDateTime
 {
 public:
+    /**
+        A small unsigned integer type for storing things like minutes,
+        seconds &c. It should be at least short (i.e. not char) to contain
+        the number of milliseconds - it may also be 'int' because there is
+        no size penalty associated with it in our code, we don't store any
+        data in this format.
+    */
+    typedef unsigned short wxDateTime_t;
+
+
+    /**
+        Time zone symbolic names.
+    */
+    enum TZ
+    {
+        /// 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
+    };
+
+    /**
+        Several functions accept an extra parameter specifying the calendar to use
+        (although most of them only support now the Gregorian calendar). This
+        parameters is one of the following values.
+    */
+    enum Calendar
+    {
+        Gregorian,  ///< calendar currently in use in Western countries
+        Julian      ///< calendar in use since -45 until the 1582 (or later)
+    };
+
+    /**
+        Date calculations often depend on the country and wxDateTime allows to set
+        the country whose conventions should be used using SetCountry(). It takes
+        one of the following values as parameter.
+    */
+    enum Country
+    {
+        Country_Unknown, ///< no special information for this country
+        Country_Default, ///< set the default country with SetCountry() method
+                         ///< or use the default country with any other
+
+        Country_WesternEurope_Start,
+        Country_EEC = Country_WesternEurope_Start,
+        France,
+        Germany,
+        UK,
+        Country_WesternEurope_End = UK,
+
+        Russia,
+
+        USA
+    };
+
+    /// symbolic names for the months
+    enum Month
+    {
+        Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec,
+
+        /// Invalid month value.
+        Inv_Month
+    };
+
+    /// symbolic names for the weekdays
+    enum WeekDay
+    {
+        Sun, Mon, Tue, Wed, Thu, Fri, Sat,
+
+        /// Invalid week day value.
+        Inv_WeekDay
+    };
+
+    /// invalid value for the year
+    enum Year
+    {
+        Inv_Year = SHRT_MIN    // should hold in wxDateTime_t
+    };
+
+    /**
+        Flags to be used with GetMonthName() and GetWeekDayName() functions.
+    */
+    enum NameFlags
+    {
+        Name_Full = 0x01,       ///< return full name
+        Name_Abbr = 0x02        ///< return abbreviated name
+    };
+
+    /**
+        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.
+    */
+    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
+    };
+
+
     /**
         @name Constructors, Assignment Operators and Setters
 
@@ -509,8 +527,7 @@ public:
         Returns the ordinal number of the week in the month (in 1-5 range).
 
         As GetWeekOfYear(), this function supports both conventions for the
-        week start. See the description of these @c WeekFlags in the
-        @ref datetime_constants section.
+        week start.
     */
     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
                                 const TimeZone& tz = Local) const;
@@ -524,10 +541,9 @@ public:
         year. Accordingly, the week number will always be in 1-53 range (52 for
         non-leap years).
 
-        The function depends on the @ref datetime_constants "week start"
-        convention specified by the @a flags argument but its results for
-        @c Sunday_First are not well-defined as the ISO definition quoted above
-        applies to the weeks starting on Monday only.
+        The function depends on the week start convention specified by the @a flags
+        argument but its results for @c Sunday_First are not well-defined as the
+        ISO definition quoted above applies to the weeks starting on Monday only.
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;
@@ -786,49 +802,31 @@ public:
 
     /**
         This function is like ParseDateTime(), but it only allows the date to
-        be specified. It is thus less flexible then ParseDateTime(), but also
-        has less chances to misinterpret the user input.
+        be specified.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+        It is thus less flexible then ParseDateTime(), but also has less
+        chances to misinterpret the user input.
 
-        @see Format()
-    */
-    const char* ParseDate(const wxString& date,
-                           wxString::const_iterator* end = NULL);
+        See ParseFormat() for the description of function parameters and return
+        value.
 
-    /**
-        @overload
-    */
-    const char* ParseDate(const char* date);
-
-    /**
-        @overload
+        @see Format()
     */
-    const wchar_t* ParseDate(const wchar_t* date);
+    bool ParseDate(const wxString& date, wxString::const_iterator *end);
 
     /**
         Parses the string @a datetime containing the date and time in free
-        format. This function tries as hard as it can to interpret the given
-        string as date and time. Unlike ParseRfc822Date(), it will accept
-        anything that may be accepted and will only reject strings which can
-        not be parsed in any way at all.
+        format.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
-    */
-    const char* ParseDateTime(const wxString& datetime,
-                              wxString::const_iterator* end = NULL);
+        This function tries as hard as it can to interpret the given string as
+        date and time. Unlike ParseRfc822Date(), it will accept anything that
+        may be accepted and will only reject strings which can not be parsed in
+        any way at all.
 
-    /**
-        @overload
-    */
-    const char* ParseDateTime(const char* datetime);
-
-    /**
-        @overload
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const wchar_t* ParseDateTime(const wchar_t* datetime);
+    bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);
 
     /**
         This function parses the string @a date according to the given
@@ -849,29 +847,53 @@ public:
         @a dateDef. If it is not specified, Today() is used as the default
         date.
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+        Example of using this function:
+        @code
+            wxDateTime dt;
+            wxString str = "...";
+            wxString::const_iterator end;
+            if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) )
+                ... parsing failed ...
+            else if ( end == str.end() )
+                ... entire string parsed ...
+            else
+                ... wxString(end, str.end()) left over ...
+        @endcode
+
+        @param date
+            The string to be parsed.
+        @param format
+            strptime()-like format string.
+        @param dateDef
+            Used to fill in the date components not specified in the @a date
+            string.
+        @param end
+            Will be filled with the iterator pointing to the location where the
+            parsing stopped if the function returns @true. If the entire string
+            was consumed, it is set to @c date.end(). Notice that this argument
+            must be non-@NULL.
+        @return
+            @true if at least part of the string was parsed successfully,
+            @false otherwise.
 
         @see Format()
     */
-    const char* ParseFormat(const wxString& date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime,
-                            wxString::const_iterator* end = NULL);
+    bool ParseFormat(const wxString& date,
+                     const wxString& format = wxDefaultDateTimeFormat,
+                     const wxDateTime& dateDef = wxDefaultDateTime,
+                     wxString::const_iterator *end);
 
     /**
         @overload
     */
-    const char* ParseFormat(const char* date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime);
+    bool ParseFormat(const wxString& date,
+                     const wxString& format = wxDefaultDateTimeFormat,
+                     wxString::const_iterator *end);
 
     /**
         @overload
     */
-    const wchar_t* ParseFormat(const wchar_t* date,
-                               const wxString& format = wxDefaultDateTimeFormat,
-                               const wxDateTime& dateDef = wxDefaultDateTime);
+    bool ParseFormat(const wxString& date, wxString::const_iterator *end);
 
     /**
         This function parses the string containing the date and time in ISO
@@ -917,39 +939,20 @@ public:
         string which is not RFC 822 compliant. If you need to parse date
         formatted in more free ways, you should use ParseDateTime() or
         ParseDate() instead.
-    */
-    const char* ParseRfc822Date(const wxString& date,
-                                  wxString::const_iterator* end = NULL);
-
-    /**
-        @overload
-    */
-    const char* ParseRfc822Date(const char* date);
 
-    /**
-        @overload
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const wchar_t* ParseRfc822Date(const wchar_t* date);
+    bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
 
     /**
         This functions is like ParseDateTime(), but only allows the time to be
         specified in the input string.
 
-        @return @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);
-
-    /**
-        @overload
+        See ParseFormat() for the description of function parameters and return
+        value.
     */
-    const char* ParseTime(const char* time);
-
-    /**
-        @overload
-    */
-    const wchar_t* ParseTime(const wchar_t* time);
+    bool ParseTime(const wxString& time, wxString::const_iterator *end);
 
     //@}
 
@@ -1265,8 +1268,53 @@ public:
     static int GetCurrentYear(Calendar cal = Gregorian);
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr name of
-        the given month.
+        Return the standard English name of the given month.
+
+        This function always returns "January" or "Jan" for January, use
+        GetMonthName() to retrieve the name of the month in the users current
+        locale.
+
+        @param month
+            One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
+
+        @see GetEnglishWeekDayName()
+
+        @since 2.9.0
+     */
+    static wxString GetEnglishMonthName(Month month,
+                                        NameFlags flags = Name_Full);
+
+    /**
+        Return the standard English name of the given week day.
+
+        This function always returns "Monday" or "Mon" for Monday, use
+        GetWeekDayName() to retrieve the name of the month in the users current
+        locale.
+
+        @param weekday
+            One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
+
+        @see GetEnglishMonthName()
+
+        @since 2.9.0
+     */
+    static wxString GetEnglishWeekDayName(WeekDay weekday,
+                                          NameFlags flags = Name_Full);
+
+    /**
+        Gets the full (default) or abbreviated name of the given month.
+
+        This function returns the name in the current locale, use
+        GetEnglishMonthName() to get the untranslated name if necessary.
+
+        @param month
+            One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
 
         @see GetWeekDayName()
     */
@@ -1314,13 +1362,20 @@ public:
     static tm* GetTmNow();
 
     /**
-        Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
-        the given week day.
+        Gets the full (default) or abbreviated name of the given week day.
+
+        This function returns the name in the current locale, use
+        GetEnglishWeekDayName() to get the untranslated name if necessary.
+
+        @param weekday
+            One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+        @param flags
+            Either Name_Full (default) or Name_Abbr.
 
         @see GetMonthName()
     */
     static wxString GetWeekDayName(WeekDay weekday,
-                                    NameFlags flags = Name_Full);
+                                   NameFlags flags = Name_Full);
 
     /**
         Returns @true if DST was used in the given year (the current one by
@@ -1364,9 +1419,6 @@ public:
         Sets the country to use by default. This setting influences the DST
         calculations, date formatting and other things.
 
-        The possible values for @a country parameter are enumerated in the
-        @ref datetime_constants section.
-
         @see GetCountry()
     */
     static void SetCountry(Country country);