X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..9602ce3d8ca47689bb69d09dbdd09152f2bde8c3:/interface/datetime.h
diff --git a/interface/datetime.h b/interface/datetime.h
index 7b2ad9370c..ce9810ebb6 100644
--- a/interface/datetime.h
+++ b/interface/datetime.h
@@ -12,357 +12,444 @@
wxDateTime class represents an absolute moment in the 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.
+
+
+ @section datetime_constants Constants
+
+ Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
+ defined. This constant will be different from any valid wxDateTime object.
+
+ All the following constants are defined inside wxDateTime class (i.e., to
+ refer to them you should prepend their names with "wxDateTime::").
+
+ Time zone symbolic names:
+
+ @code
+ enum TZ
+ {
+ // the time in the current time zone
+ Local,
+
+ // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+ // consequent numbers, so writing something like `GMT0 + offset' is
+ // safe if abs(offset) <= 12
+
+ // underscore stands for minus
+ GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
+ GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
+ GMT0,
+ GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
+ GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
+ // Note that GMT12 and GMT_12 are not the same: there is a difference
+ // of exactly one day between them
+
+ // some symbolic names for TZ
+
+ // Europe
+ WET = GMT0, // Western Europe Time
+ WEST = GMT1, // Western Europe Summer Time
+ CET = GMT1, // Central Europe Time
+ CEST = GMT2, // Central Europe Summer Time
+ EET = GMT2, // Eastern Europe Time
+ EEST = GMT3, // Eastern Europe Summer Time
+ MSK = GMT3, // Moscow Time
+ MSD = GMT4, // Moscow Summer Time
+
+ // US and Canada
+ AST = GMT_4, // Atlantic Standard Time
+ ADT = GMT_3, // Atlantic Daylight Time
+ EST = GMT_5, // Eastern Standard Time
+ EDT = GMT_4, // Eastern Daylight Saving Time
+ CST = GMT_6, // Central Standard Time
+ CDT = GMT_5, // Central Daylight Saving Time
+ MST = GMT_7, // Mountain Standard Time
+ MDT = GMT_6, // Mountain Daylight Saving Time
+ PST = GMT_8, // Pacific Standard Time
+ PDT = GMT_7, // Pacific Daylight Saving Time
+ HST = GMT_10, // Hawaiian Standard Time
+ AKST = GMT_9, // Alaska Standard Time
+ AKDT = GMT_8, // Alaska Daylight Saving Time
+
+ // Australia
+
+ A_WST = GMT8, // Western Standard Time
+ A_CST = GMT13 + 1, // Central Standard Time (+9.5)
+ A_EST = GMT10, // Eastern Standard Time
+ A_ESST = GMT11, // Eastern Summer Time
+
+ // New Zealand
+ NZST = GMT12, // Standard Time
+ NZDT = GMT13, // Daylight Saving Time
+
+ // Universal Coordinated Time = the new and politically correct name
+ // for GMT
+ UTC = GMT0
+ };
+ @endcode
+
+ Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
+ Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
+
+ Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
+ in @c wxDateTime::WeekDay enum.
+
+ Finally, Inv_Year is defined to be an invalid value for year parameter.
+
+ GetMonthName() and GetWeekDayName() functions use the following flags:
+
+ @code
+ enum NameFlags
+ {
+ Name_Full = 0x01, // return full name
+ Name_Abbr = 0x02 // return abbreviated name
+ };
+ @endcode
+
+ Several functions accept an extra parameter specifying the calendar to use
+ (although most of them only support now the Gregorian calendar). This
+ parameters is one of the following values:
+
+ @code
+ enum Calendar
+ {
+ Gregorian, // calendar currently in use in Western countries
+ Julian // calendar in use since -45 until the 1582 (or later)
+ };
+ @endcode
+
+ Date calculations often depend on the country and wxDateTime allows to set
+ the country whose conventions should be used using SetCountry(). It takes
+ one of the following values as parameter:
+
+ @code
+ enum Country
+ {
+ Country_Unknown, // no special information for this country
+ Country_Default, // set the default country with SetCountry() method
+ // or use the default country with any other
+
+ Country_WesternEurope_Start,
+ Country_EEC = Country_WesternEurope_Start,
+ France,
+ Germany,
+ UK,
+ Country_WesternEurope_End = UK,
+
+ Russia,
+
+ USA
+ };
+ @endcode
+
+ Different parts of the world use different conventions for the week start.
+ In some countries, the week starts on Sunday, while in others -- on Monday.
+ The ISO standard doesn't address this issue, so we support both conventions
+ in the functions whose result depends on it (GetWeekOfYear() and
+ GetWeekOfMonth()).
+
+ The desired behvaiour may be specified by giving one of the following
+ constants as argument to these functions:
+
+ @code
+ enum WeekFlags
+ {
+ Default_First, // Sunday_First for US, Monday_First for the rest
+ Monday_First, // week starts with a Monday
+ Sunday_First // week starts with a Sunday
+ };
+ @endcode
+
+
+ @section datetime_static Static Functions
+
+ 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.
+
+ @beginWxPythonOnly
+ These methods are standalone functions named
+ "wxDateTime_" in wxPython.
+ @endWxPythonOnly
+
+
+ @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 can not 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,
+ ParseDateTime() 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}
- @see @ref overview_wxdatetimeoverview "Date classes overview", wxTimeSpan,
- wxDateSpan, wxCalendarCtrl
+ @stdobjects
+ - ::wxDefaultDateTime
+
+ @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
*/
class wxDateTime
{
public:
/**
- Same as @ref setdate() Set
+ @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.
+ */
+ //@{
+
+ /**
+ Default constructor. Use one of the Set() functions to initialize the
+ object later.
+ */
+ wxDateTime();
+ /**
+ Same as Set().
+
+ @beginWxPythonOnly
+ This constructor is named "wxDateTimeFromTimeT" in wxPython.
+ @endWxPythonOnly
+ */
+ wxDateTime& wxDateTime(time_t timet);
+ /**
+ Same as Set().
+
+ @beginWxPythonOnly Unsupported. @endWxPythonOnly
+ */
+ wxDateTime& wxDateTime(const struct tm& tm);
+ /**
+ Same as Set().
+
+ @beginWxPythonOnly
+ This constructor is named "wxDateTimeFromJDN" in wxPython.
+ @endWxPythonOnly
+ */
+ wxDateTime& 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);
+ /**
+ Same as Set().
+
+ @beginWxPythonOnly
+ This constructor is named "wxDateTimeFromDMY" in wxPython.
+ @endWxPythonOnly
*/
wxDateTime(wxDateTime_t day, Month month = Inv_Month,
- int Inv_Year, wxDateTime_t hour = 0,
- wxDateTime_t minute = 0,
- wxDateTime_t second = 0,
+ int year = Inv_Year, wxDateTime_t hour = 0,
+ wxDateTime_t minute = 0, wxDateTime_t second = 0,
wxDateTime_t millisec = 0);
/**
- Here are the trivial accessors. Other functions, which might have to perform
- some more complicated calculations to find the answer are under the
- @ref overview_datetimecalculations "Calendar calculations" section.
- IsValid()
-
- GetTicks()
-
- GetCentury()
-
- GetYear()
-
- GetMonth()
-
- GetDay()
-
- GetWeekDay()
-
- GetHour()
-
- GetMinute()
-
- GetSecond()
-
- GetMillisecond()
-
- GetDayOfYear()
-
- GetWeekOfYear()
-
- GetWeekOfMonth()
-
- GetYearDay()
-
- IsWorkDay()
-
- IsGregorianDate()
-
- GetAsDOS()
+ Same as SetFromMSWSysTime.
+
+ @param st
+ Input, Windows SYSTEMTIME reference
+ @since 2.9.0
+ @remarks MSW only
*/
+ wxDateTime(const struct _SYSTEMTIME& st);
- //@{
/**
- Adds the given date span to this object.
+ Reset time to midnight (00:00:00) without changing the date.
*/
- wxDateTime Add(const wxDateSpan& diff);
- const wxDateTime& Add(const wxDateSpan& diff);
- wxDateTime operator+=(const wxDateSpan& diff);
- //@}
+ wxDateTime& ResetTime();
/**
- Some degree of support for the date units used in astronomy and/or history is
- provided. You can construct a wxDateTime object from a
- @ref setjdn() JDN and you may also get its JDN,
- @ref getmodifiedjuliandaynumber() MJD or
- @ref getratadie() "Rata Die number" from it.
- @ref wxdatetimejdn() "wxDateTime(double jdn)"
-
- @ref setjdn() "Set(double jdn)"
-
- GetJulianDayNumber()
-
- GetJDN()
-
- GetModifiedJulianDayNumber()
-
- GetMJD()
-
- GetRataDie()
- */
-
-
- /**
- The functions in this section perform the basic calendar calculations, mostly
- related to the week days. They allow to find the given week day in the
- week with given number (either in the month or in the year) and so on.
- All (non-const) functions in this section don't modify the time part of the
- wxDateTime -- they only work with the date part of it.
- SetToWeekDayInSameWeek()
-
- GetWeekDayInSameWeek()
-
- SetToNextWeekDay()
-
- GetNextWeekDay()
-
- SetToPrevWeekDay()
-
- GetPrevWeekDay()
-
- SetToWeekDay()
-
- @ref wxDateTime::getweekday2 GetWeekDay
-
- SetToLastWeekDay()
-
- GetLastWeekDay()
-
- SetToWeekOfYear()
-
- SetToLastMonthDay()
-
- GetLastMonthDay()
-
- SetToYearDay()
-
- GetYearDay()
- */
-
-
- /**
- Constructors and various @c 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.
- @ref wxdatetimedef() wxDateTime
-
- @ref wxdatetimetimet() wxDateTime(time_t)
-
- @ref wxdatetimetm() "wxDateTime(struct tm)"
-
- @ref wxdatetimejdn() "wxDateTime(double jdn)"
-
- @ref wxdatetimetime() "wxDateTime(h, m, s, ms)"
-
- @ref wxdatetimedate() "wxDateTime(day, mon, year, h, m, s, ms)"
-
- SetToCurrent()
-
- @ref settimet() Set(time_t)
-
- @ref settm() "Set(struct tm)"
-
- @ref setjdn() "Set(double jdn)"
-
- @ref settime() "Set(h, m, s, ms)"
-
- @ref setdate() "Set(day, mon, year, h, m, s, ms)"
-
- @ref setfromdos() "SetFromDOS(unsigned long ddt)"
-
- ResetTime()
-
- SetYear()
-
- SetMonth()
-
- @ref setdate() SetDay
-
- SetHour()
-
- SetMinute()
-
- SetSecond()
-
- SetMillisecond()
-
- @ref operatoreqtimet() operator=(time_t)
-
- @ref operatoreqtm() "operator=(struct tm)"
- */
-
-
- /**
- 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.
- This function should be used like this:
+ Constructs the object from @a timet value holding the number of seconds
+ since Jan 1, 1970.
+
+ @beginWxPythonOnly
+ This method is named "SetTimeT" in wxPython.
+ @endWxPythonOnly
*/
- static int ConvertYearToBC(int year);
+ 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);
/**
- These functions carry out arithmetics() on the wxDateTime
- objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be
- added to wxDateTime, hence all functions are overloaded to accept both
- arguments.
- Also, both @c Add() and @c Subtract() have both const and non-const
- version. The first one returns a new object which represents the
- sum/difference of the original one with the argument while the second form
- modifies the object to which it is applied. The operators -= and += are
- defined to be equivalent to the second forms of these functions.
- @ref addts() Add(wxTimeSpan)
-
- @ref addds() Add(wxDateSpan)
-
- @ref subtractts() Subtract(wxTimeSpan)
-
- @ref subtractds() Subtract(wxDateSpan)
-
- @ref subtractdt() Subtract(wxDateTime)
-
- @ref addts() oparator+=(wxTimeSpan)
-
- @ref addds() oparator+=(wxDateSpan)
-
- @ref subtractts() oparator-=(wxTimeSpan)
-
- @ref subtractds() oparator-=(wxDateSpan)
- */
-
-
- /**
- There are several function to allow date comparison. To supplement them, a few
- global operators , etc taking wxDateTime are defined.
- IsEqualTo()
-
- IsEarlierThan()
-
- IsLaterThan()
-
- IsStrictlyBetween()
-
- IsBetween()
-
- IsSameDate()
-
- IsSameTime()
-
- IsEqualUpTo()
- */
-
-
- /**
- 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.
- 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 and the
- format specification @c %l can be used to get the number of milliseconds.
-
- @see ParseFormat()
+ Sets the date from the so-called Julian Day Number.
+
+ By definition, the Julian Day Number, usually abbreviated as JDN, of a
+ 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
*/
- wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
- const TimeZone& tz = Local) const;
+ 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);
/**
- Identical to calling Format() with @c "%x"
- argument (which means 'preferred date representation for the current locale').
+ Sets the date and time from the parameters.
*/
- wxString FormatDate() const;
+ wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
+ int year = Inv_Year, wxDateTime_t hour = 0,
+ wxDateTime_t minute = 0, wxDateTime_t second = 0,
+ wxDateTime_t millisec = 0);
/**
- Returns the combined date-time representation in the ISO 8601 format
- (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 date-time
- representation is needed.
-
- @see FormatISODate(), FormatISOTime(),
- ParseISOCombined()
+ Sets the day without changing other date components.
*/
- wxString FormatISOCombined(char sep = 'T') const;
+ wxDateTime& SetDay(short unsigned int);
/**
- This function returns the date representation in the ISO 8601 format
- (YYYY-MM-DD).
+ Sets the date from the date and time in DOS format.
*/
- wxString FormatISODate() const;
+ wxDateTime& SetFromDOS(unsigned long ddt);
/**
- This function returns the time representation in the ISO 8601 format
- (HH:MM:SS).
+ Sets the hour without changing other date components.
*/
- wxString FormatISOTime() const;
+ wxDateTime& SetHour(short unsigned int);
/**
- Identical to calling Format() with @c "%X"
- argument (which means 'preferred time representation for the current locale').
+ Sets the millisecond without changing other date components.
*/
- wxString FormatTime() const;
+ wxDateTime& SetMillisecond(short unsigned int);
/**
- Transform the date from the given time zone to the local one. If @a noDST is
- @true, no DST adjustments will be made.
- Returns the date in the local time zone.
+ Sets the minute without changing other date components.
*/
- wxDateTime FromTimezone(const TimeZone& tz,
- bool noDST = false) const;
+ wxDateTime& SetMinute(short unsigned int);
/**
- Returns the translations of the strings @c AM and @c PM used for time
- formatting for the current locale. Either of the pointers may be @NULL if
- the corresponding value is not needed.
+ Sets the month without changing other date components.
*/
- static void GetAmPmStrings(wxString* am, wxString* pm);
+ wxDateTime& SetMonth(Month month);
/**
- Returns the date and time in
- DOS
- format.
+ Sets the second without changing other date components.
*/
- unsigned long GetAsDOS() const;
+ wxDateTime& SetSecond(short unsigned int);
/**
- Get the beginning of DST for the given country in the given year (current one
- by default). This function suffers from limitations described in
- @ref overview_tdatedst "DST overview".
-
- @see GetEndDST()
+ Sets the date and time of to the current values. Same as assigning the
+ result of Now() to this object.
*/
- static wxDateTime GetBeginDST(int year = Inv_Year,
- Country country = Country_Default);
+ wxDateTime& SetToCurrent();
/**
- Returns the century of this date.
+ Sets the year without changing other date components.
*/
- int GetCentury(const TimeZone& tz = Local) const;
+ wxDateTime& SetYear(int year);
/**
- Returns the current default country. The default country is used for DST
- calculations, for example.
-
- @see SetCountry()
+ Same as Set().
*/
- static Country GetCountry();
+ wxDateTime& operator=(time_t timet);
+ /**
+ Same as Set().
+ */
+ wxDateTime& operator=(const struct tm& tm);
+
+ //@}
+
+
/**
- Get the current month in given calendar (only Gregorian is currently supported).
+ @name Accessors
+
+ Here are the trivial accessors. Other functions, which might have to
+ perform some more complicated calculations to find the answer are under
+ the "Date Arithmetics" section.
*/
- static Month GetCurrentMonth(Calendar cal = Gregorian);
+ //@{
/**
- Get the current year in given calendar (only Gregorian is currently supported).
+ Returns the date and time in DOS format.
*/
- static int GetCurrentYear(Calendar cal = Gregorian);
+ long unsigned int GetAsDOS() const;
+
+ /**
+ Initialize using the Windows SYSTEMTIME structure.
+ @param st
+ Input, Windows SYSTEMTIME reference
+ @since 2.9.0
+ @remarks MSW only
+ */
+ wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
/**
- Returns the object having the same date component as this one but time of
- 00:00:00.
-
- @wxsince{2.8.2}
-
+ Returns the date and time in the Windows SYSTEMTIME format.
+ @param st
+ Output, pointer to Windows SYSTEMTIME
+ @since 2.9.0
+ @remarks MSW only
+ */
+ void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
+
+ /**
+ Returns the century of this date.
+ */
+ int GetCentury(const TimeZone& tz = Local) const;
+
+ /**
+ Returns the object having the same date component as this one but time
+ of 00:00:00.
+
+ @since 2.8.2
+
@see ResetTime()
*/
wxDateTime GetDateOnly() const;
@@ -370,797 +457,1056 @@ public:
/**
Returns the day in the given timezone (local one by default).
*/
- wxDateTime_t GetDay(const TimeZone& tz = Local) const;
+ short unsigned int GetDay(const TimeZone& tz = Local) const;
/**
- Returns the day of the year (in 1...366 range) in the given timezone
+ Returns the day of the year (in 1-366 range) in the given timezone
(local one by default).
*/
- wxDateTime_t GetDayOfYear(const TimeZone& tz = Local) const;
+ short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
/**
- Returns the end of DST for the given country in the given year (current one by
- default).
-
- @see GetBeginDST()
+ Returns the hour in the given timezone (local one by default).
*/
- static wxDateTime GetEndDST(int year = Inv_Year,
- Country country = Country_Default);
+ short unsigned int GetHour(const TimeZone& tz = Local) const;
/**
- Returns the hour in the given timezone (local one by default).
+ Returns the milliseconds in the given timezone (local one by default).
*/
- wxDateTime_t GetHour(const TimeZone& tz = Local) const;
+ short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
/**
- Synonym for GetJulianDayNumber().
+ Returns the minute in the given timezone (local one by default).
*/
- double GetJDN() const;
+ short unsigned int GetMinute(const TimeZone& tz = Local) const;
/**
- Returns the @ref setjdn() JDN corresponding to this date. Beware
- of rounding errors!
-
- @see GetModifiedJulianDayNumber()
+ Returns the month in the given timezone (local one by default).
*/
- double GetJulianDayNumber() const;
+ Month GetMonth(const TimeZone& tz = Local) const;
/**
- Returns the copy of this object to which
- SetToLastMonthDay() was applied.
+ Returns the seconds in the given timezone (local one by default).
*/
- wxDateTime GetLastMonthDay(Month month = Inv_Month,
- int year = Inv_Year) const;
+ short unsigned int GetSecond(const TimeZone& tz = Local) const;
/**
- Returns the copy of this object to which
- SetToLastWeekDay() was applied.
+ 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.
*/
- wxDateTime GetLastWeekDay(WeekDay weekday,
- Month month = Inv_Month,
- int year = Inv_Year);
+ time_t GetTicks() const;
/**
- Synonym for GetModifiedJulianDayNumber().
+ Returns broken down representation of the date and time.
*/
- double GetMJD() const;
+ Tm GetTm(const TimeZone& tz = Local) const;
/**
- Returns the milliseconds in the given timezone (local one by default).
+ Returns the week day in the given timezone (local one by default).
*/
- wxDateTime_t GetMillisecond(const TimeZone& tz = Local) const;
+ WeekDay GetWeekDay(const TimeZone& tz = Local) const;
/**
- Returns the minute in the given timezone (local one by default).
+ 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.
*/
- wxDateTime_t GetMinute(const TimeZone& tz = Local) const;
+ wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
+ const TimeZone& tz = Local) const;
/**
- Returns the @e Modified Julian Day Number (MJD) which is, by definition,
- 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 th
- noons like JDN. The MJD 0 is Nov 17, 1858.
+ Returns the number of the week of the year this date is in. The first
+ week of the year is, according to international standards, the one
+ containing Jan 4 or, equivalently, the first week which has Thursday in
+ this year. Both of these definitions are the same as saying that the
+ first week of the year must contain more than half of its days in this
+ 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.
*/
- double GetModifiedJulianDayNumber() const;
+ wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
+ const TimeZone& tz = Local) const;
/**
- Returns the month in the given timezone (local one by default).
+ Returns the year in the given timezone (local one by default).
*/
- Month GetMonth(const TimeZone& tz = Local) const;
+ int GetYear(const TimeZone& tz = Local) const;
/**
- Gets the full (default) or abbreviated (specify @c Name_Abbr name of the
- given month.
-
- @see GetWeekDayName()
+ 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).
*/
- static wxString GetMonthName(Month month,
- NameFlags flags = Name_Full);
+ bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
/**
- Returns the copy of this object to which
- SetToNextWeekDay() was applied.
+ Returns @true if the object represents a valid time moment.
*/
- wxDateTime GetNextWeekDay(WeekDay weekday) const;
+ bool IsValid() const;
- //@{
/**
- Returns the number of days in the given year or in the given month of the
- year.
- The only supported value for @a cal parameter is currently @c Gregorian.
+ Returns @true is this day is not a holiday in the given country.
*/
- static wxDateTime_t GetNumberOfDays(int year,
- Calendar cal = Gregorian);
- static wxDateTime_t GetNumberOfDays(Month month,
- int year = Inv_Year,
- Calendar cal = Gregorian);
+ bool IsWorkDay(Country country = Country_Default) const;
+
//@}
+
+
/**
- Returns the copy of this object to which
- SetToPrevWeekDay() was applied.
+ @name Date Comparison
+
+ There are several functions to allow date comparison. To supplement
+ them, a few global operators, etc taking wxDateTime are defined.
*/
- wxDateTime GetPrevWeekDay(WeekDay weekday) const;
+ //@{
/**
- Return the @e Rata Die number of this date.
- By definition, the Rata Die number is a date specified as the number of days
- relative to a base date of December 31 of the year 0. Thus January 1 of the
- year 1 is Rata Die day 1.
+ Returns @true if this date precedes the given one.
*/
- double GetRataDie() const;
+ bool IsEarlierThan(const wxDateTime& datetime) const;
/**
- Returns the seconds in the given timezone (local one by default).
+ Returns @true if the two dates are strictly identical.
*/
- wxDateTime_t GetSecond(const TimeZone& tz = Local) const;
+ bool IsEqualTo(const wxDateTime& datetime) 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 @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
+ than this interval.
*/
- time_t GetTicks() const;
+ bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
/**
- Returns the current time.
+ Returns @true if this date is later than the given one.
*/
- static time_t GetTimeNow();
+ bool IsLaterThan(const wxDateTime& datetime) const;
/**
- Returns broken down representation of the date and time.
+ Returns @true if the date is the same without comparing the time parts.
*/
- Tm GetTm(const TimeZone& tz = Local) const;
+ bool IsSameDate(const wxDateTime& dt) const;
/**
- Returns the current time broken down. Note that this function returns a
- pointer to a static buffer that's reused by calls to this function and
- certain C library functions (e.g. localtime). If there is any chance your
- code might be used in a multi-threaded application, you really should use
- the flavour of function GetTmNow()
- taking a parameter.
+ Returns @true if the time is the same (although dates may differ).
*/
- static struct tm* GetTmNow();
+ bool IsSameTime(const wxDateTime& dt) const;
/**
- Returns the copy of this object to which
- SetToWeekDay() was applied.
+ Returns @true if this date lies strictly between the two given dates.
+
+ @see IsBetween()
*/
- wxDateTime GetWeekDay(WeekDay weekday, int n = 1,
- Month month = Inv_Month,
- int year = Inv_Year) const;
+ bool IsStrictlyBetween(const wxDateTime& t1,
+ const wxDateTime& t2) const;
/**
- Returns the copy of this object to which
- SetToWeekDayInSameWeek() was
- applied.
+ Returns @true if IsStrictlyBetween() is @true or if the date is equal
+ to one of the limit values.
+
+ @see IsStrictlyBetween()
*/
- wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
- WeekFlags flags = Monday_First) const;
+ bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const;
+
+ //@}
+
+
/**
- Gets the full (default) or abbreviated (specify @c Name_Abbr name of the
- given week day.
-
- @see GetMonthName()
+ @name Date Arithmetics
+
+ These functions carry out
+ @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime
+ objects. As explained in the overview, either wxTimeSpan or wxDateSpan
+ may be added to wxDateTime, hence all functions are overloaded to
+ accept both arguments.
+
+ Also, both Add() and Subtract() have both const and non-const version.
+ The first one returns a new object which represents the sum/difference
+ of the original one with the argument while the second form modifies
+ the object to which it is applied. The operators "-=" and "+=" are
+ defined to be equivalent to the second forms of these functions.
*/
- static wxString GetWeekDayName(WeekDay weekday,
- NameFlags flags = Name_Full);
+ //@{
/**
- 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
- @ref overview_wxdatetime "week start" conventions.
+ Adds the given date span to this object.
+
+ @beginWxPythonOnly
+ This method is named "AddDS" in wxPython.
+ @endWxPythonOnly
*/
- wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
- const TimeZone& tz = Local) const;
+ 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);
/**
- Returns the number of the week of the year this date is in. The first week of
- the year is, according to international standards, the one containing Jan 4 or,
- equivalently, the first week which has Thursday in this year. Both of these
- definitions are the same as saying that the first week of the year must contain
- more than half of its days in this year. Accordingly, the week number will
- always be in 1...53 range (52 for non-leap years).
- The function depends on the @ref overview_wxdatetime "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.
+ Adds the given time span to this object.
+
+ @beginWxPythonOnly
+ This method is named "AddTS" in wxPython.
+ @endWxPythonOnly
*/
- wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
- const TimeZone& tz = Local) const;
+ 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);
/**
- Returns the year in the given timezone (local one by default).
+ Subtracts the given time span from this object.
+
+ @beginWxPythonOnly
+ This method is named "SubtractTS" in wxPython.
+ @endWxPythonOnly
*/
- int GetYear(const TimeZone& tz = Local) const;
+ 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);
/**
- Returns the copy of this object to which
- SetToYearDay() was applied.
+ Subtracts the given date span from this object.
+
+ @beginWxPythonOnly
+ This method is named "SubtractDS" in wxPython.
+ @endWxPythonOnly
*/
- wxDateTime GetYearDay(wxDateTime_t yday) const;
+ 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);
/**
- Returns @true if IsStrictlyBetween()
- is @true or if the date is equal to one of the limit values.
-
- @see IsStrictlyBetween()
+ Subtracts another date from this one and returns the difference between
+ them as a wxTimeSpan.
*/
- bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const;
+ wxTimeSpan Subtract(const wxDateTime& dt) const;
/**
- Returns @true if the DST is applied for this date in the given country.
+ Adds the given date span to this object.
*/
- int IsDST(Country country = Country_Default) const;
+ wxDateTime operator+=(const wxDateSpan& diff);
+ /**
+ Subtracts the given date span from this object.
+ */
+ wxDateTime& operator-=(const wxDateSpan& diff);
+ /**
+ Adds the given time span to this object.
+ */
+ wxDateTime& operator+=(const wxTimeSpan& diff);
+ /**
+ Subtracts the given time span from this object.
+ */
+ wxDateTime& operator-=(const wxTimeSpan& diff);
+
+ //@}
+
+
/**
- Returns @true if DST was used n the given year (the current one by
- default) in the given country.
+ @name Date Formatting and Parsing
+
+ See @ref datetime_formatting
*/
- static bool IsDSTApplicable(int year = Inv_Year,
- Country country = Country_Default);
+ //@{
/**
- Returns @true if this date precedes the given one.
+ 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.
+
+ 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
+ and the format specification @c "%l" can be used to get the number of
+ milliseconds.
+
+ @see ParseFormat()
*/
- bool IsEarlierThan(const wxDateTime& datetime) const;
+ wxString Format(const wxChar* format = wxDefaultDateTimeFormat,
+ const TimeZone& tz = Local) const;
/**
- Returns @true if the two dates are strictly identical.
+ Identical to calling Format() with @c "%x" argument (which means
+ "preferred date representation for the current locale").
*/
- bool IsEqualTo(const wxDateTime& datetime) const;
+ wxString FormatDate() const;
/**
- 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 than
- this interval.
+ 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
+ date-time representation is needed.
+
+ @see FormatISODate(), FormatISOTime(), ParseISOCombined()
*/
- bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
+ wxString FormatISOCombined(char sep = 'T') 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).
+ This function returns the date representation in the ISO 8601 format
+ @c "YYYY-MM-DD".
*/
- bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
+ wxString FormatISODate() const;
/**
- Returns @true if this date is later than the given one.
+ This function returns the time representation in the ISO 8601 format
+ @c "HH:MM:SS".
*/
- bool IsLaterThan(const wxDateTime& datetime) const;
+ wxString FormatISOTime() const;
/**
- Returns @true if the @a year is a leap one in the specified calendar.
- This functions supports Gregorian and Julian calendars.
+ Identical to calling Format() with @c "%X" argument (which means
+ "preferred time representation for the current locale").
*/
- static bool IsLeapYear(int year = Inv_Year,
- Calendar cal = Gregorian);
+ wxString FormatTime() const;
/**
- Returns @true if the date is the same without comparing the time parts.
+ This function is like ParseDateTime(), but it only allows the date to
+ be specified. It is thus less flexible then ParseDateTime(), but also
+ has less chances to misinterpret the user input.
+
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
*/
- bool IsSameDate(const wxDateTime& dt) const;
+ const char* ParseDate(const wxString& date,
+ wxString::const_iterator* end = NULL);
+ /**
+ This function is like ParseDateTime(), but it only allows the date to
+ be specified. It is thus less flexible then ParseDateTime(), but also
+ has less chances to misinterpret the user input.
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
+ */
+ const char* ParseDate(const char* date);
/**
- Returns @true if the time is the same (although dates may differ).
+ This function is like ParseDateTime(), but it only allows the date to
+ be specified. It is thus less flexible then ParseDateTime(), but also
+ has less chances to misinterpret the user input.
+
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
*/
- bool IsSameTime(const wxDateTime& dt) const;
+ const wchar_t* ParseDate(const wchar_t* date);
/**
- Returns @true if this date lies strictly between the two others,
-
- @see IsBetween()
+ 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.
*/
- bool IsStrictlyBetween(const wxDateTime& t1,
- const wxDateTime& t2) const;
+ const char* ParseDateTime(const wxString& datetime,
+ wxString::const_iterator* end = NULL);
+ /**
+ Parses the string @a datetime containing the date and time in free
+ format. This function tries as hard as it can to interpret the given
+ string as date and time. Unlike ParseRfc822Date(), it will accept
+ anything that may be accepted and will only reject strings which can
+ not be parsed in any way at all.
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
+ */
+ const char* ParseDateTime(const char* datetime);
/**
- Returns @true if the object represents a valid time moment.
+ 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.
*/
- bool IsValid() const;
+ const wchar_t* ParseDateTime(const wchar_t* datetime);
/**
- This function returns @true if the specified (or default) country is one
- of Western European ones. It is used internally by wxDateTime to determine the
- DST convention and date and time formatting rules.
+ This function parses the string @a date according to the given
+ @e format. The system @c strptime(3) function is used whenever
+ available, but even if it is not, this function is still implemented,
+ although support for locale-dependent format specifiers such as
+ @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
+ as @c "%z" and @c "%Z" are not implemented. This function does handle
+ the month and weekday names in the current locale on all platforms,
+ however.
+
+ Please see the description of the ANSI C function @c strftime(3) for
+ the syntax of the format string.
+
+ The @a dateDef parameter is used to fill in the fields which could not
+ be determined from the format string. For example, if the format is
+ @c "%d" (the day of the month), the month and the year are taken from
+ @a dateDef. If it is not specified, Today() is used as the default
+ date.
+
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
*/
- static bool IsWestEuropeanCountry(Country country = Country_Default);
+ 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.
+
+ 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.
+ */
+ const char* ParseFormat(const char* date,
+ const wxString& format = wxDefaultDateTimeFormat,
+ const wxDateTime& dateDef = wxDefaultDateTime);
/**
- Returns @true is this day is not a holiday in the given country.
+ This function parses the string @a date according to the given
+ @e format. The system @c strptime(3) function is used whenever
+ available, but even if it is not, this function is still implemented,
+ although support for locale-dependent format specifiers such as
+ @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
+ as @c "%z" and @c "%Z" are not implemented. This function does handle
+ the month and weekday names in the current locale on all platforms,
+ however.
+
+ Please see the description of the ANSI C function @c strftime(3) for
+ the syntax of the format string.
+
+ The @a dateDef parameter is used to fill in the fields which could not
+ be determined from the format string. For example, if the format is
+ @c "%d" (the day of the month), the month and the year are taken from
+ @a dateDef. If it is not specified, Today() is used as the default
+ date.
+
+ @return @NULL if the conversion failed, otherwise return the pointer
+ to the character which stopped the scan.
*/
- bool IsWorkDay(Country country = Country_Default) const;
+ const wchar_t* ParseFormat(const wchar_t* date,
+ const wxString& format = wxDefaultDateTimeFormat,
+ const wxDateTime& dateDef = wxDefaultDateTime);
/**
- Same as FromTimezone() but modifies the object
- in place.
+ This function parses the string containing the date and time in ISO
+ 8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between
+ the date and time parts must be equal to @a sep for the function to
+ succeed.
+
+ @return @true if the entire string was parsed successfully, @false
+ otherwise.
*/
- wxDateTime MakeFromTimezone(const TimeZone& tz,
- bool noDST = false);
+ bool ParseISOCombined(const wxString& date, char sep = 'T');
/**
- Modifies the object in place to represent the date in another time zone. If
- @a noDST is @true, no DST adjustments will be made.
+ This function parses the date in ISO 8601 format @c "YYYY-MM-DD".
+
+ @return @true if the entire string was parsed successfully, @false
+ otherwise.
*/
- wxDateTime MakeTimezone(const TimeZone& tz,
- bool noDST = false);
+ bool ParseISODate(const wxString& date);
/**
- This is the same as calling MakeTimezone() with
- the argument @c GMT0.
+ This function parses the time in ISO 8601 format @c "HH:MM:SS".
+
+ @return @true if the entire string was parsed successfully, @false
+ otherwise.
*/
- wxDateTime MakeUTC(bool noDST = false);
+ bool ParseISOTime(const wxString& date);
/**
- Returns the object corresponding to the current time.
- Example:
-
- Note that this function is accurate up to second:
- UNow() should be used for better precision
- (but it is less efficient and might not be available on all platforms).
-
- @see Today()
+ 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.
*/
- static wxDateTime Now();
+ 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);
/**
- 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.
+ 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 which stopped the scan.
+ 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* ParseDate(const wxString& date,
- wxString::const_iterator* end = NULL);
- const char* ParseDate(const char* date);
- const wchar_t* ParseDate(const wchar_t* date);
+ 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.
+ */
+ 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);
+
//@}
- //@{
+
+
+ /**
+ @name Calendar Calculations
+
+ The functions in this section perform the basic calendar calculations,
+ mostly related to the week days. They allow to find the given week day
+ in the week with given number (either in the month or in the year) and
+ so on.
+
+ None of the functions in this section modify the time part of the
+ wxDateTime, they only work with the date part of it.
+ */
+ //@{
+
+ /**
+ Returns the copy of this object to which SetToLastMonthDay() was
+ applied.
+ */
+ wxDateTime GetLastMonthDay(Month month = Inv_Month,
+ int year = Inv_Year) const;
+
+ /**
+ Returns the copy of this object to which SetToLastWeekDay() was
+ applied.
+ */
+ wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month,
+ int year = Inv_Year);
+
+ /**
+ Returns the copy of this object to which SetToNextWeekDay() was
+ applied.
+ */
+ wxDateTime GetNextWeekDay(WeekDay weekday) const;
+
+ /**
+ Returns the copy of this object to which SetToPrevWeekDay() was
+ applied.
+ */
+ wxDateTime GetPrevWeekDay(WeekDay weekday) const;
+
+ /**
+ Returns the copy of this object to which SetToWeekDay() was applied.
+ */
+ wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month,
+ int year = Inv_Year) const;
+
+ /**
+ Returns the copy of this object to which SetToWeekDayInSameWeek() was
+ applied.
+ */
+ wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
+ WeekFlags flags = Monday_First) const;
+
+ /**
+ Returns the copy of this object to which SetToYearDay() was applied.
+ */
+ wxDateTime GetYearDay(wxDateTime_t yday) const;
+
+ /**
+ Sets the date to the last day in the specified month (the current one
+ by default).
+
+ @return The reference to the modified object itself.
+ */
+ wxDateTime SetToLastMonthDay(Month month = Inv_Month,
+ int year = Inv_Year);
+
+ /**
+ The effect of calling this function is the same as of calling
+ @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
+ last @a weekday in the given month and year (the current ones by
+ default). Always returns @true.
+ */
+ bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
+ int year = Inv_Year);
+
+ /**
+ Sets the date so that it will be the first @a weekday following the
+ current date.
+
+ @return The reference to the modified object itself.
+ */
+ wxDateTime& SetToNextWeekDay(WeekDay weekday);
+
+ /**
+ Sets the date so that it will be the last @a weekday before the current
+ date.
+
+ @return The reference to the modified object itself.
+ */
+ wxDateTime& SetToPrevWeekDay(WeekDay weekday);
+
+ /**
+ Sets the date to the @e n-th @a weekday in the given month of the given
+ year (the current month and year are used by default). The parameter
+ @a n may be either positive (counting from the beginning of the month)
+ or negative (counting from the end of it).
+
+ For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
+ second Wednesday in the current month and
+ SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
+ in the current month.
+
+ @return @true if the date was modified successfully, @false otherwise
+ meaning that the specified date doesn't exist.
+ */
+ bool SetToWeekDay(WeekDay weekday, int n = 1,
+ Month month = Inv_Month, int year = Inv_Year);
+
+ /**
+ Adjusts the date so that it will still lie in the same week as before,
+ but its week day will be the given one.
+
+ @return The reference to the modified object itself.
+ */
+ wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
+ WeekFlags flags = Monday_First);
+
+ /**
+ 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.
+
+ @return The reference to the modified object itself.
+ */
+ wxDateTime& SetToYearDay(wxDateTime_t yday);
+
+ //@}
+
+
+
+ /**
+ @name Astronomical/Historical Functions
+
+ Some degree of support for the date units used in astronomy and/or
+ history is provided. You can construct a wxDateTime object from a
+ JDN and you may also get its JDN, MJD or Rata Die number from it.
+
+ Related functions in other groups: wxDateTime(double), Set(double)
+ */
+ //@{
+
+ /**
+ Synonym for GetJulianDayNumber().
+ */
+ double GetJDN() const;
+
+ /**
+ Returns the JDN corresponding to this date. Beware of rounding errors!
+
+ @see GetModifiedJulianDayNumber()
+ */
+ double GetJulianDayNumber() const;
+
+ /**
+ Synonym for GetModifiedJulianDayNumber().
+ */
+ double GetMJD() const;
+
+ /**
+ 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.
+ */
+ double GetModifiedJulianDayNumber() const;
+
/**
- 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 wxDateTime::ParseRfc822Date, it
- will accept anything that may be accepted and will only reject strings which
- can not be parsed in any way at all.
- Returns @NULL if the conversion failed, otherwise return the pointer to
- the character which stopped the scan.
+ Return the @e Rata Die number of this date.
+
+ By definition, the Rata Die number is a date specified as the number of
+ days relative to a base date of December 31 of the year 0. Thus January
+ 1 of the year 1 is Rata Die day 1.
*/
- const char* ParseDateTime(const wxString& datetime,
- wxString::const_iterator* end = NULL);
- const char* ParseDateTime(const char* datetime);
- const wchar_t* ParseDateTime(const wchar_t* datetime);
+ double GetRataDie() const;
+
//@}
- //@{
+
+
/**
- This function parses the string @a date according to the given
- @e format. The system @c strptime(3) function is used whenever available,
- but even if it is not, this function is still implemented, although support
- for locale-dependent format specifiers such as @c "%c", @c "%x" or @c "%X" may
- not be perfect and GNU extensions such as @c "%z" and @c "%Z" are
- not implemented. This function does handle the month and weekday
- names in the current locale on all platforms, however.
- Please see the description of the ANSI C function @c strftime(3) for the syntax
- of the format string.
- The @a dateDef parameter is used to fill in the fields which could not be
- determined from the format string. For example, if the format is @c "%d" (the
- ay of the month), the month and the year are taken from @e dateDef. If
- it is not specified, Today() is used as the
- default date.
- Returns @NULL if the conversion failed, otherwise return the pointer to
- the character which stopped the scan.
+ @name Time Zone and DST Support
+
+ Please see the @ref overview_datetime_timezones "time zone overview"
+ for more information about time zones. Normally, these functions should
+ be rarely used.
+
+ Related functions in other groups: GetBeginDST(), GetEndDST()
*/
- const char* ParseFormat(const wxString& date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime,
- wxString::const_iterator* end = NULL);
- const char* ParseFormat(const char* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
- const wchar_t* ParseFormat(const wchar_t* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
- //@}
+ //@{
/**
- This function parses the string containing the date and time in ISO 8601
- combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time
- parts must be equal to @a sep for the function to succeed.
- Returns @true if the entire string was parsed successfully, @false
- otherwise.
+ Transform the date from the given time zone to the local one. If
+ @a noDST is @true, no DST adjustments will be made.
+
+ @return The date in the local time zone.
*/
- bool ParseISOCombined(const wxString& date, char sep = 'T');
+ wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const;
/**
- This function parses the date in ISO 8601 format (YYYY-MM-DD).
- Returns @true if the entire string was parsed successfully, @false
- otherwise.
+ Returns @true if the DST is applied for this date in the given country.
+
+ @see GetBeginDST(), GetEndDST()
*/
- bool ParseISODate(const wxString& date);
+ int IsDST(Country country = Country_Default) const;
/**
- This function parses the time in ISO 8601 format (HH:MM:SS).
- Returns @true if the entire string was parsed successfully, @false
- otherwise.
+ Same as FromTimezone() but modifies the object in place.
*/
- bool ParseISOTime(const wxString& date);
+ wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false);
- //@{
/**
- 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.
+ Modifies the object in place to represent the date in another time
+ zone. If @a noDST is @true, no DST adjustments will be made.
*/
- const char* ParseRfc822Date(const wxString& date,
- wxString::const_iterator* end = NULL);
- const char* ParseRfc822Date(const char* date);
- const wchar_t* ParseRfc822Date(const wchar_t* date);
- //@}
+ wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false);
- //@{
/**
- This functions is like ParseDateTime(), but
- only allows the time to be specified in the input string.
- Returns @NULL if the conversion failed, otherwise return the pointer to
- the character which stopped the scan.
+ This is the same as calling MakeTimezone() with the argument @c GMT0.
*/
- const char* ParseTime(const wxString& time,
- wxString::const_iterator* end = NULL);
- const char* ParseTime(const char* time);
- const wchar_t* ParseTime(const wchar_t* time);
- //@}
+ wxDateTime& MakeUTC(bool noDST = false);
/**
- These 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
- wxDateTime::FormatTime), using the international standard
- representation defined by ISO 8601 (
- FormatISODate(),
- FormatISOTime() and
- wxDateTime::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. wxDateTime::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.
- But the most interesting functions are
- ParseTime(),
- ParseDate() and
- ParseDateTime(). They try to parse the date
- ans 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 @c "tomorrow", @c "March first" and even
- @c "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.
- ParseFormat()
-
- ParseDateTime()
-
- ParseDate()
-
- ParseTime()
-
- ParseISODate()
-
- ParseISOTime()
-
- ParseISOCombined()
-
- wxDateTime::ParseRfc822Date
-
- Format()
-
- FormatDate()
-
- FormatTime()
-
- FormatISOCombined()
-
- FormatISODate()
-
- FormatISOTime()
- */
+ Transform the date to the given time zone. If @a noDST is @true, no DST
+ adjustments will be made.
+ @return The date in the new time zone.
+ */
+ wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
/**
- Reset time to midnight (00:00:00) without changing the date.
+ This is the same as calling ToTimezone() with the argument @c GMT0.
*/
- wxDateTime ResetTime();
+ wxDateTime ToUTC(bool noDST = false) const;
+
+ //@}
+
+
+
+
/**
- Sets the date and time from the parameters.
+ 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.
+
+ This function should be used like this:
+
+ @code
+ wxDateTime dt(...);
+ int y = dt.GetYear();
+ printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
+ @endcode
*/
- wxDateTime Set(wxDateTime_t day, Month month = Inv_Month,
- int year = Inv_Year,
- wxDateTime_t hour = 0,
- wxDateTime_t minute = 0,
- wxDateTime_t second = 0,
- wxDateTime_t millisec = 0);
+ static int ConvertYearToBC(int year);
/**
- 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
- @ref overview_wxdatetime "wxDateTime constants section".
-
- @see GetCountry()
+ Returns the translations of the strings @c AM and @c PM used for time
+ formatting for the current locale. Either of the pointers may be @NULL
+ if the corresponding value is not needed.
*/
- static void SetCountry(Country country);
+ static void GetAmPmStrings(wxString* am, wxString* pm);
/**
- Sets the day without changing other date components.
+ Get the beginning of DST for the given country in the given year
+ (current one by default). This function suffers from limitations
+ described in the @ref overview_datetime_dst "DST overview".
+
+ @see GetEndDST()
*/
- wxDateTime SetDay(wxDateTime_t day);
+ static wxDateTime GetBeginDST(int year = Inv_Year,
+ Country country = Country_Default);
/**
- Sets the date from the date and time in
- DOS
- format.
+ Returns the end of DST for the given country in the given year (current
+ one by default).
+
+ @see GetBeginDST()
*/
- wxDateTime Set(unsigned long ddt);
+ static wxDateTime GetEndDST(int year = Inv_Year,
+ Country country = Country_Default);
/**
- Sets the hour without changing other date components.
+ Get the current century, i.e. first two digits of the year, in given
+ calendar (only Gregorian is currently supported).
*/
- wxDateTime SetHour(wxDateTime_t hour);
+ static int GetCentury(int year);
/**
- Sets the millisecond without changing other date components.
+ Returns the current default country. The default country is used for
+ DST calculations, for example.
+
+ @see SetCountry()
*/
- wxDateTime SetMillisecond(wxDateTime_t millisecond);
+ static Country GetCountry();
/**
- Sets the minute without changing other date components.
+ Get the current month in given calendar (only Gregorian is currently
+ supported).
*/
- wxDateTime SetMinute(wxDateTime_t minute);
+ static Month GetCurrentMonth(Calendar cal = Gregorian);
/**
- Sets the month without changing other date components.
+ Get the current year in given calendar (only Gregorian is currently
+ supported).
*/
- wxDateTime SetMonth(Month month);
+ static int GetCurrentYear(Calendar cal = Gregorian);
/**
- Sets the second without changing other date components.
+ Gets the full (default) or abbreviated (specify @c Name_Abbr name of
+ the given month.
+
+ @see GetWeekDayName()
*/
- wxDateTime SetSecond(wxDateTime_t second);
+ static wxString GetMonthName(Month month, NameFlags flags = Name_Full);
/**
- Sets the date and time of to the current values. Same as assigning the result
- of Now() to this object.
+ 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
*/
- wxDateTime SetToCurrent();
+ static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
/**
- Sets the date to the last day in the specified month (the current one by
- default).
- Returns the reference to the modified object itself.
+ 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
*/
- wxDateTime SetToLastMonthDay(Month month = Inv_Month,
- int year = Inv_Year);
+ static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
+ Calendar cal = Gregorian);
/**
- The effect of calling this function is the same as of calling
- @c SetToWeekDay(-1, weekday, month, year). The date will be set to the last
- @a weekday in the given month and year (the current ones by default).
- Always returns @true.
+ Returns the current time.
*/
- bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
- int year = Inv_Year);
+ static time_t GetTimeNow();
/**
- Sets the date so that it will be the first @a weekday following the current
- date.
- Returns the reference to the modified object itself.
+ Returns the current time broken down using the buffer whose adress is
+ passed to the function with @a tm to store the result.
*/
- wxDateTime SetToNextWeekDay(WeekDay weekday);
+ static struct tm* GetTmNow(struct tm *tm);
/**
- Sets the date so that it will be the last @a weekday before the current
- date.
- Returns the reference to the modified object itself.
+ Returns the current time broken down. Note that this function returns a
+ pointer to a static buffer that's reused by calls to this function and
+ certain C library functions (e.g. localtime). If there is any chance
+ your code might be used in a multi-threaded application, you really
+ should use GetTmNow(struct tm *) instead.
*/
- wxDateTime SetToPrevWeekDay(WeekDay weekday);
+ static struct tm* GetTmNow();
/**
- Sets the date to the @e n-th @a weekday in the given month of the given
- year (the current month and year are used by default). The parameter @e n
- may be either positive (counting from the beginning of the month) or negative
- (counting from the end of it).
- For example, @c SetToWeekDay(2, wxDateTime::Wed) will set the date to the
- second Wednesday in the current month and
- @c SetToWeekDay(-1, wxDateTime::Sun) -- to the last Sunday in it.
- Returns @true if the date was modified successfully, @false
- otherwise meaning that the specified date doesn't exist.
+ Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
+ the given week day.
+
+ @see GetMonthName()
*/
- bool SetToWeekDay(WeekDay weekday, int n = 1,
- Month month = Inv_Month,
- int year = Inv_Year);
+ static wxString GetWeekDayName(WeekDay weekday,
+ NameFlags flags = Name_Full);
/**
- Adjusts the date so that it will still lie in the same week as before, but its
- week day will be the given one.
- Returns the reference to the modified object itself.
+ Returns @true if DST was used n the given year (the current one by
+ default) in the given country.
*/
- wxDateTime SetToWeekDayInSameWeek(WeekDay weekday,
- WeekFlags flags = Monday_First);
+ static bool IsDSTApplicable(int year = Inv_Year,
+ Country country = Country_Default);
/**
- Set the date to the given @a weekday in the week number @a numWeek of the
- given @a year . The number should be in range 1...53.
- Note that the returned date may be in a different year than the one passed to
- this function because both the week 1 and week 52 or 53 (for leap years)
- contain days from different years. See
- GetWeekOfYear() for the explanation of how the
- year weeks are counted.
+ Returns @true if the @a year is a leap one in the specified calendar.
+ This functions supports Gregorian and Julian calendars.
*/
- static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
- WeekDay weekday = Mon);
+ static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian);
/**
- 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.
- Returns the reference to the modified object itself.
+ This function returns @true if the specified (or default) country is
+ one of Western European ones. It is used internally by wxDateTime to
+ determine the DST convention and date and time formatting rules.
*/
- wxDateTime SetToYearDay(wxDateTime_t yday);
+ static bool IsWestEuropeanCountry(Country country = Country_Default);
/**
- Sets the year without changing other date components.
- */
- wxDateTime SetYear(int year);
-
- /**
- For convenience, all static functions are collected here. These 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 @e Calendar
- parameter, it is currently ignored as only the Gregorian calendar is
- supported. Future versions will support other calendars.
-
- SetCountry()
-
- GetCountry()
-
- IsWestEuropeanCountry()
-
- GetCurrentYear()
-
- ConvertYearToBC()
-
- GetCurrentMonth()
-
- IsLeapYear()
-
- @ref getcenturystatic() GetCentury
-
- GetNumberOfDays()
-
- GetNumberOfDays()
-
- GetMonthName()
-
- GetWeekDayName()
-
- GetAmPmStrings()
-
- IsDSTApplicable()
-
- GetBeginDST()
-
- GetEndDST()
-
- Now()
-
- UNow()
-
- Today()
- */
-
-
- /**
- Subtracts another date from this one and returns the difference between them
- as wxTimeSpan.
+ Returns the object corresponding to the current time.
+
+ Example:
+
+ @code
+ wxDateTime now = wxDateTime::Now();
+ 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.
+
+ @see Today()
*/
- wxTimeSpan Subtract(const wxDateTime& dt) const;
+ static wxDateTime Now();
/**
- Please see the @ref overview_tdatetimezones "time zone overview" for more
- information about time zones. Normally, these functions should be rarely used.
- FromTimezone()
-
- ToTimezone()
-
- MakeTimezone()
-
- MakeFromTimezone()
-
- ToUTC()
-
- MakeUTC()
-
- GetBeginDST()
-
- GetEndDST()
-
- IsDST()
- */
+ 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.
- /**
- Transform the date to the given time zone. If @a noDST is @true, no
- DST adjustments will be made.
- Returns the date in the new time zone.
+ @see GetCountry()
*/
- wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
+ static void SetCountry(Country country);
/**
- This is the same as calling ToTimezone() with
- the argument @c GMT0.
+ Set the date to the given @a weekday in the week number @a numWeek of
+ the given @a year . The number should be in range 1-53.
+
+ Note that the returned date may be in a different year than the one
+ passed to this function because both the week 1 and week 52 or 53 (for
+ leap years) contain days from different years. See GetWeekOfYear() for
+ the explanation of how the year weeks are counted.
*/
- wxDateTime ToUTC(bool noDST = false) const;
+ static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
+ WeekDay weekday = Mon);
/**
- 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).
-
+ 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).
+
@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).
-
+ milliseconds if a function to get time with such precision is available
+ on the current platform (supported under most Unices and Win32).
+
@see Now()
*/
static wxDateTime UNow();
-
- /**
- Same as @ref settm() Set.
- */
- wxDateTime operator(const struct tm& tm);
};
+/**
+ Global instance of an empty wxDateTime object.
+
+ @todo Would it be better to rename this wxNullDateTime so it's consistent
+ with the rest of the "empty/invalid/null" global objects?
+*/
+const wxDateTime wxDefaultDateTime;
+
/**
@class wxDateTimeWorkDays
@wxheader{datetime.h}
+ @todo Write wxDateTimeWorkDays documentation.
@library{wxbase}
- @category{FIXME}
+ @category{data}
*/
class wxDateTimeWorkDays
{
@@ -1185,93 +1531,94 @@ public:
Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
Because of this feature, adding and subtracting back again the same
- wxDateSpan will @b not, in general give back the original date: Feb 28 - 1
+ wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
month will be Jan 28, not Jan 31!
wxDateSpan objects can be either positive or negative. They may be
multiplied by scalars which multiply all deltas by the scalar: i.e.
- 2*(1 month and 1 day) is 2 months and 2 days. They can
- be added together and with wxDateTime or
- wxTimeSpan, but the type of result is different for each
+ 2*(1 month and 1 day) is 2 months and 2 days. They can be added together
+ with wxDateTime or wxTimeSpan, but the type of result is different for each
case.
- Beware about weeks: if you specify both weeks and days, the total number of
- days added will be 7*weeks + days! See also GetTotalDays()
- function.
+ @warning If you specify both weeks and days, the total number of days added
+ will be 7*weeks + days! See also GetTotalDays().
- Equality operators are defined for wxDateSpans. Two datespans are equal if
- and only if they both give the same target date when added to @b every
- source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30),
- because they don't give the same date when added to 1 Feb. But
- wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2)
+ Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
+ if and only if they both give the same target date when added to @b every
+ source date. Thus wxDateSpan::Months(1) is not equal to
+ wxDateSpan::Days(30), because they don't give the same date when added to
+ Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
- Finally, notice that for adding hours, minutes and so on you don't need this
- class at all: wxTimeSpan will do the job because there
- are no subtleties associated with those (we don't support leap seconds).
+ Finally, notice that for adding hours, minutes and so on you don't need
+ this class at all: wxTimeSpan will do the job because there are no
+ subtleties associated with those (we don't support leap seconds).
@library{wxbase}
@category{data}
- @see @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime
+ @see @ref overview_datetime, wxDateTime
*/
class wxDateSpan
{
public:
/**
- Constructs the date span object for the given number of years, months, weeks
- and days. Note that the weeks and days add together if both are given.
+ Constructs the date span object for the given number of years, months,
+ weeks and days. Note that the weeks and days add together if both are
+ given.
*/
- wxDateSpan(int years = 0, int months = 0, int weeks = 0,
- int days = 0);
+ wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0);
- //@{
/**
- Returns the sum of two date spans. The first version returns a new object, the
- second and third ones modify this object in place.
+ Returns the sum of two date spans.
+
+ @return A new wxDateSpan object with the result.
*/
- wxDateSpan Add(const wxDateSpan& other);
- const wxDateSpan& Add(const wxDateSpan& other);
- wxDateSpan operator+=(const wxDateSpan& other);
- //@}
+ wxDateSpan Add(const wxDateSpan& other) const;
+ /**
+ Adds the given wxDateSpan to this wxDateSpan and returns a reference
+ to itself.
+ */
+ wxDateSpan& Add(const wxDateSpan& other);
/**
Returns a date span object corresponding to one day.
-
+
@see Days()
*/
static wxDateSpan Day();
/**
Returns a date span object corresponding to the given number of days.
-
+
@see Day()
*/
static wxDateSpan Days(int days);
/**
- Returns the number of days (only, that it not counting the weeks component!)
- in this date span.
-
+ Returns the number of days (not counting the weeks component) in this
+ date span.
+
@see GetTotalDays()
*/
int GetDays() const;
/**
- Returns the number of the months (not counting the years) in this date span.
+ Returns the number of the months (not counting the years) in this date
+ span.
*/
int GetMonths() const;
/**
- Returns the combined number of days in this date span, counting both weeks and
- days. It still doesn't take neither months nor years into the account.
-
+ Returns the combined number of days in this date span, counting both
+ weeks and days. This doesn't take months or years into account.
+
@see GetWeeks(), GetDays()
*/
int GetTotalDays() const;
/**
Returns the number of weeks in this date span.
-
+
@see GetTotalDays()
*/
int GetWeeks() const;
@@ -1283,120 +1630,150 @@ public:
/**
Returns a date span object corresponding to one month.
-
+
@see Months()
*/
static wxDateSpan Month();
/**
Returns a date span object corresponding to the given number of months.
-
+
@see Month()
*/
static wxDateSpan Months(int mon);
- //@{
/**
- Returns the product of the date span by the specified @e factor. The
- product is computed by multiplying each of the components by the factor.
- The first version returns a new object, the second and third ones modify this
- object in place.
+ Returns the product of the date span by the specified @a factor. The
+ product is computed by multiplying each of the components by the
+ @a factor.
+
+ @return A new wxDateSpan object with the result.
*/
- wxDateSpan Multiply(int factor);
- const wxDateSpan& Multiply(int factor);
- wxDateSpan operator*=(int factor);
- //@}
+ wxDateSpan Multiply(int factor) const;
+ /**
+ Multiplies this date span by the specified @a factor. The product is
+ computed by multiplying each of the components by the @a factor.
+
+ @return A reference to this wxDateSpan object modified in place.
+ */
+ wxDateSpan& Multiply(int factor);
- //@{
/**
Changes the sign of this date span.
-
+
@see Negate()
*/
- wxDateSpan Neg();
- wxDateSpan operator-();
- //@}
+ wxDateSpan& Neg();
/**
- Returns the date span with the opposite sign.
-
+ Returns a date span with the opposite sign.
+
@see Neg()
*/
wxDateSpan Negate() const;
/**
- Sets the number of days (without modifying any other components) in this date
- span.
+ Sets the number of days (without modifying any other components) in
+ this date span.
*/
- wxDateSpan SetDays(int n);
+ wxDateSpan& SetDays(int n);
/**
- Sets the number of months (without modifying any other components) in this
- date span.
+ Sets the number of months (without modifying any other components) in
+ this date span.
*/
- wxDateSpan SetMonths(int n);
+ wxDateSpan& SetMonths(int n);
/**
- Sets the number of weeks (without modifying any other components) in this date
- span.
+ Sets the number of weeks (without modifying any other components) in
+ this date span.
*/
- wxDateSpan SetWeeks(int n);
+ wxDateSpan& SetWeeks(int n);
/**
- Sets the number of years (without modifying any other components) in this date
- span.
+ Sets the number of years (without modifying any other components) in
+ this date span.
*/
- wxDateSpan SetYears(int n);
+ wxDateSpan& SetYears(int n);
- //@{
/**
- Returns the difference of two date spans. The first version returns a new
- object, the second and third ones modify this object in place.
+ Returns the difference of two date spans.
+
+ @return A new wxDateSpan object with the result.
*/
- wxDateSpan Subtract(const wxDateSpan& other);
- const wxDateSpan& Subtract(const wxDateSpan& other);
- wxDateSpan operator+=(const wxDateSpan& other);
- //@}
+ wxDateSpan Subtract(const wxDateSpan& other) const;
+ /**
+ Subtracts the given wxDateSpan to this wxDateSpan and returns a
+ reference to itself.
+ */
+ wxDateSpan& Subtract(const wxDateSpan& other);
/**
Returns a date span object corresponding to one week.
-
+
@see Weeks()
*/
static wxDateSpan Week();
/**
Returns a date span object corresponding to the given number of weeks.
-
+
@see Week()
*/
static wxDateSpan Weeks(int weeks);
/**
Returns a date span object corresponding to one year.
-
+
@see Years()
*/
static wxDateSpan Year();
/**
Returns a date span object corresponding to the given number of years.
-
+
@see Year()
*/
static wxDateSpan Years(int years);
+ /**
+ Adds the given wxDateSpan to this wxDateSpan and returns the result.
+ */
+ wxDateSpan& operator+=(const wxDateSpan& other);
+
+ /**
+ Subtracts the given wxDateSpan to this wxDateSpan and returns the
+ result.
+ */
+ wxDateSpan& operator-=(const wxDateSpan& other);
+
+ /**
+ Changes the sign of this date span.
+
+ @see Negate()
+ */
+ wxDateSpan& operator-();
+
+ /**
+ Multiplies this date span by the specified @a factor. The product is
+ computed by multiplying each of the components by the @a factor.
+
+ @return A reference to this wxDateSpan object modified in place.
+ */
+ wxDateSpan& operator*=(int factor);
+
/**
Returns @true if this date span is different from the other one.
*/
- bool operator!=(wxDateSpan& other) const;
+ bool operator!=(const wxDateSpan&) const;
/**
- Returns @true if this date span is equal to the other one. Two date spans
- are considered equal if and only if they have the same number of years and
- months and the same total number of days (counting both days and weeks).
+ Returns @true if this date span is equal to the other one. Two date
+ spans are considered equal if and only if they have the same number of
+ years and months and the same total number of days (counting both days
+ and weeks).
*/
- bool operator==(wxDateSpan& other) const;
+ bool operator==(const wxDateSpan&) const;
};
@@ -1410,55 +1787,38 @@ public:
@library{wxbase}
@category{data}
- @see @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime
+ @see @ref overview_datetime, wxDateTime
*/
class wxTimeSpan
{
public:
- //@{
/**
- Constructs timespan from separate values for each component, with the date
- set to 0. Hours are not restricted to 0..24 range, neither are
- minutes, seconds or milliseconds.
+ Default constructor, constructs a zero timespan.
*/
wxTimeSpan();
+ /**
+ Constructs timespan from separate values for each component, with the
+ 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);
- //@}
/**
- Returns the absolute value of the timespan: does not modify the
- object.
+ Returns the absolute value of the timespan: does not modify the object.
*/
wxTimeSpan Abs() const;
/**
- GetSeconds()
-
- GetMinutes()
-
- GetHours()
-
- GetDays()
-
- GetWeeks()
-
- GetValue()
- */
+ Returns the sum of two time spans.
-
- //@{
- /**
- Returns the sum of two timespans.
+ @return A new wxDateSpan object with the result.
*/
- wxTimeSpan Add(const wxTimeSpan& diff);
- const wxTimeSpan& Add(const wxTimeSpan& diff);
- wxTimeSpan operator+=(const wxTimeSpan& diff);
- //@}
-
+ wxTimeSpan Add(const wxTimeSpan& diff) const;
/**
- @ref ctor() wxTimeSpan
+ Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
+ to itself.
*/
-
+ wxTimeSpan& Add(const wxTimeSpan& diff);
/**
Returns the timespan for one day.
@@ -1471,54 +1831,32 @@ public:
static wxTimespan Days(long days);
/**
- Returns the string containing the formatted representation of the time span.
- The following format specifiers are allowed after %:
-
- H
-
- number of @b Hours
-
- M
-
- number of @b Minutes
-
- S
-
- number of @b Seconds
-
- l
-
- number of mi@b lliseconds
-
- D
-
- number of @b Days
-
- E
-
- number of w@b Eeks
-
- %
-
- the percent character
-
- Note that, for example, the number of hours in the description above is not
- well defined: it can be either the total number of hours (for example, for a
- time span of 50 hours this would be 50) or just the hour part of the time
- span, which would be 2 in this case as 50 hours is equal to 2 days and
- 2 hours.
- wxTimeSpan resolves this ambiguity in the following way: if there had been,
- indeed, the @c %D format specified preceding the @c %H, then it is
- interpreted as 2. Otherwise, it is 50.
- The same applies to all other format specifiers: if they follow a specifier of
- larger unit, only the rest part is taken, otherwise the full value is used.
- */
- wxString Format(const wxChar* format = wxDefaultTimeSpanFormat);
-
- /**
- Format()
- */
+ Returns the string containing the formatted representation of the time
+ span. The following format specifiers are allowed after %:
+
+ - @c H - Number of Hours
+ - @c M - Number of Minutes
+ - @c S - Number of Seconds
+ - @c l - Number of Milliseconds
+ - @c D - Number of Days
+ - @c E - Number of Weeks
+ - @c % - The percent character
+ Note that, for example, the number of hours in the description above is
+ not well defined: it can be either the total number of hours (for
+ example, for a time span of 50 hours this would be 50) or just the hour
+ part of the time span, which would be 2 in this case as 50 hours is
+ equal to 2 days and 2 hours.
+
+ wxTimeSpan resolves this ambiguity in the following way: if there had
+ been, indeed, the @c %D format specified preceding the @c %H, then it
+ is interpreted as 2. Otherwise, it is 50.
+
+ The same applies to all other format specifiers: if they follow a
+ specifier of larger unit, only the rest part is taken, otherwise the
+ full value is used.
+ */
+ wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
/**
Returns the difference in number of days.
@@ -1571,9 +1909,9 @@ public:
bool IsEqualTo(const wxTimeSpan& ts) const;
/**
- 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.
+ 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.
*/
bool IsLongerThan(const wxTimeSpan& ts) const;
@@ -1593,9 +1931,9 @@ public:
bool IsPositive() const;
/**
- 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.
+ 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.
*/
bool IsShorterThan(const wxTimeSpan& ts) const;
@@ -1619,42 +1957,32 @@ public:
*/
static wxTimespan Minutes(long min);
- //@{
/**
- Multiplies timespan by a scalar.
+ Returns the product of this time span by @a n.
+
+ @return A new wxTimeSpan object with the result.
*/
- wxTimeSpan Multiply(int n);
- const wxTimeSpan& Multiply(int n);
- wxTimeSpan operator*=(int n);
- //@}
+ wxTimeSpan Multiply(int n) const;
+ /**
+ Multiplies this time span by @a n.
+
+ @return A reference to this wxTimeSpan object modified in place.
+ */
+ wxTimeSpan& Multiply(int n);
- //@{
/**
Negate the value of the timespan.
+
+ @see Negate()
*/
- wxTimeSpan Neg();
- wxTimeSpan operator-();
- //@}
+ wxTimeSpan& Neg();
/**
Returns timespan with inverted sign.
- */
- wxTimeSpan Negate() const;
- /**
- Add()
-
- Subtract()
-
- Multiply()
-
- Negate()
-
- Neg()
-
- Abs()
+ @see Neg()
*/
-
+ wxTimeSpan Negate() const;
/**
Returns the timespan for one second.
@@ -1667,65 +1995,51 @@ public:
static wxTimespan Seconds(long sec);
/**
- Milliseconds()
-
- Millisecond()
-
- Seconds()
-
- Second()
-
- Minutes()
-
- Minute()
-
- Hours()
-
- Hour()
-
- Days()
-
- Day()
-
- Weeks()
-
- Week()
+ Returns the difference of two time spans.
+
+ @return A new wxDateSpan object with the result.
+ */
+ wxTimeSpan Subtract(const wxTimeSpan& diff) const;
+ /**
+ Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
+ reference to itself.
*/
+ wxTimeSpan& Subtract(const wxTimeSpan& diff);
+ /**
+ Returns the timespan for one week.
+ */
+ static wxTimespan Week();
- //@{
/**
- Returns the difference of two timespans.
+ Returns the timespan for the given number of weeks.
*/
- wxTimeSpan Subtract(const wxTimeSpan& diff);
- const wxTimeSpan& Subtract(const wxTimeSpan& diff);
- wxTimeSpan operator-=(const wxTimeSpan& diff);
- //@}
+ static wxTimespan Weeks(long weeks);
/**
- IsNull()
-
- IsPositive()
-
- IsNegative()
-
- IsEqualTo()
-
- IsLongerThan()
-
- IsShorterThan()
+ Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
*/
+ wxTimeSpan& operator+=(const wxTimeSpan& diff);
+
+ /**
+ Multiplies this time span by @a n.
+ @return A reference to this wxTimeSpan object modified in place.
+ */
+ wxTimeSpan& operator*=(int n);
/**
- Returns the timespan for one week.
+ Negate the value of the timespan.
+
+ @see Negate()
*/
- static wxTimespan Week();
+ wxTimeSpan& operator-();
/**
- Returns the timespan for the given number of weeks.
+ Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
+ result.
*/
- static wxTimespan Weeks(long weeks);
+ wxTimeSpan& operator-=(const wxTimeSpan& diff);
};
@@ -1734,9 +2048,10 @@ public:
@class wxDateTimeHolidayAuthority
@wxheader{datetime.h}
+ @todo Write wxDateTimeHolidayAuthority documentation.
@library{wxbase}
- @category{FIXME}
+ @category{misc}
*/
class wxDateTimeHolidayAuthority
{