used to contain the number of years, hours, minutes, seconds and
milliseconds.
-
- @section datetime_constants Constants
-
- Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
+ Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are
defined. This constant will be different from any valid wxDateTime object.
- All the following constants are defined inside wxDateTime class (i.e., to
- refer to them you should prepend their names with "wxDateTime::").
-
- Time zone symbolic names:
-
- @code
- enum TZ
- {
- // the time in the current time zone
- Local,
-
- // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
- // consequent numbers, so writing something like `GMT0 + offset' is
- // safe if abs(offset) <= 12
-
- // underscore stands for minus
- GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
- GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
- GMT0,
- GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
- GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
- // Note that GMT12 and GMT_12 are not the same: there is a difference
- // of exactly one day between them
-
- // some symbolic names for TZ
-
- // Europe
- WET = GMT0, // Western Europe Time
- WEST = GMT1, // Western Europe Summer Time
- CET = GMT1, // Central Europe Time
- CEST = GMT2, // Central Europe Summer Time
- EET = GMT2, // Eastern Europe Time
- EEST = GMT3, // Eastern Europe Summer Time
- MSK = GMT3, // Moscow Time
- MSD = GMT4, // Moscow Summer Time
-
- // US and Canada
- AST = GMT_4, // Atlantic Standard Time
- ADT = GMT_3, // Atlantic Daylight Time
- EST = GMT_5, // Eastern Standard Time
- EDT = GMT_4, // Eastern Daylight Saving Time
- CST = GMT_6, // Central Standard Time
- CDT = GMT_5, // Central Daylight Saving Time
- MST = GMT_7, // Mountain Standard Time
- MDT = GMT_6, // Mountain Daylight Saving Time
- PST = GMT_8, // Pacific Standard Time
- PDT = GMT_7, // Pacific Daylight Saving Time
- HST = GMT_10, // Hawaiian Standard Time
- AKST = GMT_9, // Alaska Standard Time
- AKDT = GMT_8, // Alaska Daylight Saving Time
-
- // Australia
-
- A_WST = GMT8, // Western Standard Time
- A_CST = GMT13 + 1, // Central Standard Time (+9.5)
- A_EST = GMT10, // Eastern Standard Time
- A_ESST = GMT11, // Eastern Summer Time
-
- // New Zealand
- NZST = GMT12, // Standard Time
- NZDT = GMT13, // Daylight Saving Time
-
- // Universal Coordinated Time = the new and politically correct name
- // for GMT
- UTC = GMT0
- };
- @endcode
-
- Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
- Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
-
- Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
- in @c wxDateTime::WeekDay enum.
-
- Finally, Inv_Year is defined to be an invalid value for year parameter.
-
- GetMonthName() and GetWeekDayName() functions use the following flags:
-
- @code
- enum NameFlags
- {
- Name_Full = 0x01, // return full name
- Name_Abbr = 0x02 // return abbreviated name
- };
- @endcode
-
- Several functions accept an extra parameter specifying the calendar to use
- (although most of them only support now the Gregorian calendar). This
- parameters is one of the following values:
-
- @code
- enum Calendar
- {
- Gregorian, // calendar currently in use in Western countries
- Julian // calendar in use since -45 until the 1582 (or later)
- };
- @endcode
-
- Date calculations often depend on the country and wxDateTime allows to set
- the country whose conventions should be used using SetCountry(). It takes
- one of the following values as parameter:
-
- @code
- enum Country
- {
- Country_Unknown, // no special information for this country
- Country_Default, // set the default country with SetCountry() method
- // or use the default country with any other
-
- Country_WesternEurope_Start,
- Country_EEC = Country_WesternEurope_Start,
- France,
- Germany,
- UK,
- Country_WesternEurope_End = UK,
-
- Russia,
-
- USA
- };
- @endcode
-
- Different parts of the world use different conventions for the week start.
- In some countries, the week starts on Sunday, while in others -- on Monday.
- The ISO standard doesn't address this issue, so we support both conventions
- in the functions whose result depends on it (GetWeekOfYear() and
- GetWeekOfMonth()).
-
- The desired behvaiour may be specified by giving one of the following
- constants as argument to these functions:
-
- @code
- enum WeekFlags
- {
- Default_First, // Sunday_First for US, Monday_First for the rest
- Monday_First, // week starts with a Monday
- Sunday_First // week starts with a Sunday
- };
- @endcode
-
@section datetime_static Static Functions
class wxDateTime
{
public:
+ /**
+ A small unsigned integer type for storing things like minutes,
+ seconds &c. It should be at least short (i.e. not char) to contain
+ the number of milliseconds - it may also be 'int' because there is
+ no size penalty associated with it in our code, we don't store any
+ data in this format.
+ */
+ typedef unsigned short wxDateTime_t;
+
+
+ /**
+ Time zone symbolic names.
+ */
+ enum TZ
+ {
+ /// the time in the current time zone
+ Local,
+
+ //@{
+ /// zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+ /// consequent numbers, so writing something like `GMT0 + offset' is
+ /// safe if abs(offset) <= 12
+
+ // underscore stands for minus
+ GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
+ GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
+ GMT0,
+ GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
+ GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
+ // Note that GMT12 and GMT_12 are not the same: there is a difference
+ // of exactly one day between them
+ //@}
+
+ // some symbolic names for TZ
+
+ // Europe
+ WET = GMT0, //!< Western Europe Time
+ WEST = GMT1, //!< Western Europe Summer Time
+ CET = GMT1, //!< Central Europe Time
+ CEST = GMT2, //!< Central Europe Summer Time
+ EET = GMT2, //!< Eastern Europe Time
+ EEST = GMT3, //!< Eastern Europe Summer Time
+ MSK = GMT3, //!< Moscow Time
+ MSD = GMT4, //!< Moscow Summer Time
+
+ // US and Canada
+ AST = GMT_4, //!< Atlantic Standard Time
+ ADT = GMT_3, //!< Atlantic Daylight Time
+ EST = GMT_5, //!< Eastern Standard Time
+ EDT = GMT_4, //!< Eastern Daylight Saving Time
+ CST = GMT_6, //!< Central Standard Time
+ CDT = GMT_5, //!< Central Daylight Saving Time
+ MST = GMT_7, //!< Mountain Standard Time
+ MDT = GMT_6, //!< Mountain Daylight Saving Time
+ PST = GMT_8, //!< Pacific Standard Time
+ PDT = GMT_7, //!< Pacific Daylight Saving Time
+ HST = GMT_10, //!< Hawaiian Standard Time
+ AKST = GMT_9, //!< Alaska Standard Time
+ AKDT = GMT_8, //!< Alaska Daylight Saving Time
+
+ // Australia
+
+ A_WST = GMT8, //!< Western Standard Time
+ A_CST = GMT13 + 1, //!< Central Standard Time (+9.5)
+ A_EST = GMT10, //!< Eastern Standard Time
+ A_ESST = GMT11, //!< Eastern Summer Time
+
+ // New Zealand
+ NZST = GMT12, //!< Standard Time
+ NZDT = GMT13, //!< Daylight Saving Time
+
+ /// Universal Coordinated Time = the new and politically correct name
+ /// for GMT.
+ UTC = GMT0
+ };
+
+ /**
+ Several functions accept an extra parameter specifying the calendar to use
+ (although most of them only support now the Gregorian calendar). This
+ parameters is one of the following values.
+ */
+ enum Calendar
+ {
+ Gregorian, ///< calendar currently in use in Western countries
+ Julian ///< calendar in use since -45 until the 1582 (or later)
+ };
+
+ /**
+ Date calculations often depend on the country and wxDateTime allows to set
+ the country whose conventions should be used using SetCountry(). It takes
+ one of the following values as parameter.
+ */
+ enum Country
+ {
+ Country_Unknown, ///< no special information for this country
+ Country_Default, ///< set the default country with SetCountry() method
+ ///< or use the default country with any other
+
+ Country_WesternEurope_Start,
+ Country_EEC = Country_WesternEurope_Start,
+ France,
+ Germany,
+ UK,
+ Country_WesternEurope_End = UK,
+
+ Russia,
+
+ USA
+ };
+
+ /// symbolic names for the months
+ enum Month
+ {
+ Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec,
+
+ /// Invalid month value.
+ Inv_Month
+ };
+
+ /// symbolic names for the weekdays
+ enum WeekDay
+ {
+ Sun, Mon, Tue, Wed, Thu, Fri, Sat,
+
+ /// Invalid week day value.
+ Inv_WeekDay
+ };
+
+ /// invalid value for the year
+ enum Year
+ {
+ Inv_Year = SHRT_MIN // should hold in wxDateTime_t
+ };
+
+ /**
+ Flags to be used with GetMonthName() and GetWeekDayName() functions.
+ */
+ enum NameFlags
+ {
+ Name_Full = 0x01, ///< return full name
+ Name_Abbr = 0x02 ///< return abbreviated name
+ };
+
+ /**
+ Different parts of the world use different conventions for the week start.
+ In some countries, the week starts on Sunday, while in others -- on Monday.
+ The ISO standard doesn't address this issue, so we support both conventions
+ in the functions whose result depends on it (GetWeekOfYear() and
+ GetWeekOfMonth()).
+
+ The desired behvaiour may be specified by giving one of the following
+ constants as argument to these functions.
+ */
+ enum WeekFlags
+ {
+ Default_First, ///< Sunday_First for US, Monday_First for the rest
+ Monday_First, ///< week starts with a Monday
+ Sunday_First ///< week starts with a Sunday
+ };
+
+
/**
@name Constructors, Assignment Operators and Setters
Returns the ordinal number of the week in the month (in 1-5 range).
As GetWeekOfYear(), this function supports both conventions for the
- week start. See the description of these @c WeekFlags in the
- @ref datetime_constants section.
+ week start.
*/
wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
const TimeZone& tz = Local) const;
year. Accordingly, the week number will always be in 1-53 range (52 for
non-leap years).
- The function depends on the @ref datetime_constants "week start"
- convention specified by the @a flags argument but its results for
- @c Sunday_First are not well-defined as the ISO definition quoted above
- applies to the weeks starting on Monday only.
+ The function depends on the week start convention specified by the @a flags
+ argument but its results for @c Sunday_First are not well-defined as the
+ ISO definition quoted above applies to the weeks starting on Monday only.
*/
wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
const TimeZone& tz = Local) const;
/**
This function does the same as the standard ANSI C @c strftime(3)
- function. Please see its description for the meaning of @a format
- parameter.
+ function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html).
+ Please see its description for the meaning of @a format parameter.
It also accepts a few wxWidgets-specific extensions: you can optionally
specify the width of the field to follow using @c printf(3)-like syntax
@return @NULL if the conversion failed, otherwise return the pointer
to the character which stopped the scan.
+
+ @see Format()
*/
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.
+ /**
+ @overload
*/
const char* ParseDate(const char* date);
- /**
- This function is like ParseDateTime(), but it only allows the date to
- be specified. It is thus less flexible then ParseDateTime(), but also
- has less chances to misinterpret the user input.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ /**
+ @overload
*/
const wchar_t* ParseDate(const wchar_t* date);
*/
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.
+ /**
+ @overload
*/
const char* ParseDateTime(const char* datetime);
- /**
- Parses the string @a datetime containing the date and time in free
- format. This function tries as hard as it can to interpret the given
- string as date and time. Unlike ParseRfc822Date(), it will accept
- anything that may be accepted and will only reject strings which can
- not be parsed in any way at all.
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ /**
+ @overload
*/
const wchar_t* ParseDateTime(const wchar_t* datetime);
@return @NULL if the conversion failed, otherwise return the pointer
to the character which stopped the scan.
+
+ @see Format()
*/
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.
+ const wxString& format = wxDefaultDateTimeFormat,
+ const wxDateTime& dateDef = wxDefaultDateTime,
+ wxString::const_iterator* end = NULL);
- 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.
+ /**
+ @overload
*/
const char* ParseFormat(const char* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
- /**
- This function parses the string @a date according to the given
- @e format. The system @c strptime(3) function is used whenever
- available, but even if it is not, this function is still implemented,
- although support for locale-dependent format specifiers such as
- @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
- as @c "%z" and @c "%Z" are not implemented. This function does handle
- the month and weekday names in the current locale on all platforms,
- however.
-
- Please see the description of the ANSI C function @c strftime(3) for
- the syntax of the format string.
-
- 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.
+ const wxString& format = wxDefaultDateTimeFormat,
+ const wxDateTime& dateDef = wxDefaultDateTime);
- @return @NULL if the conversion failed, otherwise return the pointer
- to the character which stopped the scan.
+ /**
+ @overload
*/
const wchar_t* ParseFormat(const wchar_t* date,
- const wxString& format = wxDefaultDateTimeFormat,
- const wxDateTime& dateDef = wxDefaultDateTime);
+ const wxString& format = wxDefaultDateTimeFormat,
+ const wxDateTime& dateDef = wxDefaultDateTime);
/**
This function parses the string containing the date and time in ISO
*/
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.
+ /**
+ @overload
*/
const char* ParseRfc822Date(const char* date);
- /**
- Parses the string @a date looking for a date formatted according to the
- RFC 822 in it. The exact description of this format may, of course, be
- found in the RFC (section 5), but, briefly, this is the format used in
- the headers of Internet email messages and one of the most common
- strings expressing date in this format may be something like
- @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
- Returns @NULL if the conversion failed, otherwise return the pointer to
- the character immediately following the part of the string which could
- be parsed. If the entire string contains only the date in RFC 822
- format, the returned pointer will be pointing to a @c NUL character.
- This function is intentionally strict, it will return an error for any
- string which is not RFC 822 compliant. If you need to parse date
- formatted in more free ways, you should use ParseDateTime() or
- ParseDate() instead.
+ /**
+ @overload
*/
const wchar_t* ParseRfc822Date(const wchar_t* date);
*/
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.
+ /**
+ @overload
*/
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.
+ /**
+ @overload
*/
const wchar_t* ParseTime(const wchar_t* time);
Sets the country to use by default. This setting influences the DST
calculations, date formatting and other things.
- The possible values for @a country parameter are enumerated in the
- @ref datetime_constants section.
-
@see GetCountry()
*/
static void SetCountry(Country country);
projects / wxWidgets.git / blobdiff