// Purpose: interface of wxDateTime
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
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
+ messages on the Internet. This format cannot be described with
@c strptime(3)-like format strings used by Format(), hence the need for a
separate function.
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
+ ParseDate() can parse the strings such as "tomorrow", "March first" and
even "next Sunday".
Finally notice that each of the parsing functions is available in several
Local,
//@{
- /// zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+ /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be
/// consequent numbers, so writing something like `GMT0 + offset' is
/// safe if abs(offset) <= 12
Julian ///< calendar in use since -45 until the 1582 (or later)
};
+ /**
+ Values corresponding to different dates of adoption of the Gregorian
+ calendar.
+
+ @see IsGregorianDate
+ */
+ enum GregorianAdoption
+ {
+ Gr_Unknown, ///< no data for this country or it's too uncertain to use
+ Gr_Standard, ///< on the day 0 of Gregorian calendar: 15 Oct 1582
+
+ Gr_Alaska, ///< Oct 1867 when Alaska became part of the USA
+ Gr_Albania, ///< Dec 1912
+
+ Gr_Austria = Gr_Unknown, ///< Different regions on different dates
+ Gr_Austria_Brixen, ///< 5 Oct 1583 -> 16 Oct 1583
+ Gr_Austria_Salzburg = Gr_Austria_Brixen,
+ Gr_Austria_Tyrol = Gr_Austria_Brixen,
+ Gr_Austria_Carinthia, ///< 14 Dec 1583 -> 25 Dec 1583
+ Gr_Austria_Styria = Gr_Austria_Carinthia,
+
+ Gr_Belgium, ///< Then part of the Netherlands
+
+ Gr_Bulgaria = Gr_Unknown, ///< Unknown precisely (from 1915 to 1920)
+ Gr_Bulgaria_1, ///< 18 Mar 1916 -> 1 Apr 1916
+ Gr_Bulgaria_2, ///< 31 Mar 1916 -> 14 Apr 1916
+ Gr_Bulgaria_3, ///< 3 Sep 1920 -> 17 Sep 1920
+
+ Gr_Canada = Gr_Unknown, ///< Different regions followed the changes in
+ ///< Great Britain or France
+
+ Gr_China = Gr_Unknown, ///< Different authorities say:
+ Gr_China_1, ///< 18 Dec 1911 -> 1 Jan 1912
+ Gr_China_2, ///< 18 Dec 1928 -> 1 Jan 1929
+
+ Gr_Czechoslovakia, ///< (Bohemia and Moravia) 6 Jan 1584 -> 17 Jan 1584
+ Gr_Denmark, ///< (including Norway) 18 Feb 1700 -> 1 Mar 1700
+ Gr_Egypt, ///< 1875
+ Gr_Estonia, ///< 1918
+ Gr_Finland, ///< Then part of Sweden
+
+ Gr_France, ///< 9 Dec 1582 -> 20 Dec 1582
+ Gr_France_Alsace, ///< 4 Feb 1682 -> 16 Feb 1682
+ Gr_France_Lorraine, ///< 16 Feb 1760 -> 28 Feb 1760
+ Gr_France_Strasbourg, ///< February 1682
+
+ Gr_Germany = Gr_Unknown, ///< Different states on different dates:
+ Gr_Germany_Catholic, ///< 1583-1585 (we take 1584)
+ Gr_Germany_Prussia, ///< 22 Aug 1610 -> 2 Sep 1610
+ Gr_Germany_Protestant, ///< 18 Feb 1700 -> 1 Mar 1700
+
+ Gr_GreatBritain, ///< 2 Sep 1752 -> 14 Sep 1752 (use 'cal(1)')
+
+ Gr_Greece, ///< 9 Mar 1924 -> 23 Mar 1924
+ Gr_Hungary, ///< 21 Oct 1587 -> 1 Nov 1587
+ Gr_Ireland = Gr_GreatBritain,
+ Gr_Italy = Gr_Standard,
+
+ Gr_Japan = Gr_Unknown, ///< Different authorities say:
+ Gr_Japan_1, ///< 19 Dec 1872 -> 1 Jan 1873
+ Gr_Japan_2, ///< 19 Dec 1892 -> 1 Jan 1893
+ Gr_Japan_3, ///< 18 Dec 1918 -> 1 Jan 1919
+
+ Gr_Latvia, ///< 1915-1918 (we take 1915)
+ Gr_Lithuania, ///< 1915
+ Gr_Luxemburg, ///< 14 Dec 1582 -> 25 Dec 1582
+ Gr_Netherlands = Gr_Belgium, ///< (including Belgium) 1 Jan 1583
+
+ /**
+ Special case of Groningen.
+
+ The Gregorian calendar was introduced twice in Groningen, first
+ time 28 Feb 1583 was followed by 11 Mar 1583, then it has gone back
+ to Julian in the summer of 1584 and then 13 Dec 1700 was followed
+ by 12 Jan 1701 -- which is the date we take into account here.
+ */
+ Gr_Netherlands_Groningen, ///< 13 Dec 1700 -> 12 Jan 1701
+ Gr_Netherlands_Gelderland, ///< 30 Jun 1700 -> 12 Jul 1700
+ Gr_Netherlands_Utrecht, ///< (and Overijssel) 30 Nov 1700->12 Dec 1700
+ Gr_Netherlands_Friesland, ///< (and Drenthe) 31 Dec 1700 -> 12 Jan 1701
+
+ Gr_Norway = Gr_Denmark, ///< Then part of Denmark
+ Gr_Poland = Gr_Standard,
+ Gr_Portugal = Gr_Standard,
+ Gr_Romania, ///< 31 Mar 1919 -> 14 Apr 1919
+ Gr_Russia, ///< 31 Jan 1918 -> 14 Feb 1918
+ Gr_Scotland = Gr_GreatBritain,
+ Gr_Spain = Gr_Standard,
+
+ /**
+ Special case of Sweden.
+
+ Sweden has a curious history. Sweden decided to make a gradual
+ change from the Julian to the Gregorian calendar. By dropping every
+ leap year from 1700 through 1740 the eleven superfluous days would
+ be omitted and from 1 Mar 1740 they would be in sync with the
+ Gregorian calendar. (But in the meantime they would be in sync with
+ nobody!)
+
+ So 1700 (which should have been a leap year in the Julian calendar)
+ was not a leap year in Sweden. However, by mistake 1704 and 1708
+ became leap years. This left Sweden out of synchronisation with
+ both the Julian and the Gregorian world, so they decided to go back
+ to the Julian calendar. In order to do this, they inserted an extra
+ day in 1712, making that year a double leap year! So in 1712,
+ February had 30 days in Sweden.
+
+ Later, in 1753, Sweden changed to the Gregorian calendar by
+ dropping 11 days like everyone else and this is what we use here.
+ */
+ Gr_Sweden = Gr_Finland, ///< 17 Feb 1753 -> 1 Mar 1753
+
+ Gr_Switzerland = Gr_Unknown,///< Different cantons used different dates
+ Gr_Switzerland_Catholic, ///< 1583, 1584 or 1597 (we take 1584)
+ Gr_Switzerland_Protestant, ///< 31 Dec 1700 -> 12 Jan 1701
+
+ Gr_Turkey, ///< 1 Jan 1927
+ Gr_USA = Gr_GreatBritain,
+ Gr_Wales = Gr_GreatBritain,
+ Gr_Yugoslavia ///< 1919
+ };
+
/**
Date calculations often depend on the country and wxDateTime allows to set
the country whose conventions should be used using SetCountry(). It takes
in the functions whose result depends on it (GetWeekOfYear() and
GetWeekOfMonth()).
- The desired behvaiour may be specified by giving one of the following
+ The desired behaviour may be specified by giving one of the following
constants as argument to these functions.
*/
enum WeekFlags
};
+ /**
+ Class representing a time zone.
+
+ The representation is simply the offset, in seconds, from UTC.
+ */
+ class WXDLLIMPEXP_BASE TimeZone
+ {
+ public:
+ /// Constructor for a named time zone.
+ TimeZone(TZ tz);
+
+ /// Constructor for the given offset in seconds.
+ TimeZone(long offset = 0);
+
+ /// Create a time zone with the given offset in seconds.
+ static TimeZone Make(long offset);
+
+ /// Return the offset of this time zone from UTC, in seconds.
+ long GetOffset() const;
+ };
+
+ /**
+ Contains broken down date-time representation.
+
+ This struct is analogous to standard C <code>struct tm</code> and uses
+ the same, not always immediately obvious, conventions for its members:
+ notably its mon and mday fields count from 0 while yday counts from 1.
+ */
+ struct Tm
+ {
+ wxDateTime_t msec, ///< Number of milliseconds.
+ sec, ///< Seconds in 0..59 (60 with leap seconds) range.
+ min, ///< Minutes in 0..59 range.
+ hour, ///< Hours since midnight in 0..23 range.
+ mday, ///< Day of the month in 1..31 range.
+ yday; ///< Day of the year in 0..365 range.
+ Month mon; ///< Month, as an enumerated constant.
+ int year; ///< Year.
+
+ /**
+ Check if the given date/time is valid (in Gregorian calendar).
+
+ Return @false if the components don't correspond to a correct date.
+ */
+ bool IsValid() const;
+
+ /**
+ Return the week day corresponding to this date.
+
+ Unlike the other fields, the week day is not always available and
+ so must be accessed using this method as it is computed on demand
+ when it is called.
+ */
+ WeekDay GetWeekDay();
+ };
+
+
/**
@name Constructors, Assignment Operators and Setters
Constructors and various Set() methods are collected here. If you
construct a date object from separate values for day, month and year,
you should use IsValid() method to check that the values were correct
- as constructors can not return an error code.
+ as constructors cannot return an error code.
*/
//@{
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime(const struct _SYSTEMTIME& st);
Input, Windows SYSTEMTIME reference
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
Output, pointer to Windows SYSTEMTIME
@since 2.9.0
@remarks MSW only
+ @onlyfor{wxmsw}
*/
void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
/**
Adds the given date span to this object.
*/
- wxDateTime operator+=(const wxDateSpan& diff);
+ wxDateTime& operator+=(const wxDateSpan& diff);
/**
Subtracts the given date span from this object.
*/
Returns the combined date-time representation in the ISO 8601 format
@c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
the result exactly corresponding to the ISO standard, but it can also
- be useful to use a space as seprator if a more human-readable combined
+ be useful to use a space as separator if a more human-readable combined
date-time representation is needed.
@see FormatISODate(), FormatISOTime(), ParseISOCombined()
/**
This function is like ParseDateTime(), but it only allows the date to
- be specified. It is thus less flexible then ParseDateTime(), but also
- has less chances to misinterpret the user input.
+ be specified.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ It is thus less flexible then ParseDateTime(), but also has less
+ chances to misinterpret the user input.
- @see Format()
- */
- const char* ParseDate(const wxString& date,
- wxString::const_iterator* end = NULL);
+ See ParseFormat() for the description of function parameters and return
+ value.
- /**
- @overload
- */
- const char* ParseDate(const char* date);
-
- /**
- @overload
+ @see Format()
*/
- const wchar_t* ParseDate(const wchar_t* date);
+ bool ParseDate(const wxString& date, wxString::const_iterator *end);
/**
Parses the string @a datetime containing the date and time in free
- format. This function tries as hard as it can to interpret the given
- string as date and time. Unlike ParseRfc822Date(), it will accept
- anything that may be accepted and will only reject strings which can
- not be parsed in any way at all.
+ format.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
- */
- const char* ParseDateTime(const wxString& datetime,
- wxString::const_iterator* end = NULL);
+ This function tries as hard as it can to interpret the given string as
+ date and time. Unlike ParseRfc822Date(), it will accept anything that
+ may be accepted and will only reject strings which cannot be parsed in
+ any way at all. Notice that the function will fail if either date or
+ time part is present but not both, use ParseDate() or ParseTime() to
+ parse strings containing just the date or time component.
- /**
- @overload
+ See ParseFormat() for the description of function parameters and return
+ value.
*/
- const char* ParseDateTime(const char* datetime);
-
- /**
- @overload
- */
- const wchar_t* ParseDateTime(const wchar_t* datetime);
+ bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);
/**
This function parses the string @a date according to the given
@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.
+ Example of using this function:
+ @code
+ wxDateTime dt;
+ wxString str = "...";
+ wxString::const_iterator end;
+ if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) )
+ ... parsing failed ...
+ else if ( end == str.end() )
+ ... entire string parsed ...
+ else
+ ... wxString(end, str.end()) left over ...
+ @endcode
+
+ @param date
+ The string to be parsed.
+ @param format
+ strptime()-like format string.
+ @param dateDef
+ Used to fill in the date components not specified in the @a date
+ string.
+ @param end
+ Will be filled with the iterator pointing to the location where the
+ parsing stopped if the function returns @true. If the entire string
+ was consumed, it is set to @c date.end(). Notice that this argument
+ must be non-@NULL.
+ @return
+ @true if at least part of the string was parsed successfully,
+ @false otherwise.
@see Format()
*/
- const char* ParseFormat(const wxString& date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime,
- wxString::const_iterator* end = NULL);
+ bool ParseFormat(const wxString& date,
+ const wxString& format,
+ const wxDateTime& dateDef,
+ wxString::const_iterator *end);
/**
@overload
*/
- const char* ParseFormat(const char* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
+ bool ParseFormat(const wxString& date,
+ const wxString& format,
+ wxString::const_iterator *end);
/**
@overload
*/
- const wchar_t* ParseFormat(const wchar_t* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
+ bool ParseFormat(const wxString& date, wxString::const_iterator *end);
/**
This function parses the string containing the date and time in ISO
string which is not RFC 822 compliant. If you need to parse date
formatted in more free ways, you should use ParseDateTime() or
ParseDate() instead.
- */
- const char* ParseRfc822Date(const wxString& date,
- wxString::const_iterator* end = NULL);
- /**
- @overload
- */
- const char* ParseRfc822Date(const char* date);
-
- /**
- @overload
+ See ParseFormat() for the description of function parameters and return
+ value.
*/
- const wchar_t* ParseRfc822Date(const wchar_t* date);
+ bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
/**
This functions is like ParseDateTime(), but only allows the time to be
specified in the input string.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ See ParseFormat() for the description of function parameters and return
+ value.
*/
- const char* ParseTime(const wxString& time,
- wxString::const_iterator* end = NULL);
-
- /**
- @overload
- */
- const char* ParseTime(const char* time);
-
- /**
- @overload
- */
- const wchar_t* ParseTime(const wchar_t* time);
+ bool ParseTime(const wxString& time, wxString::const_iterator *end);
//@}
static int GetCurrentYear(Calendar cal = Gregorian);
/**
- Gets the full (default) or abbreviated (specify @c Name_Abbr name of
- the given month.
+ Return the standard English name of the given month.
+
+ This function always returns "January" or "Jan" for January, use
+ GetMonthName() to retrieve the name of the month in the users current
+ locale.
+
+ @param month
+ One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+ @param flags
+ Either Name_Full (default) or Name_Abbr.
+
+ @see GetEnglishWeekDayName()
+
+ @since 2.9.0
+ */
+ static wxString GetEnglishMonthName(Month month,
+ NameFlags flags = Name_Full);
+
+ /**
+ Return the standard English name of the given week day.
+
+ This function always returns "Monday" or "Mon" for Monday, use
+ GetWeekDayName() to retrieve the name of the month in the users current
+ locale.
+
+ @param weekday
+ One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+ @param flags
+ Either Name_Full (default) or Name_Abbr.
+
+ @see GetEnglishMonthName()
+
+ @since 2.9.0
+ */
+ static wxString GetEnglishWeekDayName(WeekDay weekday,
+ NameFlags flags = Name_Full);
+
+ /**
+ Gets the full (default) or abbreviated name of the given month.
+
+ This function returns the name in the current locale, use
+ GetEnglishMonthName() to get the untranslated name if necessary.
+
+ @param month
+ One of wxDateTime::Jan, ..., wxDateTime::Dec values.
+ @param flags
+ Either Name_Full (default) or Name_Abbr.
@see GetWeekDayName()
*/
static time_t GetTimeNow();
/**
- Returns the current time broken down using the buffer whose adress is
+ Returns the current time broken down using the buffer whose address is
passed to the function with @a tm to store the result.
*/
static tm* GetTmNow(struct tm *tm);
static tm* GetTmNow();
/**
- Gets the full (default) or abbreviated (specify @c Name_Abbr) name of
- the given week day.
+ Gets the full (default) or abbreviated name of the given week day.
+
+ This function returns the name in the current locale, use
+ GetEnglishWeekDayName() to get the untranslated name if necessary.
+
+ @param weekday
+ One of wxDateTime::Sun, ..., wxDateTime::Sat values.
+ @param flags
+ Either Name_Full (default) or Name_Abbr.
@see GetMonthName()
*/
static wxString GetWeekDayName(WeekDay weekday,
- NameFlags flags = Name_Full);
+ NameFlags flags = Name_Full);
/**
Returns @true if DST was used in the given year (the current one by
*/
const wxDateTime wxDefaultDateTime;
+/*
+ wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime
/**
projects / wxWidgets.git / blobdiff