X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/datetime.h
diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index ce9810ebb6..ecd0b73b3c 100644
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -2,40 +2,102 @@
// Name: datetime.h
// Purpose: interface of wxDateTime
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxDateTime
- @wxheader{datetime.h}
- 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 unsigned short and is
used to contain the number of years, hours, minutes, seconds and
milliseconds.
+ Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are
+ defined. This constant will be different from any valid wxDateTime object.
- @section datetime_constants Constants
- Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
- defined. This constant will be different from any valid wxDateTime object.
+ @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.
+
+ @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.
- All the following constants are defined inside wxDateTime class (i.e., to
- refer to them you should prepend their names with "wxDateTime::").
+ 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 cannot be described with
+ @c strptime(3)-like format strings used by Format(), hence the need for a
+ separate function.
- Time zone symbolic names:
+ 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,
+ ParseDate() can parse the strings such as "tomorrow", "March first" and
+ even "next Sunday".
- @code
+ 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}
+
+ @stdobjects
+ - ::wxDefaultDateTime
+
+ @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
+*/
+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
+ /// 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
+ //@{
+ /// zones from GMT (= Greenwich 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,
@@ -45,91 +107,194 @@
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
+ 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
+ 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
+ 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
+ NZST = GMT12, //!< Standard Time
+ NZDT = GMT13, //!< Daylight Saving Time
- // Universal Coordinated Time = the new and politically correct name
- // for GMT
+ /// 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
+ /**
+ 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
{
- Name_Full = 0x01, // return full name
- Name_Abbr = 0x02 // return abbreviated name
+ Gregorian, ///< calendar currently in use in Western countries
+ Julian ///< calendar in use since -45 until the 1582 (or later)
};
- @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:
+ /**
+ Values corresponding to different dates of adoption of the Gregorian
+ calendar.
- @code
- enum Calendar
+ @see IsGregorianDate
+ */
+ enum GregorianAdoption
{
- Gregorian, // calendar currently in use in Western countries
- Julian // calendar in use since -45 until the 1582 (or later)
+ 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
};
- @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
+ /**
+ 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_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,
@@ -142,98 +307,122 @@
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()).
+ /// symbolic names for the months
+ enum Month
+ {
+ Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec,
- The desired behvaiour may be specified by giving one of the following
- constants as argument to these functions:
+ /// Invalid month value.
+ Inv_Month
+ };
- @code
- enum WeekFlags
+ /// symbolic names for the weekdays
+ enum WeekDay
{
- 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
+ Sun, Mon, Tue, Wed, Thu, Fri, Sat,
+ /// Invalid week day value.
+ Inv_WeekDay
+ };
- @section datetime_static Static Functions
+ /// invalid value for the year
+ enum Year
+ {
+ Inv_Year = SHRT_MIN // should hold in wxDateTime_t
+ };
- 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.
+ /**
+ Flags to be used with GetMonthName() and GetWeekDayName() functions.
+ */
+ enum NameFlags
+ {
+ Name_Full = 0x01, ///< return full name
+ Name_Abbr = 0x02 ///< return abbreviated name
+ };
- 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.
+ /**
+ 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()).
- @beginWxPythonOnly
- These methods are standalone functions named
- "wxDateTime_" in wxPython.
- @endWxPythonOnly
+ The desired behaviour 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
+ };
- @section datetime_formatting Date Formatting and Parsing
+ /**
+ Class representing a time zone.
- 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 representation is simply the offset, in seconds, from UTC.
+ */
+ class WXDLLIMPEXP_BASE TimeZone
+ {
+ public:
+ /// Constructor for a named time zone.
+ TimeZone(TZ tz);
- 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.
+ /// Constructor for the given offset in seconds.
+ TimeZone(long offset = 0);
- 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".
+ /// Create a time zone with the given offset in seconds.
+ static TimeZone Make(long offset);
- 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.
+ /// Return the offset of this time zone from UTC, in seconds.
+ long GetOffset() const;
+ };
+ /**
+ Contains broken down date-time representation.
- @library{wxbase}
- @category{data}
+ This struct is analogous to standard C struct tm and uses
+ the same, not always immediately obvious, conventions for its members:
+ notably its mon and mday fields count from 0 while yday counts from 1.
+ */
+ struct Tm
+ {
+ wxDateTime_t msec, ///< Number of milliseconds.
+ sec, ///< Seconds in 0..59 (60 with leap seconds) range.
+ min, ///< Minutes in 0..59 range.
+ hour, ///< Hours since midnight in 0..23 range.
+ mday, ///< Day of the month in 1..31 range.
+ yday; ///< Day of the year in 0..365 range.
+ Month mon; ///< Month, as an enumerated constant.
+ int year; ///< Year.
+
+ /**
+ Check if the given date/time is valid (in Gregorian calendar).
+
+ Return @false if the components don't correspond to a correct date.
+ */
+ bool IsValid() const;
+
+ /**
+ Return the week day corresponding to this date.
+
+ Unlike the other fields, the week day is not always available and
+ so must be accessed using this method as it is computed on demand
+ when it is called.
+ */
+ WeekDay GetWeekDay();
+ };
- @stdobjects
- - ::wxDefaultDateTime
- @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
-*/
-class wxDateTime
-{
-public:
/**
@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.
+ as constructors cannot return an error code.
*/
//@{
@@ -242,45 +431,33 @@ public:
object later.
*/
wxDateTime();
+
+ /**
+ Copy constructor.
+ */
+ wxDateTime(const wxDateTime& date);
+
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromTimeT" in wxPython.
- @endWxPythonOnly
*/
- wxDateTime& wxDateTime(time_t timet);
+ wxDateTime(time_t timet);
/**
Same as Set().
-
- @beginWxPythonOnly Unsupported. @endWxPythonOnly
*/
- wxDateTime& wxDateTime(const struct tm& tm);
+ wxDateTime(const struct tm& tm);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromJDN" in wxPython.
- @endWxPythonOnly
*/
- wxDateTime& wxDateTime(double jdn);
+ 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);
+ 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,
+ 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);
@@ -292,6 +469,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime(const struct _SYSTEMTIME& st);
@@ -303,20 +481,24 @@ public:
/**
Constructs the object from @a timet value holding the number of seconds
- since Jan 1, 1970.
+ since Jan 1, 1970 UTC.
- @beginWxPythonOnly
- This method is named "SetTimeT" in wxPython.
- @endWxPythonOnly
+ If @a timet is invalid, i.e. @code (time_t)-1 @endcode, wxDateTime
+ becomes invalid too, i.e. its IsValid() will return @false.
*/
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);
+
+ /**
+ 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.
@@ -324,26 +506,18 @@ public:
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
*/
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);
/**
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);
@@ -351,7 +525,7 @@ public:
/**
Sets the day without changing other date components.
*/
- wxDateTime& SetDay(short unsigned int);
+ wxDateTime& SetDay(unsigned short day);
/**
Sets the date from the date and time in DOS format.
@@ -361,17 +535,17 @@ public:
/**
Sets the hour without changing other date components.
*/
- wxDateTime& SetHour(short unsigned int);
+ wxDateTime& SetHour(unsigned short hour);
/**
Sets the millisecond without changing other date components.
*/
- wxDateTime& SetMillisecond(short unsigned int);
+ wxDateTime& SetMillisecond(unsigned short millisecond);
/**
Sets the minute without changing other date components.
*/
- wxDateTime& SetMinute(short unsigned int);
+ wxDateTime& SetMinute(unsigned short minute);
/**
Sets the month without changing other date components.
@@ -381,7 +555,7 @@ public:
/**
Sets the second without changing other date components.
*/
- wxDateTime& SetSecond(short unsigned int);
+ wxDateTime& SetSecond(unsigned short second);
/**
Sets the date and time of to the current values. Same as assigning the
@@ -419,7 +593,7 @@ public:
/**
Returns the date and time in DOS format.
*/
- long unsigned int GetAsDOS() const;
+ unsigned long GetAsDOS() const;
/**
Initialize using the Windows SYSTEMTIME structure.
@@ -427,6 +601,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
@@ -436,6 +611,7 @@ public:
Output, pointer to Windows SYSTEMTIME
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
@@ -457,28 +633,28 @@ public:
/**
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).
*/
- 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).
*/
- 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).
*/
- 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).
*/
- 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).
@@ -488,11 +664,13 @@ public:
/**
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
- occur if the date is not in the range covered by @c time_t type.
+ Returns the number of seconds since Jan 1, 1970 UTC.
+
+ An assert failure will occur if the date is not in the range covered by
+ @c time_t type, use GetValue() if you work with dates outside of it.
*/
time_t GetTicks() const;
@@ -510,8 +688,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;
@@ -525,10 +702,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;
@@ -579,7 +755,7 @@ public:
/**
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
+ interval, i.e.\ if the absolute difference between the two dates is less
than this interval.
*/
bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
@@ -638,67 +814,35 @@ public:
/**
Adds the given date span to this object.
-
- @beginWxPythonOnly
- This method is named "AddDS" in wxPython.
- @endWxPythonOnly
*/
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);
+ wxDateTime& Add(const wxDateSpan& diff);
/**
Adds the given time span to this object.
-
- @beginWxPythonOnly
- This method is named "AddTS" in wxPython.
- @endWxPythonOnly
*/
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);
/**
Subtracts the given time span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractTS" in wxPython.
- @endWxPythonOnly
*/
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);
/**
Subtracts the given date span from this object.
-
- @beginWxPythonOnly
- This method is named "SubtractDS" in wxPython.
- @endWxPythonOnly
*/
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);
/**
@@ -706,23 +850,53 @@ public:
them as a wxTimeSpan.
*/
wxTimeSpan Subtract(const wxDateTime& dt) const;
+ /**
+ Returns the difference between this object and @a dt as a wxDateSpan.
+
+ This method allows to find the number of entire years, months, weeks and
+ days between @a dt and this date.
+ @since 2.9.5
+ */
+ wxDateSpan DiffAsDateSpan(const wxDateTime& dt) const;
+
+ /**
+ Adds the given date span to this object.
+ */
+ wxDateTime& operator+=(const wxDateSpan& diff);
/**
Adds the given date span to this object.
*/
- wxDateTime operator+=(const wxDateSpan& diff);
+ wxDateTime operator+(const wxDateSpan& ds) const;
/**
Subtracts the given date span from this object.
*/
wxDateTime& operator-=(const wxDateSpan& diff);
+ /**
+ Subtracts the given date span from this object.
+ */
+ wxDateTime operator-(const wxDateSpan& ds) const;
/**
Adds the given time span to this object.
*/
wxDateTime& operator+=(const wxTimeSpan& diff);
+ /**
+ Adds the given time span to this object.
+ */
+ wxDateTime operator+(const wxTimeSpan& ts) const;
/**
Subtracts the given time span from this object.
*/
wxDateTime& operator-=(const wxTimeSpan& diff);
+ /**
+ Subtracts the given time span from this object.
+ */
+ wxDateTime operator-(const wxTimeSpan& ts) const;
+ /**
+ Subtracts another date from this one and returns the difference between
+ them as a wxTimeSpan.
+ */
+ wxTimeSpan operator-(const wxDateTime& dt2) const;
//@}
@@ -737,8 +911,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
@@ -747,7 +921,7 @@ public:
@see ParseFormat()
*/
- wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
+ wxString Format(const wxString& format = wxDefaultDateTimeFormat,
const TimeZone& tz = Local) const;
/**
@@ -760,7 +934,7 @@ public:
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
+ be useful to use a space as separator if a more human-readable combined
date-time representation is needed.
@see FormatISODate(), FormatISOTime(), ParseISOCombined()
@@ -787,67 +961,33 @@ 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 cannot be parsed in
+ any way at all. Notice that the function will fail if either date or
+ time part is present but not both, use ParseDate() or ParseTime() to
+ parse strings containing just the date or time component.
- @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
@@ -868,63 +1008,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.
+ bool ParseFormat(const wxString& date,
+ const wxString& format,
+ const wxDateTime& dateDef,
+ wxString::const_iterator *end);
- 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.
+ /**
+ @overload
+ */
+ bool ParseFormat(const wxString& date,
+ const wxString& format,
+ 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
@@ -970,73 +1100,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);
//@}
@@ -1105,8 +1182,7 @@ public:
@return The reference to the modified object itself.
*/
- wxDateTime SetToLastMonthDay(Month month = Inv_Month,
- int year = Inv_Year);
+ wxDateTime& SetToLastMonthDay(Month month = Inv_Month, int year = Inv_Year);
/**
The effect of calling this function is the same as of calling
@@ -1156,11 +1232,11 @@ public:
@return The reference to the modified object itself.
*/
- wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
+ wxDateTime& SetToWeekDayInSameWeek(WeekDay weekday,
WeekFlags flags = Monday_First);
/**
- Sets the date to the day number @a yday in the same year (i.e., unlike
+ 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.
@@ -1203,10 +1279,10 @@ public:
/**
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.
+ 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;
@@ -1252,13 +1328,13 @@ public:
/**
Same as FromTimezone() but modifies the object in place.
*/
- wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false);
+ wxDateTime& MakeFromTimezone(const TimeZone& tz, bool noDST = false);
/**
Modifies the object in place to represent the date in another time
zone. If @a noDST is @true, no DST adjustments will be made.
*/
- wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false);
+ wxDateTime& MakeTimezone(const TimeZone& tz, bool noDST = false);
/**
This is the same as calling MakeTimezone() with the argument @c GMT0.
@@ -1285,7 +1361,7 @@ public:
/**
- Converts the year in absolute notation (i.e. a number which can be
+ 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.
@@ -1327,7 +1403,7 @@ public:
Country country = Country_Default);
/**
- Get the current century, i.e. first two digits of the year, in given
+ Get the current century, i.e.\ first two digits of the year, in given
calendar (only Gregorian is currently supported).
*/
static int GetCentury(int year);
@@ -1353,8 +1429,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()
*/
@@ -1363,20 +1484,12 @@ public:
/**
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
*/
static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
/**
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
*/
static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
Calendar cal = Gregorian);
@@ -1387,10 +1500,10 @@ public:
static time_t GetTimeNow();
/**
- Returns the current time broken down using the buffer whose adress is
+ Returns the current time broken down using the buffer whose address is
passed to the function with @a tm to store the result.
*/
- static struct tm* GetTmNow(struct tm *tm);
+ static tm* GetTmNow(struct tm *tm);
/**
Returns the current time broken down. Note that this function returns a
@@ -1399,19 +1512,26 @@ public:
your code might be used in a multi-threaded application, you really
should use GetTmNow(struct tm *) instead.
*/
- static struct tm* GetTmNow();
+ 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 n the given year (the current one by
+ Returns @true if DST was used in the given year (the current one by
default) in the given country.
*/
static bool IsDSTApplicable(int year = Inv_Year,
@@ -1440,9 +1560,8 @@ public:
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.
+ @note This function is accurate up to seconds. UNow() can be used if
+ better precision is required.
@see Today()
*/
@@ -1452,9 +1571,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);
@@ -1473,18 +1589,20 @@ public:
/**
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).
+ (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).
+ Returns the object corresponding to the current UTC time including the
+ milliseconds.
- @see Now()
+ Notice that unlike Now(), this method creates a wxDateTime object
+ corresponding to UTC, not local, time.
+
+ @see Now(), wxGetUTCTimeMillis()
*/
static wxDateTime UNow();
};
@@ -1497,11 +1615,14 @@ public:
*/
const wxDateTime wxDefaultDateTime;
+/*
+ wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime
/**
@class wxDateTimeWorkDays
- @wxheader{datetime.h}
@todo Write wxDateTimeWorkDays documentation.
@@ -1518,7 +1639,6 @@ public:
/**
@class wxDateSpan
- @wxheader{datetime.h}
This class is a "logical time span" and is useful for implementing program
logic for such things as "add one month to the date" which, in general,
@@ -1608,6 +1728,16 @@ public:
*/
int GetMonths() const;
+ /**
+ Returns the combined number of months in this date span, counting both
+ years and months.
+
+ @see GetYears(), GetMonths()
+
+ @since 2.9.5
+ */
+ int GetTotalMonths() const;
+
/**
Returns the combined number of days in this date span, counting both
weeks and days. This doesn't take months or years into account.
@@ -1765,7 +1895,7 @@ public:
/**
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
@@ -1773,14 +1903,13 @@ public:
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;
};
/**
@class wxTimeSpan
- @wxheader{datetime.h}
wxTimeSpan class represents a time interval.
@@ -1801,7 +1930,7 @@ public:
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);
+ wxTimeSpan(long hours, long min = 0, wxLongLong sec = 0, wxLongLong msec = 0);
/**
Returns the absolute value of the timespan: does not modify the object.
@@ -1823,12 +1952,12 @@ public:
/**
Returns the timespan for one day.
*/
- static wxTimespan Day();
+ static wxTimeSpan Day();
/**
Returns the timespan for the given number of days.
*/
- static wxTimespan Days(long days);
+ static wxTimeSpan Days(long days);
/**
Returns the string containing the formatted representation of the time
@@ -1856,7 +1985,7 @@ public:
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.
@@ -1896,12 +2025,12 @@ public:
/**
Returns the timespan for one hour.
*/
- static wxTimespan Hour();
+ static wxTimeSpan Hour();
/**
Returns the timespan for the given number of hours.
*/
- static wxTimespan Hours(long hours);
+ static wxTimeSpan Hours(long hours);
/**
Returns @true if two timespans are equal.
@@ -1909,7 +2038,7 @@ public:
bool IsEqualTo(const wxTimeSpan& ts) const;
/**
- Compares two timespans: works with the absolute values, i.e. -2 hours
+ 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.
*/
@@ -1931,7 +2060,7 @@ public:
bool IsPositive() const;
/**
- Compares two timespans: works with the absolute values, i.e. 1 hour is
+ 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.
*/
@@ -1940,22 +2069,22 @@ public:
/**
Returns the timespan for one millisecond.
*/
- static wxTimespan Millisecond();
+ static wxTimeSpan Millisecond();
/**
Returns the timespan for the given number of milliseconds.
*/
- static wxTimespan Milliseconds(long ms);
+ static wxTimeSpan Milliseconds(wxLongLong ms);
/**
Returns the timespan for one minute.
*/
- static wxTimespan Minute();
+ static wxTimeSpan Minute();
/**
Returns the timespan for the given number of minutes.
*/
- static wxTimespan Minutes(long min);
+ static wxTimeSpan Minutes(long min);
/**
Returns the product of this time span by @a n.
@@ -1987,12 +2116,12 @@ public:
/**
Returns the timespan for one second.
*/
- static wxTimespan Second();
+ static wxTimeSpan Second();
/**
Returns the timespan for the given number of seconds.
*/
- static wxTimespan Seconds(long sec);
+ static wxTimeSpan Seconds(wxLongLong sec);
/**
Returns the difference of two time spans.
@@ -2009,12 +2138,12 @@ public:
/**
Returns the timespan for one week.
*/
- static wxTimespan Week();
+ static wxTimeSpan Week();
/**
Returns the timespan for the given number of weeks.
*/
- static wxTimespan Weeks(long weeks);
+ static wxTimeSpan Weeks(long weeks);
/**
Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
@@ -2046,12 +2175,11 @@ public:
/**
@class wxDateTimeHolidayAuthority
- @wxheader{datetime.h}
@todo Write wxDateTimeHolidayAuthority documentation.
@library{wxbase}
- @category{misc}
+ @category{data}
*/
class wxDateTimeHolidayAuthority
{