interface/wx/datetime.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        datetime.h
   3 // Purpose:     interface of wxDateTime
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDateTime
  11
  12     wxDateTime class represents an absolute moment in the time.
  13
  14     The type @c wxDateTime_t is typedefed as <tt>unsigned short</tt> and is
  15     used to contain the number of years, hours, minutes, seconds and
  16     milliseconds.
  17
  18     Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are
  19     defined. This constant will be different from any valid wxDateTime object.
  20
  21
  22     @section datetime_static Static Functions
  23
  24     All static functions either set or return the static variables of
  25     wxDateSpan (the country), return the current moment, year, month or number
  26     of days in it, or do some general calendar-related actions.
  27
  28     Please note that although several function accept an extra Calendar
  29     parameter, it is currently ignored as only the Gregorian calendar is
  30     supported. Future versions will support other calendars.
  31
  32     @beginWxPythonOnly
  33     These methods are standalone functions named
  34     "wxDateTime_<StaticMethodName>" in wxPython.
  35     @endWxPythonOnly
  36
  37
  38     @section datetime_formatting Date Formatting and Parsing
  39
  40     The date formatting and parsing functions convert wxDateTime objects to and
  41     from text. The conversions to text are mostly trivial: you can either do it
  42     using the default date and time representations for the current locale
  43     (FormatDate() and FormatTime()), using the international standard
  44     representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and
  45     FormatISOCombined()) or by specifying any format at all and using Format()
  46     directly.
  47
  48     The conversions from text are more interesting, as there are much more
  49     possibilities to care about. The simplest cases can be taken care of with
  50     ParseFormat() which can parse any date in the given (rigid) format.
  51     ParseRfc822Date() is another function for parsing dates in predefined
  52     format -- the one of RFC 822 which (still...) defines the format of email
  53     messages on the Internet. This format cannot be described with
  54     @c strptime(3)-like format strings used by Format(), hence the need for a
  55     separate function.
  56
  57     But the most interesting functions are ParseTime(), ParseDate() and
  58     ParseDateTime(). They try to parse the date and time (or only one of them)
  59     in 'free' format, i.e. allow them to be specified in any of possible ways.
  60     These functions will usually be used to parse the (interactive) user input
  61     which is not bound to be in any predefined format. As an example,
  62     ParseDate() can parse the strings such as "tomorrow", "March first" and
  63     even "next Sunday".
  64
  65     Finally notice that each of the parsing functions is available in several
  66     overloads: if the input string is a narrow (@c char *) string, then a
  67     narrow pointer is returned. If the input string is a wide string, a wide
  68     char pointer is returned. Finally, if the input parameter is a wxString, a
  69     narrow char pointer is also returned for backwards compatibility but there
  70     is also an additional argument of wxString::const_iterator type in which,
  71     if it is not @NULL, an iterator pointing to the end of the scanned string
  72     part is returned.
  73
  74
  75     @library{wxbase}
  76     @category{data}
  77
  78     @stdobjects
  79     - ::wxDefaultDateTime
  80
  81     @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl
  82 */
  83 class wxDateTime
  84 {
  85 public:
  86     /**
  87         A small unsigned integer type for storing things like minutes,
  88         seconds &c. It should be at least short (i.e. not char) to contain
  89         the number of milliseconds - it may also be 'int' because there is
  90         no size penalty associated with it in our code, we don't store any
  91         data in this format.
  92     */
  93     typedef unsigned short wxDateTime_t;
  94
  95
  96     /**
  97         Time zone symbolic names.
  98     */
  99     enum TZ
 100     {
 101         /// the time in the current time zone
 102         Local,
 103
 104         //@{
 105         /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be
 106         /// consequent numbers, so writing something like `GMT0 + offset' is
 107         /// safe if abs(offset) <= 12
 108
 109         // underscore stands for minus
 110         GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
 111         GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
 112         GMT0,
 113         GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
 114         GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
 115         // Note that GMT12 and GMT_12 are not the same: there is a difference
 116         // of exactly one day between them
 117         //@}
 118
 119         // some symbolic names for TZ
 120
 121         // Europe
 122         WET = GMT0,         //!< Western Europe Time
 123         WEST = GMT1,        //!< Western Europe Summer Time
 124         CET = GMT1,         //!< Central Europe Time
 125         CEST = GMT2,        //!< Central Europe Summer Time
 126         EET = GMT2,         //!< Eastern Europe Time
 127         EEST = GMT3,        //!< Eastern Europe Summer Time
 128         MSK = GMT3,         //!< Moscow Time
 129         MSD = GMT4,         //!< Moscow Summer Time
 130
 131         // US and Canada
 132         AST = GMT_4,        //!< Atlantic Standard Time
 133         ADT = GMT_3,        //!< Atlantic Daylight Time
 134         EST = GMT_5,        //!< Eastern Standard Time
 135         EDT = GMT_4,        //!< Eastern Daylight Saving Time
 136         CST = GMT_6,        //!< Central Standard Time
 137         CDT = GMT_5,        //!< Central Daylight Saving Time
 138         MST = GMT_7,        //!< Mountain Standard Time
 139         MDT = GMT_6,        //!< Mountain Daylight Saving Time
 140         PST = GMT_8,        //!< Pacific Standard Time
 141         PDT = GMT_7,        //!< Pacific Daylight Saving Time
 142         HST = GMT_10,       //!< Hawaiian Standard Time
 143         AKST = GMT_9,       //!< Alaska Standard Time
 144         AKDT = GMT_8,       //!< Alaska Daylight Saving Time
 145
 146         // Australia
 147
 148         A_WST = GMT8,       //!< Western Standard Time
 149         A_CST = GMT13 + 1,  //!< Central Standard Time (+9.5)
 150         A_EST = GMT10,      //!< Eastern Standard Time
 151         A_ESST = GMT11,     //!< Eastern Summer Time
 152
 153         // New Zealand
 154         NZST = GMT12,       //!< Standard Time
 155         NZDT = GMT13,       //!< Daylight Saving Time
 156
 157         /// Universal Coordinated Time = the new and politically correct name
 158         /// for GMT.
 159         UTC = GMT0
 160     };
 161
 162     /**
 163         Several functions accept an extra parameter specifying the calendar to use
 164         (although most of them only support now the Gregorian calendar). This
 165         parameters is one of the following values.
 166     */
 167     enum Calendar
 168     {
 169         Gregorian,  ///< calendar currently in use in Western countries
 170         Julian      ///< calendar in use since -45 until the 1582 (or later)
 171     };
 172
 173     /**
 174         Values corresponding to different dates of adoption of the Gregorian
 175         calendar.
 176
 177         @see IsGregorianDate
 178      */
 179     enum GregorianAdoption
 180     {
 181         Gr_Unknown,    ///< no data for this country or it's too uncertain to use
 182         Gr_Standard,   ///< on the day 0 of Gregorian calendar: 15 Oct 1582
 183
 184         Gr_Alaska,             ///< Oct 1867 when Alaska became part of the USA
 185         Gr_Albania,            ///< Dec 1912
 186
 187         Gr_Austria = Gr_Unknown,    ///< Different regions on different dates
 188         Gr_Austria_Brixen,          ///< 5 Oct 1583 -> 16 Oct 1583
 189         Gr_Austria_Salzburg = Gr_Austria_Brixen,
 190         Gr_Austria_Tyrol = Gr_Austria_Brixen,
 191         Gr_Austria_Carinthia,       ///< 14 Dec 1583 -> 25 Dec 1583
 192         Gr_Austria_Styria = Gr_Austria_Carinthia,
 193
 194         Gr_Belgium,            ///< Then part of the Netherlands
 195
 196         Gr_Bulgaria = Gr_Unknown, ///< Unknown precisely (from 1915 to 1920)
 197         Gr_Bulgaria_1,         ///<      18 Mar 1916 -> 1 Apr 1916
 198         Gr_Bulgaria_2,         ///<      31 Mar 1916 -> 14 Apr 1916
 199         Gr_Bulgaria_3,         ///<      3 Sep 1920 -> 17 Sep 1920
 200
 201         Gr_Canada = Gr_Unknown,   ///< Different regions followed the changes in
 202                                ///< Great Britain or France
 203
 204         Gr_China = Gr_Unknown,    ///< Different authorities say:
 205         Gr_China_1,            ///<      18 Dec 1911 -> 1 Jan 1912
 206         Gr_China_2,            ///<      18 Dec 1928 -> 1 Jan 1929
 207
 208         Gr_Czechoslovakia,     ///< (Bohemia and Moravia) 6 Jan 1584 -> 17 Jan 1584
 209         Gr_Denmark,            ///< (including Norway) 18 Feb 1700 -> 1 Mar 1700
 210         Gr_Egypt,              ///< 1875
 211         Gr_Estonia,            ///< 1918
 212         Gr_Finland,            ///< Then part of Sweden
 213
 214         Gr_France,             ///< 9 Dec 1582 -> 20 Dec 1582
 215         Gr_France_Alsace,      ///<      4 Feb 1682 -> 16 Feb 1682
 216         Gr_France_Lorraine,    ///<      16 Feb 1760 -> 28 Feb 1760
 217         Gr_France_Strasbourg,  ///< February 1682
 218
 219         Gr_Germany = Gr_Unknown,  ///< Different states on different dates:
 220         Gr_Germany_Catholic,   ///<      1583-1585 (we take 1584)
 221         Gr_Germany_Prussia,    ///<      22 Aug 1610 -> 2 Sep 1610
 222         Gr_Germany_Protestant, ///<      18 Feb 1700 -> 1 Mar 1700
 223
 224         Gr_GreatBritain,       ///< 2 Sep 1752 -> 14 Sep 1752 (use 'cal(1)')
 225
 226         Gr_Greece,             ///< 9 Mar 1924 -> 23 Mar 1924
 227         Gr_Hungary,            ///< 21 Oct 1587 -> 1 Nov 1587
 228         Gr_Ireland = Gr_GreatBritain,
 229         Gr_Italy = Gr_Standard,
 230
 231         Gr_Japan = Gr_Unknown,    ///< Different authorities say:
 232         Gr_Japan_1,            ///<      19 Dec 1872 -> 1 Jan 1873
 233         Gr_Japan_2,            ///<      19 Dec 1892 -> 1 Jan 1893
 234         Gr_Japan_3,            ///<      18 Dec 1918 -> 1 Jan 1919
 235
 236         Gr_Latvia,             ///< 1915-1918 (we take 1915)
 237         Gr_Lithuania,          ///< 1915
 238         Gr_Luxemburg,          ///< 14 Dec 1582 -> 25 Dec 1582
 239         Gr_Netherlands = Gr_Belgium, ///< (including Belgium) 1 Jan 1583
 240
 241         /**
 242             Special case of Groningen.
 243
 244             The Gregorian calendar was introduced twice in Groningen, first
 245             time 28 Feb 1583 was followed by 11 Mar 1583, then it has gone back
 246             to Julian in the summer of 1584 and then 13 Dec 1700 was followed
 247             by 12 Jan 1701 -- which is the date we take into account here.
 248          */
 249         Gr_Netherlands_Groningen,  ///< 13 Dec 1700 -> 12 Jan 1701
 250         Gr_Netherlands_Gelderland, ///< 30 Jun 1700 -> 12 Jul 1700
 251         Gr_Netherlands_Utrecht,    ///< (and Overijssel) 30 Nov 1700->12 Dec 1700
 252         Gr_Netherlands_Friesland,  ///< (and Drenthe) 31 Dec 1700 -> 12 Jan 1701
 253
 254         Gr_Norway = Gr_Denmark,       ///< Then part of Denmark
 255         Gr_Poland = Gr_Standard,
 256         Gr_Portugal = Gr_Standard,
 257         Gr_Romania,                ///< 31 Mar 1919 -> 14 Apr 1919
 258         Gr_Russia,                 ///< 31 Jan 1918 -> 14 Feb 1918
 259         Gr_Scotland = Gr_GreatBritain,
 260         Gr_Spain = Gr_Standard,
 261
 262         /**
 263             Special case of Sweden.
 264
 265             Sweden has a curious history. Sweden decided to make a gradual
 266             change from the Julian to the Gregorian calendar. By dropping every
 267             leap year from 1700 through 1740 the eleven superfluous days would
 268             be omitted and from 1 Mar 1740 they would be in sync with the
 269             Gregorian calendar. (But in the meantime they would be in sync with
 270             nobody!)
 271
 272             So 1700 (which should have been a leap year in the Julian calendar)
 273             was not a leap year in Sweden. However, by mistake 1704 and 1708
 274             became leap years. This left Sweden out of synchronisation with
 275             both the Julian and the Gregorian world, so they decided to go back
 276             to the Julian calendar. In order to do this, they inserted an extra
 277             day in 1712, making that year a double leap year! So in 1712,
 278             February had 30 days in Sweden.
 279
 280             Later, in 1753, Sweden changed to the Gregorian calendar by
 281             dropping 11 days like everyone else and this is what we use here.
 282          */
 283         Gr_Sweden = Gr_Finland,       ///< 17 Feb 1753 -> 1 Mar 1753
 284
 285         Gr_Switzerland = Gr_Unknown,///< Different cantons used different dates
 286         Gr_Switzerland_Catholic,    ///<      1583, 1584 or 1597 (we take 1584)
 287         Gr_Switzerland_Protestant,  ///<      31 Dec 1700 -> 12 Jan 1701
 288
 289         Gr_Turkey,                 ///< 1 Jan 1927
 290         Gr_USA = Gr_GreatBritain,
 291         Gr_Wales = Gr_GreatBritain,
 292         Gr_Yugoslavia              ///< 1919
 293     };
 294
 295     /**
 296         Date calculations often depend on the country and wxDateTime allows to set
 297         the country whose conventions should be used using SetCountry(). It takes
 298         one of the following values as parameter.
 299     */
 300     enum Country
 301     {
 302         Country_Unknown, ///< no special information for this country
 303         Country_Default, ///< set the default country with SetCountry() method
 304                          ///< or use the default country with any other
 305
 306         Country_WesternEurope_Start,
 307         Country_EEC = Country_WesternEurope_Start,
 308         France,
 309         Germany,
 310         UK,
 311         Country_WesternEurope_End = UK,
 312
 313         Russia,
 314
 315         USA
 316     };
 317
 318     /// symbolic names for the months
 319     enum Month
 320     {
 321         Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec,
 322
 323         /// Invalid month value.
 324         Inv_Month
 325     };
 326
 327     /// symbolic names for the weekdays
 328     enum WeekDay
 329     {
 330         Sun, Mon, Tue, Wed, Thu, Fri, Sat,
 331
 332         /// Invalid week day value.
 333         Inv_WeekDay
 334     };
 335
 336     /// invalid value for the year
 337     enum Year
 338     {
 339         Inv_Year = SHRT_MIN    // should hold in wxDateTime_t
 340     };
 341
 342     /**
 343         Flags to be used with GetMonthName() and GetWeekDayName() functions.
 344     */
 345     enum NameFlags
 346     {
 347         Name_Full = 0x01,       ///< return full name
 348         Name_Abbr = 0x02        ///< return abbreviated name
 349     };
 350
 351     /**
 352         Different parts of the world use different conventions for the week start.
 353         In some countries, the week starts on Sunday, while in others -- on Monday.
 354         The ISO standard doesn't address this issue, so we support both conventions
 355         in the functions whose result depends on it (GetWeekOfYear() and
 356         GetWeekOfMonth()).
 357
 358         The desired behaviour may be specified by giving one of the following
 359         constants as argument to these functions.
 360     */
 361     enum WeekFlags
 362     {
 363         Default_First,   ///< Sunday_First for US, Monday_First for the rest
 364         Monday_First,    ///< week starts with a Monday
 365         Sunday_First     ///< week starts with a Sunday
 366     };
 367
 368
 369     /**
 370         Class representing a time zone.
 371
 372         The representation is simply the offset, in seconds, from UTC.
 373      */
 374     class WXDLLIMPEXP_BASE TimeZone
 375     {
 376     public:
 377         /// Constructor for a named time zone.
 378         TimeZone(TZ tz);
 379
 380         /// Constructor for the given offset in seconds.
 381         TimeZone(long offset = 0);
 382
 383         /// Create a time zone with the given offset in seconds.
 384         static TimeZone Make(long offset);
 385
 386         /// Return the offset of this time zone from UTC, in seconds.
 387         long GetOffset() const;
 388     };
 389
 390     /**
 391         Contains broken down date-time representation.
 392
 393         This struct is analogous to standard C <code>struct tm</code> and uses
 394         the same, not always immediately obvious, conventions for its members:
 395         notably its mon and mday fields count from 0 while yday counts from 1.
 396      */
 397     struct Tm
 398     {
 399         wxDateTime_t msec,  ///< Number of milliseconds.
 400                      sec,   ///< Seconds in 0..59 (60 with leap seconds) range.
 401                      min,   ///< Minutes in 0..59 range.
 402                      hour,  ///< Hours since midnight in 0..23 range.
 403                      mday,  ///< Day of the month in 1..31 range.
 404                      yday;  ///< Day of the year in 0..365 range.
 405         Month mon;          ///< Month, as an enumerated constant.
 406         int year;           ///< Year.
 407
 408         /**
 409             Check if the given date/time is valid (in Gregorian calendar).
 410
 411             Return @false if the components don't correspond to a correct date.
 412          */
 413         bool IsValid() const;
 414
 415         /**
 416             Return the week day corresponding to this date.
 417
 418             Unlike the other fields, the week day is not always available and
 419             so must be accessed using this method as it is computed on demand
 420             when it is called.
 421          */
 422         WeekDay GetWeekDay();
 423     };
 424
 425
 426     /**
 427         @name Constructors, Assignment Operators and Setters
 428
 429         Constructors and various Set() methods are collected here. If you
 430         construct a date object from separate values for day, month and year,
 431         you should use IsValid() method to check that the values were correct
 432         as constructors cannot return an error code.
 433     */
 434     //@{
 435
 436     /**
 437         Default constructor. Use one of the Set() functions to initialize the
 438         object later.
 439     */
 440     wxDateTime();
 441     /**
 442         Same as Set().
 443
 444         @beginWxPythonOnly
 445         This constructor is named "wxDateTimeFromTimeT" in wxPython.
 446         @endWxPythonOnly
 447     */
 448     wxDateTime(time_t timet);
 449     /**
 450         Same as Set().
 451
 452         @beginWxPythonOnly Unsupported. @endWxPythonOnly
 453     */
 454     wxDateTime(const struct tm& tm);
 455     /**
 456         Same as Set().
 457
 458         @beginWxPythonOnly
 459         This constructor is named "wxDateTimeFromJDN" in wxPython.
 460         @endWxPythonOnly
 461     */
 462     wxDateTime(double jdn);
 463     /**
 464         Same as Set().
 465
 466         @beginWxPythonOnly
 467         This constructor is named "wxDateTimeFromHMS" in wxPython.
 468         @endWxPythonOnly
 469     */
 470     wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0,
 471                wxDateTime_t second = 0, wxDateTime_t millisec = 0);
 472     /**
 473         Same as Set().
 474
 475         @beginWxPythonOnly
 476         This constructor is named "wxDateTimeFromDMY" in wxPython.
 477         @endWxPythonOnly
 478     */
 479     wxDateTime(wxDateTime_t day, Month month = Inv_Month,
 480                int year = Inv_Year, wxDateTime_t hour = 0,
 481                wxDateTime_t minute = 0, wxDateTime_t second = 0,
 482                wxDateTime_t millisec = 0);
 483
 484     /**
 485         Same as SetFromMSWSysTime.
 486
 487         @param st
 488             Input, Windows SYSTEMTIME reference
 489         @since 2.9.0
 490         @remarks MSW only
 491     */
 492     wxDateTime(const struct _SYSTEMTIME& st);
 493
 494
 495     /**
 496         Reset time to midnight (00:00:00) without changing the date.
 497     */
 498     wxDateTime& ResetTime();
 499
 500     /**
 501         Constructs the object from @a timet value holding the number of seconds
 502         since Jan 1, 1970.
 503
 504         @beginWxPythonOnly
 505         This method is named "SetTimeT" in wxPython.
 506         @endWxPythonOnly
 507     */
 508     wxDateTime& Set(time_t timet);
 509     /**
 510         Sets the date and time from the broken down representation in the
 511         standard @a tm structure.
 512
 513         @beginWxPythonOnly Unsupported. @endWxPythonOnly
 514     */
 515     wxDateTime& Set(const struct tm& tm);
 516     /**
 517         Sets the date from the so-called Julian Day Number.
 518
 519         By definition, the Julian Day Number, usually abbreviated as JDN, of a
 520         particular instant is the fractional number of days since 12 hours
 521         Universal Coordinated Time (Greenwich mean noon) on January 1 of the
 522         year -4712 in the Julian proleptic calendar.
 523
 524         @beginWxPythonOnly
 525         This method is named "SetJDN" in wxPython.
 526         @endWxPythonOnly
 527     */
 528     wxDateTime& Set(double jdn);
 529     /**
 530         Sets the date to be equal to Today() and the time from supplied
 531         parameters.
 532
 533         @beginWxPythonOnly
 534         This method is named "SetHMS" in wxPython.
 535         @endWxPythonOnly
 536     */
 537     wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0,
 538                     wxDateTime_t second = 0, wxDateTime_t millisec = 0);
 539     /**
 540         Sets the date and time from the parameters.
 541     */
 542     wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month,
 543                     int year = Inv_Year, wxDateTime_t hour = 0,
 544                     wxDateTime_t minute = 0, wxDateTime_t second = 0,
 545                     wxDateTime_t millisec = 0);
 546
 547     /**
 548         Sets the day without changing other date components.
 549     */
 550     wxDateTime& SetDay(unsigned short day);
 551
 552     /**
 553         Sets the date from the date and time in DOS format.
 554     */
 555     wxDateTime& SetFromDOS(unsigned long ddt);
 556
 557     /**
 558         Sets the hour without changing other date components.
 559     */
 560     wxDateTime& SetHour(unsigned short hour);
 561
 562     /**
 563         Sets the millisecond without changing other date components.
 564     */
 565     wxDateTime& SetMillisecond(unsigned short millisecond);
 566
 567     /**
 568         Sets the minute without changing other date components.
 569     */
 570     wxDateTime& SetMinute(unsigned short minute);
 571
 572     /**
 573         Sets the month without changing other date components.
 574     */
 575     wxDateTime& SetMonth(Month month);
 576
 577     /**
 578         Sets the second without changing other date components.
 579     */
 580     wxDateTime& SetSecond(unsigned short second);
 581
 582     /**
 583         Sets the date and time of to the current values. Same as assigning the
 584         result of Now() to this object.
 585     */
 586     wxDateTime& SetToCurrent();
 587
 588     /**
 589         Sets the year without changing other date components.
 590     */
 591     wxDateTime& SetYear(int year);
 592
 593     /**
 594         Same as Set().
 595     */
 596     wxDateTime& operator=(time_t timet);
 597     /**
 598         Same as Set().
 599     */
 600     wxDateTime& operator=(const struct tm& tm);
 601
 602     //@}
 603
 604
 605
 606     /**
 607         @name Accessors
 608
 609         Here are the trivial accessors. Other functions, which might have to
 610         perform some more complicated calculations to find the answer are under
 611         the "Date Arithmetics" section.
 612     */
 613     //@{
 614
 615     /**
 616         Returns the date and time in DOS format.
 617     */
 618     long unsigned int GetAsDOS() const;
 619
 620     /**
 621         Initialize using the Windows SYSTEMTIME structure.
 622         @param st
 623             Input, Windows SYSTEMTIME reference
 624         @since 2.9.0
 625         @remarks MSW only
 626     */
 627     wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st);
 628
 629     /**
 630         Returns the date and time in the Windows SYSTEMTIME format.
 631         @param st
 632             Output, pointer to Windows SYSTEMTIME
 633         @since 2.9.0
 634         @remarks MSW only
 635     */
 636     void GetAsMSWSysTime(struct _SYSTEMTIME* st) const;
 637
 638     /**
 639         Returns the century of this date.
 640     */
 641     int GetCentury(const TimeZone& tz = Local) const;
 642
 643     /**
 644         Returns the object having the same date component as this one but time
 645         of 00:00:00.
 646
 647         @since 2.8.2
 648
 649         @see ResetTime()
 650     */
 651     wxDateTime GetDateOnly() const;
 652
 653     /**
 654         Returns the day in the given timezone (local one by default).
 655     */
 656     short unsigned int GetDay(const TimeZone& tz = Local) const;
 657
 658     /**
 659         Returns the day of the year (in 1-366 range) in the given timezone
 660         (local one by default).
 661     */
 662     short unsigned int GetDayOfYear(const TimeZone& tz = Local) const;
 663
 664     /**
 665         Returns the hour in the given timezone (local one by default).
 666     */
 667     short unsigned int GetHour(const TimeZone& tz = Local) const;
 668
 669     /**
 670         Returns the milliseconds in the given timezone (local one by default).
 671     */
 672     short unsigned int GetMillisecond(const TimeZone& tz = Local) const;
 673
 674     /**
 675         Returns the minute in the given timezone (local one by default).
 676     */
 677     short unsigned int GetMinute(const TimeZone& tz = Local) const;
 678
 679     /**
 680         Returns the month in the given timezone (local one by default).
 681     */
 682     Month GetMonth(const TimeZone& tz = Local) const;
 683
 684     /**
 685         Returns the seconds in the given timezone (local one by default).
 686     */
 687     short unsigned int GetSecond(const TimeZone& tz = Local) const;
 688
 689     /**
 690         Returns the number of seconds since Jan 1, 1970. An assert failure will
 691         occur if the date is not in the range covered by @c time_t type.
 692     */
 693     time_t GetTicks() const;
 694
 695     /**
 696         Returns broken down representation of the date and time.
 697     */
 698     Tm GetTm(const TimeZone& tz = Local) const;
 699
 700     /**
 701         Returns the week day in the given timezone (local one by default).
 702     */
 703     WeekDay GetWeekDay(const TimeZone& tz = Local) const;
 704
 705     /**
 706         Returns the ordinal number of the week in the month (in 1-5 range).
 707
 708         As GetWeekOfYear(), this function supports both conventions for the
 709         week start.
 710     */
 711     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
 712                                 const TimeZone& tz = Local) const;
 713
 714     /**
 715         Returns the number of the week of the year this date is in. The first
 716         week of the year is, according to international standards, the one
 717         containing Jan 4 or, equivalently, the first week which has Thursday in
 718         this year. Both of these definitions are the same as saying that the
 719         first week of the year must contain more than half of its days in this
 720         year. Accordingly, the week number will always be in 1-53 range (52 for
 721         non-leap years).
 722
 723         The function depends on the week start convention specified by the @a flags
 724         argument but its results for @c Sunday_First are not well-defined as the
 725         ISO definition quoted above applies to the weeks starting on Monday only.
 726     */
 727     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
 728                                const TimeZone& tz = Local) const;
 729
 730     /**
 731         Returns the year in the given timezone (local one by default).
 732     */
 733     int GetYear(const TimeZone& tz = Local) const;
 734
 735     /**
 736         Returns @true if the given date is later than the date of adoption of
 737         the Gregorian calendar in the given country (and hence the Gregorian
 738         calendar calculations make sense for it).
 739     */
 740     bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const;
 741
 742     /**
 743         Returns @true if the object represents a valid time moment.
 744     */
 745     bool IsValid() const;
 746
 747     /**
 748         Returns @true is this day is not a holiday in the given country.
 749     */
 750     bool IsWorkDay(Country country = Country_Default) const;
 751
 752     //@}
 753
 754
 755
 756     /**
 757         @name Date Comparison
 758
 759         There are several functions to allow date comparison. To supplement
 760         them, a few global operators, etc taking wxDateTime are defined.
 761     */
 762     //@{
 763
 764     /**
 765         Returns @true if this date precedes the given one.
 766     */
 767     bool IsEarlierThan(const wxDateTime& datetime) const;
 768
 769     /**
 770         Returns @true if the two dates are strictly identical.
 771     */
 772     bool IsEqualTo(const wxDateTime& datetime) const;
 773
 774     /**
 775         Returns @true if the date is equal to another one up to the given time
 776         interval, i.e. if the absolute difference between the two dates is less
 777         than this interval.
 778     */
 779     bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
 780
 781     /**
 782         Returns @true if this date is later than the given one.
 783     */
 784     bool IsLaterThan(const wxDateTime& datetime) const;
 785
 786     /**
 787         Returns @true if the date is the same without comparing the time parts.
 788     */
 789     bool IsSameDate(const wxDateTime& dt) const;
 790
 791     /**
 792         Returns @true if the time is the same (although dates may differ).
 793     */
 794     bool IsSameTime(const wxDateTime& dt) const;
 795
 796     /**
 797         Returns @true if this date lies strictly between the two given dates.
 798
 799         @see IsBetween()
 800     */
 801     bool IsStrictlyBetween(const wxDateTime& t1,
 802                             const wxDateTime& t2) const;
 803
 804     /**
 805         Returns @true if IsStrictlyBetween() is @true or if the date is equal
 806         to one of the limit values.
 807
 808         @see IsStrictlyBetween()
 809     */
 810     bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const;
 811
 812     //@}
 813
 814
 815
 816     /**
 817         @name Date Arithmetics
 818
 819         These functions carry out
 820         @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime
 821         objects. As explained in the overview, either wxTimeSpan or wxDateSpan
 822         may be added to wxDateTime, hence all functions are overloaded to
 823         accept both arguments.
 824
 825         Also, both Add() and Subtract() have both const and non-const version.
 826         The first one returns a new object which represents the sum/difference
 827         of the original one with the argument while the second form modifies
 828         the object to which it is applied. The operators "-=" and "+=" are
 829         defined to be equivalent to the second forms of these functions.
 830     */
 831     //@{
 832
 833     /**
 834         Adds the given date span to this object.
 835
 836         @beginWxPythonOnly
 837         This method is named "AddDS" in wxPython.
 838         @endWxPythonOnly
 839     */
 840     wxDateTime Add(const wxDateSpan& diff) const;
 841     /**
 842         Adds the given date span to this object.
 843
 844         @beginWxPythonOnly
 845         This method is named "AddDS" in wxPython.
 846         @endWxPythonOnly
 847     */
 848     wxDateTime Add(const wxDateSpan& diff);
 849     /**
 850         Adds the given time span to this object.
 851
 852         @beginWxPythonOnly
 853         This method is named "AddTS" in wxPython.
 854         @endWxPythonOnly
 855     */
 856     wxDateTime Add(const wxTimeSpan& diff) const;
 857     /**
 858         Adds the given time span to this object.
 859
 860         @beginWxPythonOnly
 861         This method is named "AddTS" in wxPython.
 862         @endWxPythonOnly
 863     */
 864     wxDateTime& Add(const wxTimeSpan& diff);
 865
 866     /**
 867         Subtracts the given time span from this object.
 868
 869         @beginWxPythonOnly
 870         This method is named "SubtractTS" in wxPython.
 871         @endWxPythonOnly
 872     */
 873     wxDateTime Subtract(const wxTimeSpan& diff) const;
 874     /**
 875         Subtracts the given time span from this object.
 876
 877         @beginWxPythonOnly
 878         This method is named "SubtractTS" in wxPython.
 879         @endWxPythonOnly
 880     */
 881     wxDateTime& Subtract(const wxTimeSpan& diff);
 882     /**
 883         Subtracts the given date span from this object.
 884
 885         @beginWxPythonOnly
 886         This method is named "SubtractDS" in wxPython.
 887         @endWxPythonOnly
 888     */
 889     wxDateTime Subtract(const wxDateSpan& diff) const;
 890     /**
 891         Subtracts the given date span from this object.
 892
 893         @beginWxPythonOnly
 894         This method is named "SubtractDS" in wxPython.
 895         @endWxPythonOnly
 896     */
 897     wxDateTime& Subtract(const wxDateSpan& diff);
 898     /**
 899         Subtracts another date from this one and returns the difference between
 900         them as a wxTimeSpan.
 901     */
 902     wxTimeSpan Subtract(const wxDateTime& dt) const;
 903
 904     /**
 905         Adds the given date span to this object.
 906     */
 907     wxDateTime operator+=(const wxDateSpan& diff);
 908     /**
 909         Subtracts the given date span from this object.
 910     */
 911     wxDateTime& operator-=(const wxDateSpan& diff);
 912     /**
 913         Adds the given time span to this object.
 914     */
 915     wxDateTime& operator+=(const wxTimeSpan& diff);
 916     /**
 917         Subtracts the given time span from this object.
 918     */
 919     wxDateTime& operator-=(const wxTimeSpan& diff);
 920
 921     //@}
 922
 923
 924
 925     /**
 926         @name Date Formatting and Parsing
 927
 928         See @ref datetime_formatting
 929     */
 930     //@{
 931
 932     /**
 933         This function does the same as the standard ANSI C @c strftime(3)
 934         function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html).
 935         Please see its description for the meaning of @a format parameter.
 936
 937         It also accepts a few wxWidgets-specific extensions: you can optionally
 938         specify the width of the field to follow using @c printf(3)-like syntax
 939         and the format specification @c "%l" can be used to get the number of
 940         milliseconds.
 941
 942         @see ParseFormat()
 943     */
 944     wxString Format(const wxString& format = wxDefaultDateTimeFormat,
 945                     const TimeZone& tz = Local) const;
 946
 947     /**
 948         Identical to calling Format() with @c "%x" argument (which means
 949         "preferred date representation for the current locale").
 950     */
 951     wxString FormatDate() const;
 952
 953     /**
 954         Returns the combined date-time representation in the ISO 8601 format
 955         @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
 956         the result exactly corresponding to the ISO standard, but it can also
 957         be useful to use a space as separator if a more human-readable combined
 958         date-time representation is needed.
 959
 960         @see FormatISODate(), FormatISOTime(), ParseISOCombined()
 961     */
 962     wxString FormatISOCombined(char sep = 'T') const;
 963
 964     /**
 965         This function returns the date representation in the ISO 8601 format
 966         @c "YYYY-MM-DD".
 967     */
 968     wxString FormatISODate() const;
 969
 970     /**
 971         This function returns the time representation in the ISO 8601 format
 972         @c "HH:MM:SS".
 973     */
 974     wxString FormatISOTime() const;
 975
 976     /**
 977         Identical to calling Format() with @c "%X" argument (which means
 978         "preferred time representation for the current locale").
 979     */
 980     wxString FormatTime() const;
 981
 982     /**
 983         This function is like ParseDateTime(), but it only allows the date to
 984         be specified.
 985
 986         It is thus less flexible then ParseDateTime(), but also has less
 987         chances to misinterpret the user input.
 988
 989         See ParseFormat() for the description of function parameters and return
 990         value.
 991
 992         @see Format()
 993     */
 994     bool ParseDate(const wxString& date, wxString::const_iterator *end);
 995
 996     /**
 997         Parses the string @a datetime containing the date and time in free
 998         format.
 999
1000         This function tries as hard as it can to interpret the given string as
1001         date and time. Unlike ParseRfc822Date(), it will accept anything that
1002         may be accepted and will only reject strings which cannot be parsed in
1003         any way at all. Notice that the function will fail if either date or
1004         time part is present but not both, use ParseDate() or ParseTime() to
1005         parse strings containing just the date or time component.
1006
1007         See ParseFormat() for the description of function parameters and return
1008         value.
1009     */
1010     bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);
1011
1012     /**
1013         This function parses the string @a date according to the given
1014         @e format. The system @c strptime(3) function is used whenever
1015         available, but even if it is not, this function is still implemented,
1016         although support for locale-dependent format specifiers such as
1017         @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
1018         as @c "%z" and @c "%Z" are not implemented. This function does handle
1019         the month and weekday names in the current locale on all platforms,
1020         however.
1021
1022         Please see the description of the ANSI C function @c strftime(3) for
1023         the syntax of the format string.
1024
1025         The @a dateDef parameter is used to fill in the fields which could not
1026         be determined from the format string. For example, if the format is
1027         @c "%d" (the day of the month), the month and the year are taken from
1028         @a dateDef. If it is not specified, Today() is used as the default
1029         date.
1030
1031         Example of using this function:
1032         @code
1033             wxDateTime dt;
1034             wxString str = "...";
1035             wxString::const_iterator end;
1036             if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) )
1037                 ... parsing failed ...
1038             else if ( end == str.end() )
1039                 ... entire string parsed ...
1040             else
1041                 ... wxString(end, str.end()) left over ...
1042         @endcode
1043
1044         @param date
1045             The string to be parsed.
1046         @param format
1047             strptime()-like format string.
1048         @param dateDef
1049             Used to fill in the date components not specified in the @a date
1050             string.
1051         @param end
1052             Will be filled with the iterator pointing to the location where the
1053             parsing stopped if the function returns @true. If the entire string
1054             was consumed, it is set to @c date.end(). Notice that this argument
1055             must be non-@NULL.
1056         @return
1057             @true if at least part of the string was parsed successfully,
1058             @false otherwise.
1059
1060         @see Format()
1061     */
1062     bool ParseFormat(const wxString& date,
1063                      const wxString& format,
1064                      const wxDateTime& dateDef,
1065                      wxString::const_iterator *end);
1066
1067     /**
1068         @overload
1069     */
1070     bool ParseFormat(const wxString& date,
1071                      const wxString& format,
1072                      wxString::const_iterator *end);
1073
1074     /**
1075         @overload
1076     */
1077     bool ParseFormat(const wxString& date, wxString::const_iterator *end);
1078
1079     /**
1080         This function parses the string containing the date and time in ISO
1081         8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between
1082         the date and time parts must be equal to @a sep for the function to
1083         succeed.
1084
1085         @return @true if the entire string was parsed successfully, @false
1086                  otherwise.
1087     */
1088     bool ParseISOCombined(const wxString& date, char sep = 'T');
1089
1090     /**
1091         This function parses the date in ISO 8601 format @c "YYYY-MM-DD".
1092
1093         @return @true if the entire string was parsed successfully, @false
1094                  otherwise.
1095     */
1096     bool ParseISODate(const wxString& date);
1097
1098     /**
1099         This function parses the time in ISO 8601 format @c "HH:MM:SS".
1100
1101         @return @true if the entire string was parsed successfully, @false
1102                  otherwise.
1103     */
1104     bool ParseISOTime(const wxString& date);
1105
1106     /**
1107         Parses the string @a date looking for a date formatted according to the
1108         RFC 822 in it. The exact description of this format may, of course, be
1109         found in the RFC (section 5), but, briefly, this is the format used in
1110         the headers of Internet email messages and one of the most common
1111         strings expressing date in this format may be something like
1112         @c "Sat, 18 Dec 1999 00:48:30 +0100".
1113
1114         Returns @NULL if the conversion failed, otherwise return the pointer to
1115         the character immediately following the part of the string which could
1116         be parsed. If the entire string contains only the date in RFC 822
1117         format, the returned pointer will be pointing to a @c NUL character.
1118
1119         This function is intentionally strict, it will return an error for any
1120         string which is not RFC 822 compliant. If you need to parse date
1121         formatted in more free ways, you should use ParseDateTime() or
1122         ParseDate() instead.
1123
1124         See ParseFormat() for the description of function parameters and return
1125         value.
1126     */
1127     bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
1128
1129     /**
1130         This functions is like ParseDateTime(), but only allows the time to be
1131         specified in the input string.
1132
1133         See ParseFormat() for the description of function parameters and return
1134         value.
1135     */
1136     bool ParseTime(const wxString& time, wxString::const_iterator *end);
1137
1138     //@}
1139
1140
1141
1142     /**
1143         @name Calendar Calculations
1144
1145         The functions in this section perform the basic calendar calculations,
1146         mostly related to the week days. They allow to find the given week day
1147         in the week with given number (either in the month or in the year) and
1148         so on.
1149
1150         None of the functions in this section modify the time part of the
1151         wxDateTime, they only work with the date part of it.
1152     */
1153     //@{
1154
1155     /**
1156         Returns the copy of this object to which SetToLastMonthDay() was
1157         applied.
1158     */
1159     wxDateTime GetLastMonthDay(Month month = Inv_Month,
1160                                int year = Inv_Year) const;
1161
1162     /**
1163         Returns the copy of this object to which SetToLastWeekDay() was
1164         applied.
1165     */
1166     wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month,
1167                               int year = Inv_Year);
1168
1169     /**
1170         Returns the copy of this object to which SetToNextWeekDay() was
1171         applied.
1172     */
1173     wxDateTime GetNextWeekDay(WeekDay weekday) const;
1174
1175     /**
1176         Returns the copy of this object to which SetToPrevWeekDay() was
1177         applied.
1178     */
1179     wxDateTime GetPrevWeekDay(WeekDay weekday) const;
1180
1181     /**
1182         Returns the copy of this object to which SetToWeekDay() was applied.
1183     */
1184     wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month,
1185                           int year = Inv_Year) const;
1186
1187     /**
1188         Returns the copy of this object to which SetToWeekDayInSameWeek() was
1189         applied.
1190     */
1191     wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
1192                                     WeekFlags flags = Monday_First) const;
1193
1194     /**
1195         Returns the copy of this object to which SetToYearDay() was applied.
1196     */
1197     wxDateTime GetYearDay(wxDateTime_t yday) const;
1198
1199     /**
1200         Sets the date to the last day in the specified month (the current one
1201         by default).
1202
1203         @return The reference to the modified object itself.
1204     */
1205     wxDateTime& SetToLastMonthDay(Month month = Inv_Month, int year = Inv_Year);
1206
1207     /**
1208         The effect of calling this function is the same as of calling
1209         @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
1210         last @a weekday in the given month and year (the current ones by
1211         default). Always returns @true.
1212     */
1213     bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
1214                           int year = Inv_Year);
1215
1216     /**
1217         Sets the date so that it will be the first @a weekday following the
1218         current date.
1219
1220         @return The reference to the modified object itself.
1221     */
1222     wxDateTime& SetToNextWeekDay(WeekDay weekday);
1223
1224     /**
1225         Sets the date so that it will be the last @a weekday before the current
1226         date.
1227
1228         @return The reference to the modified object itself.
1229     */
1230     wxDateTime& SetToPrevWeekDay(WeekDay weekday);
1231
1232     /**
1233         Sets the date to the @e n-th @a weekday in the given month of the given
1234         year (the current month and year are used by default). The parameter
1235         @a n may be either positive (counting from the beginning of the month)
1236         or negative (counting from the end of it).
1237
1238         For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
1239         second Wednesday in the current month and
1240         SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
1241         in the current month.
1242
1243         @return @true if the date was modified successfully, @false otherwise
1244                  meaning that the specified date doesn't exist.
1245     */
1246     bool SetToWeekDay(WeekDay weekday, int n = 1,
1247                        Month month = Inv_Month, int year = Inv_Year);
1248
1249     /**
1250         Adjusts the date so that it will still lie in the same week as before,
1251         but its week day will be the given one.
1252
1253         @return The reference to the modified object itself.
1254     */
1255     wxDateTime& SetToWeekDayInSameWeek(WeekDay weekday,
1256                                       WeekFlags flags = Monday_First);
1257
1258     /**
1259         Sets the date to the day number @a yday in the same year (i.e., unlike
1260         the other functions, this one does not use the current year). The day
1261         number should be in the range 1-366 for the leap years and 1-365 for
1262         the other ones.
1263
1264         @return The reference to the modified object itself.
1265     */
1266     wxDateTime& SetToYearDay(wxDateTime_t yday);
1267
1268     //@}
1269
1270
1271
1272     /**
1273         @name Astronomical/Historical Functions
1274
1275         Some degree of support for the date units used in astronomy and/or
1276         history is provided. You can construct a wxDateTime object from a
1277         JDN and you may also get its JDN, MJD or Rata Die number from it.
1278
1279         Related functions in other groups: wxDateTime(double), Set(double)
1280     */
1281     //@{
1282
1283     /**
1284         Synonym for GetJulianDayNumber().
1285     */
1286     double GetJDN() const;
1287
1288     /**
1289         Returns the JDN corresponding to this date. Beware of rounding errors!
1290
1291         @see GetModifiedJulianDayNumber()
1292     */
1293     double GetJulianDayNumber() const;
1294
1295     /**
1296         Synonym for GetModifiedJulianDayNumber().
1297     */
1298     double GetMJD() const;
1299
1300     /**
1301         Returns the @e "Modified Julian Day Number" (MJD) which is, by
1302         definition, is equal to JDN - 2400000.5.
1303         The MJDs are simpler to work with as the integral MJDs correspond to
1304         midnights of the dates in the Gregorian calendar and not the noons like
1305         JDN. The MJD 0 represents Nov 17, 1858.
1306     */
1307     double GetModifiedJulianDayNumber() const;
1308
1309     /**
1310         Return the @e Rata Die number of this date.
1311
1312         By definition, the Rata Die number is a date specified as the number of
1313         days relative to a base date of December 31 of the year 0. Thus January
1314         1 of the year 1 is Rata Die day 1.
1315     */
1316     double GetRataDie() const;
1317
1318     //@}
1319
1320
1321
1322     /**
1323         @name Time Zone and DST Support
1324
1325         Please see the @ref overview_datetime_timezones "time zone overview"
1326         for more information about time zones. Normally, these functions should
1327         be rarely used.
1328
1329         Related functions in other groups: GetBeginDST(), GetEndDST()
1330     */
1331     //@{
1332
1333     /**
1334         Transform the date from the given time zone to the local one. If
1335         @a noDST is @true, no DST adjustments will be made.
1336
1337         @return The date in the local time zone.
1338     */
1339     wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const;
1340
1341     /**
1342         Returns @true if the DST is applied for this date in the given country.
1343
1344         @see GetBeginDST(), GetEndDST()
1345     */
1346     int IsDST(Country country = Country_Default) const;
1347
1348     /**
1349         Same as FromTimezone() but modifies the object in place.
1350     */
1351     wxDateTime& MakeFromTimezone(const TimeZone& tz, bool noDST = false);
1352
1353     /**
1354         Modifies the object in place to represent the date in another time
1355         zone. If @a noDST is @true, no DST adjustments will be made.
1356     */
1357     wxDateTime& MakeTimezone(const TimeZone& tz, bool noDST = false);
1358
1359     /**
1360         This is the same as calling MakeTimezone() with the argument @c GMT0.
1361     */
1362     wxDateTime& MakeUTC(bool noDST = false);
1363
1364     /**
1365         Transform the date to the given time zone. If @a noDST is @true, no DST
1366         adjustments will be made.
1367
1368         @return The date in the new time zone.
1369     */
1370     wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
1371
1372     /**
1373         This is the same as calling ToTimezone() with the argument @c GMT0.
1374     */
1375     wxDateTime ToUTC(bool noDST = false) const;
1376
1377     //@}
1378
1379
1380
1381
1382
1383     /**
1384         Converts the year in absolute notation (i.e. a number which can be
1385         negative, positive or zero) to the year in BC/AD notation. For the
1386         positive years, nothing is done, but the year 0 is year 1 BC and so for
1387         other years there is a difference of 1.
1388
1389         This function should be used like this:
1390
1391         @code
1392         wxDateTime dt(...);
1393         int y = dt.GetYear();
1394         printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
1395         @endcode
1396     */
1397     static int ConvertYearToBC(int year);
1398
1399     /**
1400         Returns the translations of the strings @c AM and @c PM used for time
1401         formatting for the current locale. Either of the pointers may be @NULL
1402         if the corresponding value is not needed.
1403     */
1404     static void GetAmPmStrings(wxString* am, wxString* pm);
1405
1406     /**
1407         Get the beginning of DST for the given country in the given year
1408         (current one by default). This function suffers from limitations
1409         described in the @ref overview_datetime_dst "DST overview".
1410
1411         @see GetEndDST()
1412     */
1413     static wxDateTime GetBeginDST(int year = Inv_Year,
1414                                    Country country = Country_Default);
1415
1416     /**
1417         Returns the end of DST for the given country in the given year (current
1418         one by default).
1419
1420         @see GetBeginDST()
1421     */
1422     static wxDateTime GetEndDST(int year = Inv_Year,
1423                                  Country country = Country_Default);
1424
1425     /**
1426         Get the current century, i.e. first two digits of the year, in given
1427         calendar (only Gregorian is currently supported).
1428     */
1429     static int GetCentury(int year);
1430
1431     /**
1432         Returns the current default country. The default country is used for
1433         DST calculations, for example.
1434
1435         @see SetCountry()
1436     */
1437     static Country GetCountry();
1438
1439     /**
1440         Get the current month in given calendar (only Gregorian is currently
1441         supported).
1442     */
1443     static Month GetCurrentMonth(Calendar cal = Gregorian);
1444
1445     /**
1446         Get the current year in given calendar (only Gregorian is currently
1447         supported).
1448     */
1449     static int GetCurrentYear(Calendar cal = Gregorian);
1450
1451     /**
1452         Return the standard English name of the given month.
1453
1454         This function always returns "January" or "Jan" for January, use
1455         GetMonthName() to retrieve the name of the month in the users current
1456         locale.
1457
1458         @param month
1459             One of wxDateTime::Jan, ..., wxDateTime::Dec values.
1460         @param flags
1461             Either Name_Full (default) or Name_Abbr.
1462
1463         @see GetEnglishWeekDayName()
1464
1465         @since 2.9.0
1466      */
1467     static wxString GetEnglishMonthName(Month month,
1468                                         NameFlags flags = Name_Full);
1469
1470     /**
1471         Return the standard English name of the given week day.
1472
1473         This function always returns "Monday" or "Mon" for Monday, use
1474         GetWeekDayName() to retrieve the name of the month in the users current
1475         locale.
1476
1477         @param weekday
1478             One of wxDateTime::Sun, ..., wxDateTime::Sat values.
1479         @param flags
1480             Either Name_Full (default) or Name_Abbr.
1481
1482         @see GetEnglishMonthName()
1483
1484         @since 2.9.0
1485      */
1486     static wxString GetEnglishWeekDayName(WeekDay weekday,
1487                                           NameFlags flags = Name_Full);
1488
1489     /**
1490         Gets the full (default) or abbreviated name of the given month.
1491
1492         This function returns the name in the current locale, use
1493         GetEnglishMonthName() to get the untranslated name if necessary.
1494
1495         @param month
1496             One of wxDateTime::Jan, ..., wxDateTime::Dec values.
1497         @param flags
1498             Either Name_Full (default) or Name_Abbr.
1499
1500         @see GetWeekDayName()
1501     */
1502     static wxString GetMonthName(Month month, NameFlags flags = Name_Full);
1503
1504     /**
1505         Returns the number of days in the given year. The only supported value
1506         for @a cal currently is @c Gregorian.
1507
1508         @beginWxPythonOnly
1509         This method is named "GetNumberOfDaysInYear" in wxPython.
1510         @endWxPythonOnly
1511     */
1512     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
1513
1514     /**
1515         Returns the number of days in the given month of the given year. The
1516         only supported value for @a cal currently is @c Gregorian.
1517
1518         @beginWxPythonOnly
1519         This method is named "GetNumberOfDaysInMonth" in wxPython.
1520         @endWxPythonOnly
1521     */
1522     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
1523                                         Calendar cal = Gregorian);
1524
1525     /**
1526         Returns the current time.
1527     */
1528     static time_t GetTimeNow();
1529
1530     /**
1531         Returns the current time broken down using the buffer whose address is
1532         passed to the function with @a tm to store the result.
1533     */
1534     static tm* GetTmNow(struct tm *tm);
1535
1536     /**
1537         Returns the current time broken down. Note that this function returns a
1538         pointer to a static buffer that's reused by calls to this function and
1539         certain C library functions (e.g. localtime). If there is any chance
1540         your code might be used in a multi-threaded application, you really
1541         should use GetTmNow(struct tm *) instead.
1542     */
1543     static tm* GetTmNow();
1544
1545     /**
1546         Gets the full (default) or abbreviated name of the given week day.
1547
1548         This function returns the name in the current locale, use
1549         GetEnglishWeekDayName() to get the untranslated name if necessary.
1550
1551         @param weekday
1552             One of wxDateTime::Sun, ..., wxDateTime::Sat values.
1553         @param flags
1554             Either Name_Full (default) or Name_Abbr.
1555
1556         @see GetMonthName()
1557     */
1558     static wxString GetWeekDayName(WeekDay weekday,
1559                                    NameFlags flags = Name_Full);
1560
1561     /**
1562         Returns @true if DST was used in the given year (the current one by
1563         default) in the given country.
1564     */
1565     static bool IsDSTApplicable(int year = Inv_Year,
1566                                   Country country = Country_Default);
1567
1568     /**
1569         Returns @true if the @a year is a leap one in the specified calendar.
1570         This functions supports Gregorian and Julian calendars.
1571     */
1572     static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian);
1573
1574     /**
1575         This function returns @true if the specified (or default) country is
1576         one of Western European ones. It is used internally by wxDateTime to
1577         determine the DST convention and date and time formatting rules.
1578     */
1579     static bool IsWestEuropeanCountry(Country country = Country_Default);
1580
1581     /**
1582         Returns the object corresponding to the current time.
1583
1584         Example:
1585
1586         @code
1587         wxDateTime now = wxDateTime::Now();
1588         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
1589         @endcode
1590
1591         @note This function is accurate up to seconds. UNow() should be used
1592               for better precision, but it is less efficient and might not be
1593               available on all platforms.
1594
1595         @see Today()
1596     */
1597     static wxDateTime Now();
1598
1599     /**
1600         Sets the country to use by default. This setting influences the DST
1601         calculations, date formatting and other things.
1602
1603         @see GetCountry()
1604     */
1605     static void SetCountry(Country country);
1606
1607     /**
1608         Set the date to the given @a weekday in the week number @a numWeek of
1609         the given @a year . The number should be in range 1-53.
1610
1611         Note that the returned date may be in a different year than the one
1612         passed to this function because both the week 1 and week 52 or 53 (for
1613         leap years) contain days from different years. See GetWeekOfYear() for
1614         the explanation of how the year weeks are counted.
1615     */
1616     static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
1617                                        WeekDay weekday = Mon);
1618
1619     /**
1620         Returns the object corresponding to the midnight of the current day
1621         (i.e. the same as Now(), but the time part is set to 0).
1622
1623         @see Now()
1624     */
1625     static wxDateTime Today();
1626
1627     /**
1628         Returns the object corresponding to the current time including the
1629         milliseconds if a function to get time with such precision is available
1630         on the current platform (supported under most Unices and Win32).
1631
1632         @see Now()
1633     */
1634     static wxDateTime UNow();
1635 };
1636
1637 /**
1638     Global instance of an empty wxDateTime object.
1639
1640     @todo Would it be better to rename this wxNullDateTime so it's consistent
1641           with the rest of the "empty/invalid/null" global objects?
1642 */
1643 const wxDateTime wxDefaultDateTime;
1644
1645 /*
1646     wxInvalidDateTime is an alias for wxDefaultDateTime.
1647 */
1648 #define wxInvalidDateTime wxDefaultDateTime
1649
1650
1651 /**
1652     @class wxDateTimeWorkDays
1653
1654     @todo Write wxDateTimeWorkDays documentation.
1655
1656     @library{wxbase}
1657     @category{data}
1658 */
1659 class wxDateTimeWorkDays
1660 {
1661 public:
1662
1663 };
1664
1665
1666
1667 /**
1668     @class wxDateSpan
1669
1670     This class is a "logical time span" and is useful for implementing program
1671     logic for such things as "add one month to the date" which, in general,
1672     doesn't mean to add 60*60*24*31 seconds to it, but to take the same date
1673     the next month (to understand that this is indeed different consider adding
1674     one month to Feb, 15 -- we want to get Mar, 15, of course).
1675
1676     When adding a month to the date, all lesser components (days, hours, ...)
1677     won't be changed unless the resulting date would be invalid: for example,
1678     Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
1679
1680     Because of this feature, adding and subtracting back again the same
1681     wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
1682     month will be Jan 28, not Jan 31!
1683
1684     wxDateSpan objects can be either positive or negative. They may be
1685     multiplied by scalars which multiply all deltas by the scalar: i.e.
1686     2*(1  month and  1  day) is 2 months and 2 days. They can be added together
1687     with wxDateTime or wxTimeSpan, but the type of result is different for each
1688     case.
1689
1690     @warning If you specify both weeks and days, the total number of days added
1691              will be 7*weeks + days! See also GetTotalDays().
1692
1693     Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
1694     if and only if they both give the same target date when added to @b every
1695     source date. Thus wxDateSpan::Months(1) is not equal to
1696     wxDateSpan::Days(30), because they don't give the same date when added to
1697     Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
1698
1699     Finally, notice that for adding hours, minutes and so on you don't need
1700     this class at all: wxTimeSpan will do the job because there are no
1701     subtleties associated with those (we don't support leap seconds).
1702
1703     @library{wxbase}
1704     @category{data}
1705
1706     @see @ref overview_datetime, wxDateTime
1707 */
1708 class wxDateSpan
1709 {
1710 public:
1711     /**
1712         Constructs the date span object for the given number of years, months,
1713         weeks and days. Note that the weeks and days add together if both are
1714         given.
1715     */
1716     wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0);
1717
1718     /**
1719         Returns the sum of two date spans.
1720
1721         @return A new wxDateSpan object with the result.
1722     */
1723     wxDateSpan Add(const wxDateSpan& other) const;
1724     /**
1725         Adds the given wxDateSpan to this wxDateSpan and returns a reference
1726         to itself.
1727     */
1728     wxDateSpan& Add(const wxDateSpan& other);
1729
1730     /**
1731         Returns a date span object corresponding to one day.
1732
1733         @see Days()
1734     */
1735     static wxDateSpan Day();
1736
1737     /**
1738         Returns a date span object corresponding to the given number of days.
1739
1740         @see Day()
1741     */
1742     static wxDateSpan Days(int days);
1743
1744     /**
1745         Returns the number of days (not counting the weeks component) in this
1746         date span.
1747
1748         @see GetTotalDays()
1749     */
1750     int GetDays() const;
1751
1752     /**
1753         Returns the number of the months (not counting the years) in this date
1754         span.
1755     */
1756     int GetMonths() const;
1757
1758     /**
1759         Returns the combined number of days in this date span, counting both
1760         weeks and days. This doesn't take months or years into account.
1761
1762         @see GetWeeks(), GetDays()
1763     */
1764     int GetTotalDays() const;
1765
1766     /**
1767         Returns the number of weeks in this date span.
1768
1769         @see GetTotalDays()
1770     */
1771     int GetWeeks() const;
1772
1773     /**
1774         Returns the number of years in this date span.
1775     */
1776     int GetYears() const;
1777
1778     /**
1779         Returns a date span object corresponding to one month.
1780
1781         @see Months()
1782     */
1783     static wxDateSpan Month();
1784
1785     /**
1786         Returns a date span object corresponding to the given number of months.
1787
1788         @see Month()
1789     */
1790     static wxDateSpan Months(int mon);
1791
1792     /**
1793         Returns the product of the date span by the specified @a factor. The
1794         product is computed by multiplying each of the components by the
1795         @a factor.
1796
1797         @return A new wxDateSpan object with the result.
1798     */
1799     wxDateSpan Multiply(int factor) const;
1800     /**
1801         Multiplies this date span by the specified @a factor. The product is
1802         computed by multiplying each of the components by the @a factor.
1803
1804         @return A reference to this wxDateSpan object modified in place.
1805     */
1806     wxDateSpan& Multiply(int factor);
1807
1808     /**
1809         Changes the sign of this date span.
1810
1811         @see Negate()
1812     */
1813     wxDateSpan& Neg();
1814
1815     /**
1816         Returns a date span with the opposite sign.
1817
1818         @see Neg()
1819     */
1820     wxDateSpan Negate() const;
1821
1822     /**
1823         Sets the number of days (without modifying any other components) in
1824         this date span.
1825     */
1826     wxDateSpan& SetDays(int n);
1827
1828     /**
1829         Sets the number of months (without modifying any other components) in
1830         this date span.
1831     */
1832     wxDateSpan& SetMonths(int n);
1833
1834     /**
1835         Sets the number of weeks (without modifying any other components) in
1836         this date span.
1837     */
1838     wxDateSpan& SetWeeks(int n);
1839
1840     /**
1841         Sets the number of years (without modifying any other components) in
1842         this date span.
1843     */
1844     wxDateSpan& SetYears(int n);
1845
1846     /**
1847         Returns the difference of two date spans.
1848
1849         @return A new wxDateSpan object with the result.
1850     */
1851     wxDateSpan Subtract(const wxDateSpan& other) const;
1852     /**
1853         Subtracts the given wxDateSpan to this wxDateSpan and returns a
1854         reference to itself.
1855     */
1856     wxDateSpan& Subtract(const wxDateSpan& other);
1857
1858     /**
1859         Returns a date span object corresponding to one week.
1860
1861         @see Weeks()
1862     */
1863     static wxDateSpan Week();
1864
1865     /**
1866         Returns a date span object corresponding to the given number of weeks.
1867
1868         @see Week()
1869     */
1870     static wxDateSpan Weeks(int weeks);
1871
1872     /**
1873         Returns a date span object corresponding to one year.
1874
1875         @see Years()
1876     */
1877     static wxDateSpan Year();
1878
1879     /**
1880         Returns a date span object corresponding to the given number of years.
1881
1882         @see Year()
1883     */
1884     static wxDateSpan Years(int years);
1885
1886     /**
1887         Adds the given wxDateSpan to this wxDateSpan and returns the result.
1888     */
1889     wxDateSpan& operator+=(const wxDateSpan& other);
1890
1891     /**
1892         Subtracts the given wxDateSpan to this wxDateSpan and returns the
1893         result.
1894     */
1895     wxDateSpan& operator-=(const wxDateSpan& other);
1896
1897     /**
1898         Changes the sign of this date span.
1899
1900         @see Negate()
1901     */
1902     wxDateSpan& operator-();
1903
1904     /**
1905         Multiplies this date span by the specified @a factor. The product is
1906         computed by multiplying each of the components by the @a factor.
1907
1908         @return A reference to this wxDateSpan object modified in place.
1909     */
1910     wxDateSpan& operator*=(int factor);
1911
1912     /**
1913         Returns @true if this date span is different from the other one.
1914     */
1915     bool operator!=(const wxDateSpan&) const;
1916
1917     /**
1918         Returns @true if this date span is equal to the other one. Two date
1919         spans are considered equal if and only if they have the same number of
1920         years and months and the same total number of days (counting both days
1921         and weeks).
1922     */
1923     bool operator==(const wxDateSpan&) const;
1924 };
1925
1926
1927
1928 /**
1929     @class wxTimeSpan
1930
1931     wxTimeSpan class represents a time interval.
1932
1933     @library{wxbase}
1934     @category{data}
1935
1936     @see @ref overview_datetime, wxDateTime
1937 */
1938 class wxTimeSpan
1939 {
1940 public:
1941     /**
1942         Default constructor, constructs a zero timespan.
1943     */
1944     wxTimeSpan();
1945     /**
1946         Constructs timespan from separate values for each component, with the
1947         date set to 0. Hours are not restricted to 0-24 range, neither are
1948         minutes, seconds or milliseconds.
1949     */
1950     wxTimeSpan(long hours, long min = 0, wxLongLong sec = 0, wxLongLong msec = 0);
1951
1952     /**
1953         Returns the absolute value of the timespan: does not modify the object.
1954     */
1955     wxTimeSpan Abs() const;
1956
1957     /**
1958         Returns the sum of two time spans.
1959
1960         @return A new wxDateSpan object with the result.
1961     */
1962     wxTimeSpan Add(const wxTimeSpan& diff) const;
1963     /**
1964         Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
1965         to itself.
1966     */
1967     wxTimeSpan& Add(const wxTimeSpan& diff);
1968
1969     /**
1970         Returns the timespan for one day.
1971     */
1972     static wxTimeSpan Day();
1973
1974     /**
1975         Returns the timespan for the given number of days.
1976     */
1977     static wxTimeSpan Days(long days);
1978
1979     /**
1980         Returns the string containing the formatted representation of the time
1981         span. The following format specifiers are allowed after %:
1982
1983         - @c H - Number of Hours
1984         - @c M - Number of Minutes
1985         - @c S - Number of Seconds
1986         - @c l - Number of Milliseconds
1987         - @c D - Number of Days
1988         - @c E - Number of Weeks
1989         - @c % - The percent character
1990
1991         Note that, for example, the number of hours in the description above is
1992         not well defined: it can be either the total number of hours (for
1993         example, for a time span of 50 hours this would be 50) or just the hour
1994         part of the time span, which would be 2 in this case as 50 hours is
1995         equal to 2 days and 2 hours.
1996
1997         wxTimeSpan resolves this ambiguity in the following way: if there had
1998         been, indeed, the @c %D format specified preceding the @c %H, then it
1999         is interpreted as 2. Otherwise, it is 50.
2000
2001         The same applies to all other format specifiers: if they follow a
2002         specifier of larger unit, only the rest part is taken, otherwise the
2003         full value is used.
2004     */
2005     wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
2006
2007     /**
2008         Returns the difference in number of days.
2009     */
2010     int GetDays() const;
2011
2012     /**
2013         Returns the difference in number of hours.
2014     */
2015     int GetHours() const;
2016
2017     /**
2018         Returns the difference in number of milliseconds.
2019     */
2020     wxLongLong GetMilliseconds() const;
2021
2022     /**
2023         Returns the difference in number of minutes.
2024     */
2025     int GetMinutes() const;
2026
2027     /**
2028         Returns the difference in number of seconds.
2029     */
2030     wxLongLong GetSeconds() const;
2031
2032     /**
2033         Returns the internal representation of timespan.
2034     */
2035     wxLongLong GetValue() const;
2036
2037     /**
2038         Returns the difference in number of weeks.
2039     */
2040     int GetWeeks() const;
2041
2042     /**
2043         Returns the timespan for one hour.
2044     */
2045     static wxTimeSpan Hour();
2046
2047     /**
2048         Returns the timespan for the given number of hours.
2049     */
2050     static wxTimeSpan Hours(long hours);
2051
2052     /**
2053         Returns @true if two timespans are equal.
2054     */
2055     bool IsEqualTo(const wxTimeSpan& ts) const;
2056
2057     /**
2058         Compares two timespans: works with the absolute values, i.e. -2 hours
2059         is longer than 1 hour. Also, it will return @false if the timespans are
2060         equal in absolute value.
2061     */
2062     bool IsLongerThan(const wxTimeSpan& ts) const;
2063
2064     /**
2065         Returns @true if the timespan is negative.
2066     */
2067     bool IsNegative() const;
2068
2069     /**
2070         Returns @true if the timespan is empty.
2071     */
2072     bool IsNull() const;
2073
2074     /**
2075         Returns @true if the timespan is positive.
2076     */
2077     bool IsPositive() const;
2078
2079     /**
2080         Compares two timespans: works with the absolute values, i.e. 1 hour is
2081         shorter than -2 hours. Also, it will return @false if the timespans are
2082         equal in absolute value.
2083     */
2084     bool IsShorterThan(const wxTimeSpan& ts) const;
2085
2086     /**
2087         Returns the timespan for one millisecond.
2088     */
2089     static wxTimeSpan Millisecond();
2090
2091     /**
2092         Returns the timespan for the given number of milliseconds.
2093     */
2094     static wxTimeSpan Milliseconds(wxLongLong ms);
2095
2096     /**
2097         Returns the timespan for one minute.
2098     */
2099     static wxTimeSpan Minute();
2100
2101     /**
2102         Returns the timespan for the given number of minutes.
2103     */
2104     static wxTimeSpan Minutes(long min);
2105
2106     /**
2107         Returns the product of this time span by @a n.
2108
2109         @return A new wxTimeSpan object with the result.
2110     */
2111     wxTimeSpan Multiply(int n) const;
2112     /**
2113         Multiplies this time span by @a n.
2114
2115         @return A reference to this wxTimeSpan object modified in place.
2116     */
2117     wxTimeSpan& Multiply(int n);
2118
2119     /**
2120         Negate the value of the timespan.
2121
2122         @see Negate()
2123     */
2124     wxTimeSpan& Neg();
2125
2126     /**
2127         Returns timespan with inverted sign.
2128
2129         @see Neg()
2130     */
2131     wxTimeSpan Negate() const;
2132
2133     /**
2134         Returns the timespan for one second.
2135     */
2136     static wxTimeSpan Second();
2137
2138     /**
2139         Returns the timespan for the given number of seconds.
2140     */
2141     static wxTimeSpan Seconds(wxLongLong sec);
2142
2143     /**
2144         Returns the difference of two time spans.
2145
2146         @return A new wxDateSpan object with the result.
2147     */
2148     wxTimeSpan Subtract(const wxTimeSpan& diff) const;
2149     /**
2150         Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
2151         reference to itself.
2152     */
2153     wxTimeSpan& Subtract(const wxTimeSpan& diff);
2154
2155     /**
2156         Returns the timespan for one week.
2157     */
2158     static wxTimeSpan Week();
2159
2160     /**
2161         Returns the timespan for the given number of weeks.
2162     */
2163     static wxTimeSpan Weeks(long weeks);
2164
2165     /**
2166         Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
2167     */
2168     wxTimeSpan& operator+=(const wxTimeSpan& diff);
2169
2170     /**
2171         Multiplies this time span by @a n.
2172
2173         @return A reference to this wxTimeSpan object modified in place.
2174     */
2175     wxTimeSpan& operator*=(int n);
2176
2177     /**
2178         Negate the value of the timespan.
2179
2180         @see Negate()
2181     */
2182     wxTimeSpan& operator-();
2183
2184     /**
2185         Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
2186         result.
2187     */
2188     wxTimeSpan& operator-=(const wxTimeSpan& diff);
2189 };
2190
2191
2192
2193 /**
2194     @class wxDateTimeHolidayAuthority
2195
2196     @todo Write wxDateTimeHolidayAuthority documentation.
2197
2198     @library{wxbase}
2199     @category{data}
2200 */
2201 class wxDateTimeHolidayAuthority
2202 {
2203 public:
2204
2205 };
2206