X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c99e2fd1b3432974b892be508c0757da5b6ad49..e777bd14b3b3ce4a601fcc0df63d64e3dc75ae8e:/interface/wx/datetime.h?ds=inline diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index 70cf1c5a89..f28fd2abb3 100644 --- a/interface/wx/datetime.h +++ b/interface/wx/datetime.h @@ -15,152 +15,9 @@ 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 @@ -226,6 +83,167 @@ 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; @@ -736,8 +752,8 @@ public: /** This function does the same as the standard ANSI C @c strftime(3) - function. Please see its description for the meaning of @a format - parameter. + function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html). + Please see its description for the meaning of @a format parameter. It also accepts a few wxWidgets-specific extensions: you can optionally specify the width of the field to follow using @c printf(3)-like syntax @@ -791,25 +807,19 @@ public: @return @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. + + @see Format() */ 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. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const char* ParseDate(const char* date); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const wchar_t* ParseDate(const wchar_t* date); @@ -825,26 +835,14 @@ public: */ 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. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const char* ParseDateTime(const char* datetime); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const wchar_t* ParseDateTime(const wchar_t* datetime); @@ -869,61 +867,27 @@ public: @return @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. + + @see Format() */ 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. + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime, + wxString::const_iterator* end = NULL); - 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. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const char* ParseFormat(const char* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. - - 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. + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const wchar_t* ParseFormat(const wchar_t* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); /** This function parses the string containing the date and time in ISO @@ -972,42 +936,14 @@ public: */ 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. + /** + @overload */ const char* ParseRfc822Date(const char* date); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. + /** + @overload */ const wchar_t* ParseRfc822Date(const wchar_t* date); @@ -1020,20 +956,14 @@ public: */ const char* ParseTime(const wxString& time, wxString::const_iterator* end = NULL); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const char* ParseTime(const char* time); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + /** + @overload */ const wchar_t* ParseTime(const wchar_t* time); @@ -1450,9 +1380,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);