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