X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c99e2fd1b3432974b892be508c0757da5b6ad49..e4097f77c440b1f31a80fe273cc732c14d606096:/interface/wx/datetime.h
diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index 70cf1c5a89..f7f1906921 100644
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -2,39 +2,102 @@
// Name: datetime.h
// Purpose: interface of wxDateTime
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxDateTime
- wxDateTime class represents an absolute moment in the time.
+ wxDateTime class represents an absolute moment in time.
The type @c wxDateTime_t is typedefed as 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.
+
+ 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.
+
+ 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".
+
+ 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
- All the following constants are defined inside wxDateTime class (i.e., to
- refer to them you should prepend their names with "wxDateTime::").
+ @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:
- @code
+ /**
+ 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,
@@ -44,91 +107,72 @@
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
- {
- 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
+ /**
+ 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)
+ 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
+ /**
+ 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,
@@ -141,98 +185,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.
*/
//@{
@@ -241,45 +309,33 @@ public:
object later.
*/
wxDateTime();
+
+ /**
+ Copy constructor.
+ */
+ wxDateTime(const wxDateTime& date);
+
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromTimeT" in wxPython.
- @endWxPythonOnly
*/
wxDateTime(time_t timet);
/**
Same as Set().
-
- @beginWxPythonOnly Unsupported. @endWxPythonOnly
*/
wxDateTime(const struct tm& tm);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromJDN" in wxPython.
- @endWxPythonOnly
*/
wxDateTime(double jdn);
/**
Same as Set().
-
- @beginWxPythonOnly
- This constructor is named "wxDateTimeFromHMS" in wxPython.
- @endWxPythonOnly
*/
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);
@@ -291,6 +347,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime(const struct _SYSTEMTIME& st);
@@ -302,20 +359,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.
@@ -323,26 +384,32 @@ 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
+ See the full Set() overload for the remarks about DST.
*/
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.
+
+ If the function parameters are invalid, e.g. @a month is February and
+ @a day is 30, the object is left in an invalid state, i.e. IsValid()
+ method will return @false.
+
+ If the specified time moment is invalid due to DST, i.e. it falls into
+ the "missing" hour on the date on which the DST starts, a valid
+ wxDateTime object is still constructed but its hour component is moved
+ forward to ensure that it corresponds to a valid moment in the local
+ time zone. For example, in the CET time zone the DST started on
+ 2013-03-31T02:00:00 in 2013 and so setting the object to 2:30 at this
+ date actually sets the hour to 3, and not 2.
*/
- 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);
@@ -418,7 +485,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.
@@ -426,6 +493,7 @@ public:
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
@@ -435,6 +503,7 @@ public:
Output, pointer to Windows SYSTEMTIME
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
@@ -456,28 +525,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).
@@ -487,11 +556,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;
@@ -509,8 +580,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 +594,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;
@@ -537,13 +606,6 @@ public:
*/
int GetYear(const TimeZone& tz = Local) const;
- /**
- Returns @true if the given date is later than the date of adoption of
- the Gregorian calendar in the given country (and hence the Gregorian
- calendar calculations make sense for it).
- */
- bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
-
/**
Returns @true if the object represents a valid time moment.
*/
@@ -578,7 +640,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;
@@ -637,67 +699,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);
/**
@@ -705,23 +735,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);
+ wxDateTime& operator+=(const wxDateSpan& diff);
+ /**
+ Adds the given date span to this object.
+ */
+ 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;
//@}
@@ -736,8 +796,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
@@ -759,7 +819,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()
@@ -786,67 +846,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);
-
- /**
- 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.
+ bool ParseDate(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* 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.
+ format.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
- */
- 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.
+ 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 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 +893,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.
-
- Please see the description of the ANSI C function @c strftime(3) for
- the syntax of the format string.
+ 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
- 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.
+ @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.
- @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,
+ const wxDateTime& dateDef,
+ 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,
+ 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 +985,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.
+ See ParseFormat() for the description of function parameters and return
+ value.
*/
- const wchar_t* ParseRfc822Date(const wchar_t* date);
+ bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
/**
This functions is like ParseDateTime(), but only allows the time to be
specified in the input string.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ 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.
-
- @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.
- */
- const wchar_t* ParseTime(const wchar_t* time);
+ bool ParseTime(const wxString& time, wxString::const_iterator *end);
//@}
@@ -1158,7 +1121,7 @@ public:
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.
@@ -1283,7 +1246,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.
@@ -1325,7 +1288,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);
@@ -1351,8 +1314,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()
*/
@@ -1361,20 +1369,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);
@@ -1385,7 +1385,7 @@ 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 tm* GetTmNow(struct tm *tm);
@@ -1400,13 +1400,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
@@ -1438,9 +1445,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()
*/
@@ -1450,9 +1456,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);
@@ -1471,18 +1474,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();
};
@@ -1495,6 +1500,10 @@ public:
*/
const wxDateTime wxDefaultDateTime;
+/*
+ wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime
/**
@@ -1604,6 +1613,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.
@@ -1761,7 +1780,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
@@ -1769,7 +1788,7 @@ 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;
};
@@ -1851,7 +1870,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.
@@ -1904,7 +1923,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.
*/
@@ -1926,7 +1945,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.
*/