X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/882678ebb43804d34d20ba8781647fe136ae67d9..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/datetime.h diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h index 9505c3d9a6..e8eb26d46d 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 @@ -786,67 +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. - */ - 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. + 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. - */ - 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. + See ParseFormat() for the description of function parameters and return + value. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + @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); - /** - 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. + 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. + See ParseFormat() for the description of function parameters and return + value. */ - 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. - */ - 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 @@ -867,63 +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. - */ - 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. + 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 - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. + @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. - 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. + @see Format() */ - 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. + bool ParseFormat(const wxString& date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime, + wxString::const_iterator *end); - 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. + /** + @overload + */ + bool ParseFormat(const wxString& date, + const wxString& format = wxDefaultDateTimeFormat, + wxString::const_iterator *end); - @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); + bool ParseFormat(const wxString& date, wxString::const_iterator *end); /** This function parses the string containing the date and time in ISO @@ -969,73 +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); - /** - 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); - /** - 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 wchar_t* ParseRfc822Date(const wchar_t* date); - - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const char* ParseTime(const wxString& time, - wxString::const_iterator* end = NULL); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. + bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end); - @return @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. - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. + See ParseFormat() for the description of function parameters and return + value. */ - const wchar_t* ParseTime(const wchar_t* time); + bool ParseTime(const wxString& time, wxString::const_iterator *end); //@} @@ -1351,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() */ @@ -1400,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 @@ -1450,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); @@ -2045,7 +2011,7 @@ public: @todo Write wxDateTimeHolidayAuthority documentation. @library{wxbase} - @category{misc} + @category{data} */ class wxDateTimeHolidayAuthority {