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