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.
 806
 807         It is thus less flexible then ParseDateTime(), but also has less
 808         chances to misinterpret the user input.
 809
 810         See ParseFormat() for the description of function parameters and return
 811         value.
 812
 813         @see Format()
 814     */
 815     bool ParseDate(const wxString& date, wxString::const_iterator *end);
 816
 817     /**
 818         Parses the string @a datetime containing the date and time in free
 819         format.
 820
 821         This function tries as hard as it can to interpret the given string as
 822         date and time. Unlike ParseRfc822Date(), it will accept anything that
 823         may be accepted and will only reject strings which can not be parsed in
 824         any way at all.
 825
 826         See ParseFormat() for the description of function parameters and return
 827         value.
 828     */
 829     bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);
 830
 831     /**
 832         This function parses the string @a date according to the given
 833         @e format. The system @c strptime(3) function is used whenever
 834         available, but even if it is not, this function is still implemented,
 835         although support for locale-dependent format specifiers such as
 836         @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
 837         as @c "%z" and @c "%Z" are not implemented. This function does handle
 838         the month and weekday names in the current locale on all platforms,
 839         however.
 840
 841         Please see the description of the ANSI C function @c strftime(3) for
 842         the syntax of the format string.
 843
 844         The @a dateDef parameter is used to fill in the fields which could not
 845         be determined from the format string. For example, if the format is
 846         @c "%d" (the day of the month), the month and the year are taken from
 847         @a dateDef. If it is not specified, Today() is used as the default
 848         date.
 849
 850         Example of using this function:
 851         @code
 852             wxDateTime dt;
 853             wxString str = "...";
 854             wxString::const_iterator end;
 855             if ( !dt.ParseFormat(str, "%Y-%m-%d", &end) )
 856                 ... parsing failed ...
 857             else if ( end == str.end() )
 858                 ... entire string parsed ...
 859             else
 860                 ... wxString(end, str.end()) left over ...
 861         @endcode
 862
 863         @param date
 864             The string to be parsed.
 865         @param format
 866             strptime()-like format string.
 867         @param dateDef
 868             Used to fill in the date components not specified in the @a date
 869             string.
 870         @param end
 871             Will be filled with the iterator pointing to the location where the
 872             parsing stopped if the function returns @true. If the entire string
 873             was consumed, it is set to @c date.end(). Notice that this argument
 874             must be non-@NULL.
 875         @return
 876             @true if at least part of the string was parsed successfully,
 877             @false otherwise.
 878
 879         @see Format()
 880     */
 881     bool ParseFormat(const wxString& date,
 882                      const wxString& format = wxDefaultDateTimeFormat,
 883                      const wxDateTime& dateDef = wxDefaultDateTime,
 884                      wxString::const_iterator *end);
 885
 886     /**
 887         @overload
 888     */
 889     bool ParseFormat(const wxString& date,
 890                      const wxString& format = wxDefaultDateTimeFormat,
 891                      wxString::const_iterator *end);
 892
 893     /**
 894         @overload
 895     */
 896     bool ParseFormat(const wxString& date, wxString::const_iterator *end);
 897
 898     /**
 899         This function parses the string containing the date and time in ISO
 900         8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between
 901         the date and time parts must be equal to @a sep for the function to
 902         succeed.
 903
 904         @return @true if the entire string was parsed successfully, @false
 905                  otherwise.
 906     */
 907     bool ParseISOCombined(const wxString& date, char sep = 'T');
 908
 909     /**
 910         This function parses the date in ISO 8601 format @c "YYYY-MM-DD".
 911
 912         @return @true if the entire string was parsed successfully, @false
 913                  otherwise.
 914     */
 915     bool ParseISODate(const wxString& date);
 916
 917     /**
 918         This function parses the time in ISO 8601 format @c "HH:MM:SS".
 919
 920         @return @true if the entire string was parsed successfully, @false
 921                  otherwise.
 922     */
 923     bool ParseISOTime(const wxString& date);
 924
 925     /**
 926         Parses the string @a date looking for a date formatted according to the
 927         RFC 822 in it. The exact description of this format may, of course, be
 928         found in the RFC (section 5), but, briefly, this is the format used in
 929         the headers of Internet email messages and one of the most common
 930         strings expressing date in this format may be something like
 931         @c "Sat, 18 Dec 1999 00:48:30 +0100".
 932
 933         Returns @NULL if the conversion failed, otherwise return the pointer to
 934         the character immediately following the part of the string which could
 935         be parsed. If the entire string contains only the date in RFC 822
 936         format, the returned pointer will be pointing to a @c NUL character.
 937
 938         This function is intentionally strict, it will return an error for any
 939         string which is not RFC 822 compliant. If you need to parse date
 940         formatted in more free ways, you should use ParseDateTime() or
 941         ParseDate() instead.
 942
 943         See ParseFormat() for the description of function parameters and return
 944         value.
 945     */
 946     bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);
 947
 948     /**
 949         This functions is like ParseDateTime(), but only allows the time to be
 950         specified in the input string.
 951
 952         See ParseFormat() for the description of function parameters and return
 953         value.
 954     */
 955     bool ParseTime(const wxString& time, wxString::const_iterator *end);
 956
 957     //@}
 958
 959
 960
 961     /**
 962         @name Calendar Calculations
 963
 964         The functions in this section perform the basic calendar calculations,
 965         mostly related to the week days. They allow to find the given week day
 966         in the week with given number (either in the month or in the year) and
 967         so on.
 968
 969         None of the functions in this section modify the time part of the
 970         wxDateTime, they only work with the date part of it.
 971     */
 972     //@{
 973
 974     /**
 975         Returns the copy of this object to which SetToLastMonthDay() was
 976         applied.
 977     */
 978     wxDateTime GetLastMonthDay(Month month = Inv_Month,
 979                                int year = Inv_Year) const;
 980
 981     /**
 982         Returns the copy of this object to which SetToLastWeekDay() was
 983         applied.
 984     */
 985     wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month,
 986                               int year = Inv_Year);
 987
 988     /**
 989         Returns the copy of this object to which SetToNextWeekDay() was
 990         applied.
 991     */
 992     wxDateTime GetNextWeekDay(WeekDay weekday) const;
 993
 994     /**
 995         Returns the copy of this object to which SetToPrevWeekDay() was
 996         applied.
 997     */
 998     wxDateTime GetPrevWeekDay(WeekDay weekday) const;
 999
1000     /**
1001         Returns the copy of this object to which SetToWeekDay() was applied.
1002     */
1003     wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month,
1004                           int year = Inv_Year) const;
1005
1006     /**
1007         Returns the copy of this object to which SetToWeekDayInSameWeek() was
1008         applied.
1009     */
1010     wxDateTime GetWeekDayInSameWeek(WeekDay weekday,
1011                                     WeekFlags flags = Monday_First) const;
1012
1013     /**
1014         Returns the copy of this object to which SetToYearDay() was applied.
1015     */
1016     wxDateTime GetYearDay(wxDateTime_t yday) const;
1017
1018     /**
1019         Sets the date to the last day in the specified month (the current one
1020         by default).
1021
1022         @return The reference to the modified object itself.
1023     */
1024     wxDateTime& SetToLastMonthDay(Month month = Inv_Month, int year = Inv_Year);
1025
1026     /**
1027         The effect of calling this function is the same as of calling
1028         @c SetToWeekDay(-1, weekday, month, year). The date will be set to the
1029         last @a weekday in the given month and year (the current ones by
1030         default). Always returns @true.
1031     */
1032     bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month,
1033                           int year = Inv_Year);
1034
1035     /**
1036         Sets the date so that it will be the first @a weekday following the
1037         current date.
1038
1039         @return The reference to the modified object itself.
1040     */
1041     wxDateTime& SetToNextWeekDay(WeekDay weekday);
1042
1043     /**
1044         Sets the date so that it will be the last @a weekday before the current
1045         date.
1046
1047         @return The reference to the modified object itself.
1048     */
1049     wxDateTime& SetToPrevWeekDay(WeekDay weekday);
1050
1051     /**
1052         Sets the date to the @e n-th @a weekday in the given month of the given
1053         year (the current month and year are used by default). The parameter
1054         @a n may be either positive (counting from the beginning of the month)
1055         or negative (counting from the end of it).
1056
1057         For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the
1058         second Wednesday in the current month and
1059         SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday
1060         in the current month.
1061
1062         @return @true if the date was modified successfully, @false otherwise
1063                  meaning that the specified date doesn't exist.
1064     */
1065     bool SetToWeekDay(WeekDay weekday, int n = 1,
1066                        Month month = Inv_Month, int year = Inv_Year);
1067
1068     /**
1069         Adjusts the date so that it will still lie in the same week as before,
1070         but its week day will be the given one.
1071
1072         @return The reference to the modified object itself.
1073     */
1074     wxDateTime& SetToWeekDayInSameWeek(WeekDay weekday,
1075                                       WeekFlags flags = Monday_First);
1076
1077     /**
1078         Sets the date to the day number @a yday in the same year (i.e., unlike
1079         the other functions, this one does not use the current year). The day
1080         number should be in the range 1-366 for the leap years and 1-365 for
1081         the other ones.
1082
1083         @return The reference to the modified object itself.
1084     */
1085     wxDateTime& SetToYearDay(wxDateTime_t yday);
1086
1087     //@}
1088
1089
1090
1091     /**
1092         @name Astronomical/Historical Functions
1093
1094         Some degree of support for the date units used in astronomy and/or
1095         history is provided. You can construct a wxDateTime object from a
1096         JDN and you may also get its JDN, MJD or Rata Die number from it.
1097
1098         Related functions in other groups: wxDateTime(double), Set(double)
1099     */
1100     //@{
1101
1102     /**
1103         Synonym for GetJulianDayNumber().
1104     */
1105     double GetJDN() const;
1106
1107     /**
1108         Returns the JDN corresponding to this date. Beware of rounding errors!
1109
1110         @see GetModifiedJulianDayNumber()
1111     */
1112     double GetJulianDayNumber() const;
1113
1114     /**
1115         Synonym for GetModifiedJulianDayNumber().
1116     */
1117     double GetMJD() const;
1118
1119     /**
1120         Returns the @e "Modified Julian Day Number" (MJD) which is, by
1121         definition, is equal to JDN - 2400000.5.
1122         The MJDs are simpler to work with as the integral MJDs correspond to
1123         midnights of the dates in the Gregorian calendar and not the noons like
1124         JDN. The MJD 0 represents Nov 17, 1858.
1125     */
1126     double GetModifiedJulianDayNumber() const;
1127
1128     /**
1129         Return the @e Rata Die number of this date.
1130
1131         By definition, the Rata Die number is a date specified as the number of
1132         days relative to a base date of December 31 of the year 0. Thus January
1133         1 of the year 1 is Rata Die day 1.
1134     */
1135     double GetRataDie() const;
1136
1137     //@}
1138
1139
1140
1141     /**
1142         @name Time Zone and DST Support
1143
1144         Please see the @ref overview_datetime_timezones "time zone overview"
1145         for more information about time zones. Normally, these functions should
1146         be rarely used.
1147
1148         Related functions in other groups: GetBeginDST(), GetEndDST()
1149     */
1150     //@{
1151
1152     /**
1153         Transform the date from the given time zone to the local one. If
1154         @a noDST is @true, no DST adjustments will be made.
1155
1156         @return The date in the local time zone.
1157     */
1158     wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const;
1159
1160     /**
1161         Returns @true if the DST is applied for this date in the given country.
1162
1163         @see GetBeginDST(), GetEndDST()
1164     */
1165     int IsDST(Country country = Country_Default) const;
1166
1167     /**
1168         Same as FromTimezone() but modifies the object in place.
1169     */
1170     wxDateTime& MakeFromTimezone(const TimeZone& tz, bool noDST = false);
1171
1172     /**
1173         Modifies the object in place to represent the date in another time
1174         zone. If @a noDST is @true, no DST adjustments will be made.
1175     */
1176     wxDateTime& MakeTimezone(const TimeZone& tz, bool noDST = false);
1177
1178     /**
1179         This is the same as calling MakeTimezone() with the argument @c GMT0.
1180     */
1181     wxDateTime& MakeUTC(bool noDST = false);
1182
1183     /**
1184         Transform the date to the given time zone. If @a noDST is @true, no DST
1185         adjustments will be made.
1186
1187         @return The date in the new time zone.
1188     */
1189     wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const;
1190
1191     /**
1192         This is the same as calling ToTimezone() with the argument @c GMT0.
1193     */
1194     wxDateTime ToUTC(bool noDST = false) const;
1195
1196     //@}
1197
1198
1199
1200
1201
1202     /**
1203         Converts the year in absolute notation (i.e. a number which can be
1204         negative, positive or zero) to the year in BC/AD notation. For the
1205         positive years, nothing is done, but the year 0 is year 1 BC and so for
1206         other years there is a difference of 1.
1207
1208         This function should be used like this:
1209
1210         @code
1211         wxDateTime dt(...);
1212         int y = dt.GetYear();
1213         printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
1214         @endcode
1215     */
1216     static int ConvertYearToBC(int year);
1217
1218     /**
1219         Returns the translations of the strings @c AM and @c PM used for time
1220         formatting for the current locale. Either of the pointers may be @NULL
1221         if the corresponding value is not needed.
1222     */
1223     static void GetAmPmStrings(wxString* am, wxString* pm);
1224
1225     /**
1226         Get the beginning of DST for the given country in the given year
1227         (current one by default). This function suffers from limitations
1228         described in the @ref overview_datetime_dst "DST overview".
1229
1230         @see GetEndDST()
1231     */
1232     static wxDateTime GetBeginDST(int year = Inv_Year,
1233                                    Country country = Country_Default);
1234
1235     /**
1236         Returns the end of DST for the given country in the given year (current
1237         one by default).
1238
1239         @see GetBeginDST()
1240     */
1241     static wxDateTime GetEndDST(int year = Inv_Year,
1242                                  Country country = Country_Default);
1243
1244     /**
1245         Get the current century, i.e. first two digits of the year, in given
1246         calendar (only Gregorian is currently supported).
1247     */
1248     static int GetCentury(int year);
1249
1250     /**
1251         Returns the current default country. The default country is used for
1252         DST calculations, for example.
1253
1254         @see SetCountry()
1255     */
1256     static Country GetCountry();
1257
1258     /**
1259         Get the current month in given calendar (only Gregorian is currently
1260         supported).
1261     */
1262     static Month GetCurrentMonth(Calendar cal = Gregorian);
1263
1264     /**
1265         Get the current year in given calendar (only Gregorian is currently
1266         supported).
1267     */
1268     static int GetCurrentYear(Calendar cal = Gregorian);
1269
1270     /**
1271         Return the standard English name of the given month.
1272
1273         This function always returns "January" or "Jan" for January, use
1274         GetMonthName() to retrieve the name of the month in the users current
1275         locale.
1276
1277         @param month
1278             One of wxDateTime::Jan, ..., wxDateTime::Dec values.
1279         @param flags
1280             Either Name_Full (default) or Name_Abbr.
1281
1282         @see GetEnglishWeekDayName()
1283
1284         @since 2.9.0
1285      */
1286     static wxString GetEnglishMonthName(Month month,
1287                                         NameFlags flags = Name_Full);
1288
1289     /**
1290         Return the standard English name of the given week day.
1291
1292         This function always returns "Monday" or "Mon" for Monday, use
1293         GetWeekDayName() to retrieve the name of the month in the users current
1294         locale.
1295
1296         @param weekday
1297             One of wxDateTime::Sun, ..., wxDateTime::Sat values.
1298         @param flags
1299             Either Name_Full (default) or Name_Abbr.
1300
1301         @see GetEnglishMonthName()
1302
1303         @since 2.9.0
1304      */
1305     static wxString GetEnglishWeekDayName(WeekDay weekday,
1306                                           NameFlags flags = Name_Full);
1307
1308     /**
1309         Gets the full (default) or abbreviated name of the given month.
1310
1311         This function returns the name in the current locale, use
1312         GetEnglishMonthName() to get the untranslated name if necessary.
1313
1314         @param month
1315             One of wxDateTime::Jan, ..., wxDateTime::Dec values.
1316         @param flags
1317             Either Name_Full (default) or Name_Abbr.
1318
1319         @see GetWeekDayName()
1320     */
1321     static wxString GetMonthName(Month month, NameFlags flags = Name_Full);
1322
1323     /**
1324         Returns the number of days in the given year. The only supported value
1325         for @a cal currently is @c Gregorian.
1326
1327         @beginWxPythonOnly
1328         This method is named "GetNumberOfDaysInYear" in wxPython.
1329         @endWxPythonOnly
1330     */
1331     static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian);
1332
1333     /**
1334         Returns the number of days in the given month of the given year. The
1335         only supported value for @a cal currently is @c Gregorian.
1336
1337         @beginWxPythonOnly
1338         This method is named "GetNumberOfDaysInMonth" in wxPython.
1339         @endWxPythonOnly
1340     */
1341     static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year,
1342                                         Calendar cal = Gregorian);
1343
1344     /**
1345         Returns the current time.
1346     */
1347     static time_t GetTimeNow();
1348
1349     /**
1350         Returns the current time broken down using the buffer whose adress is
1351         passed to the function with @a tm to store the result.
1352     */
1353     static tm* GetTmNow(struct tm *tm);
1354
1355     /**
1356         Returns the current time broken down. Note that this function returns a
1357         pointer to a static buffer that's reused by calls to this function and
1358         certain C library functions (e.g. localtime). If there is any chance
1359         your code might be used in a multi-threaded application, you really
1360         should use GetTmNow(struct tm *) instead.
1361     */
1362     static tm* GetTmNow();
1363
1364     /**
1365         Gets the full (default) or abbreviated name of the given week day.
1366
1367         This function returns the name in the current locale, use
1368         GetEnglishWeekDayName() to get the untranslated name if necessary.
1369
1370         @param weekday
1371             One of wxDateTime::Sun, ..., wxDateTime::Sat values.
1372         @param flags
1373             Either Name_Full (default) or Name_Abbr.
1374
1375         @see GetMonthName()
1376     */
1377     static wxString GetWeekDayName(WeekDay weekday,
1378                                    NameFlags flags = Name_Full);
1379
1380     /**
1381         Returns @true if DST was used in the given year (the current one by
1382         default) in the given country.
1383     */
1384     static bool IsDSTApplicable(int year = Inv_Year,
1385                                   Country country = Country_Default);
1386
1387     /**
1388         Returns @true if the @a year is a leap one in the specified calendar.
1389         This functions supports Gregorian and Julian calendars.
1390     */
1391     static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian);
1392
1393     /**
1394         This function returns @true if the specified (or default) country is
1395         one of Western European ones. It is used internally by wxDateTime to
1396         determine the DST convention and date and time formatting rules.
1397     */
1398     static bool IsWestEuropeanCountry(Country country = Country_Default);
1399
1400     /**
1401         Returns the object corresponding to the current time.
1402
1403         Example:
1404
1405         @code
1406         wxDateTime now = wxDateTime::Now();
1407         printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str());
1408         @endcode
1409
1410         @note This function is accurate up to seconds. UNow() should be used
1411               for better precision, but it is less efficient and might not be
1412               available on all platforms.
1413
1414         @see Today()
1415     */
1416     static wxDateTime Now();
1417
1418     /**
1419         Sets the country to use by default. This setting influences the DST
1420         calculations, date formatting and other things.
1421
1422         @see GetCountry()
1423     */
1424     static void SetCountry(Country country);
1425
1426     /**
1427         Set the date to the given @a weekday in the week number @a numWeek of
1428         the given @a year . The number should be in range 1-53.
1429
1430         Note that the returned date may be in a different year than the one
1431         passed to this function because both the week 1 and week 52 or 53 (for
1432         leap years) contain days from different years. See GetWeekOfYear() for
1433         the explanation of how the year weeks are counted.
1434     */
1435     static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek,
1436                                        WeekDay weekday = Mon);
1437
1438     /**
1439         Returns the object corresponding to the midnight of the current day
1440         (i.e. the same as Now(), but the time part is set to 0).
1441
1442         @see Now()
1443     */
1444     static wxDateTime Today();
1445
1446     /**
1447         Returns the object corresponding to the current time including the
1448         milliseconds if a function to get time with such precision is available
1449         on the current platform (supported under most Unices and Win32).
1450
1451         @see Now()
1452     */
1453     static wxDateTime UNow();
1454 };
1455
1456 /**
1457     Global instance of an empty wxDateTime object.
1458
1459     @todo Would it be better to rename this wxNullDateTime so it's consistent
1460           with the rest of the "empty/invalid/null" global objects?
1461 */
1462 const wxDateTime wxDefaultDateTime;
1463
1464
1465
1466 /**
1467     @class wxDateTimeWorkDays
1468
1469     @todo Write wxDateTimeWorkDays documentation.
1470
1471     @library{wxbase}
1472     @category{data}
1473 */
1474 class wxDateTimeWorkDays
1475 {
1476 public:
1477
1478 };
1479
1480
1481
1482 /**
1483     @class wxDateSpan
1484
1485     This class is a "logical time span" and is useful for implementing program
1486     logic for such things as "add one month to the date" which, in general,
1487     doesn't mean to add 60*60*24*31 seconds to it, but to take the same date
1488     the next month (to understand that this is indeed different consider adding
1489     one month to Feb, 15 -- we want to get Mar, 15, of course).
1490
1491     When adding a month to the date, all lesser components (days, hours, ...)
1492     won't be changed unless the resulting date would be invalid: for example,
1493     Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
1494
1495     Because of this feature, adding and subtracting back again the same
1496     wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1
1497     month will be Jan 28, not Jan 31!
1498
1499     wxDateSpan objects can be either positive or negative. They may be
1500     multiplied by scalars which multiply all deltas by the scalar: i.e.
1501     2*(1  month and  1  day) is 2 months and 2 days. They can be added together
1502     with wxDateTime or wxTimeSpan, but the type of result is different for each
1503     case.
1504
1505     @warning If you specify both weeks and days, the total number of days added
1506              will be 7*weeks + days! See also GetTotalDays().
1507
1508     Equality operators are defined for wxDateSpans. Two wxDateSpans are equal
1509     if and only if they both give the same target date when added to @b every
1510     source date. Thus wxDateSpan::Months(1) is not equal to
1511     wxDateSpan::Days(30), because they don't give the same date when added to
1512     Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2).
1513
1514     Finally, notice that for adding hours, minutes and so on you don't need
1515     this class at all: wxTimeSpan will do the job because there are no
1516     subtleties associated with those (we don't support leap seconds).
1517
1518     @library{wxbase}
1519     @category{data}
1520
1521     @see @ref overview_datetime, wxDateTime
1522 */
1523 class wxDateSpan
1524 {
1525 public:
1526     /**
1527         Constructs the date span object for the given number of years, months,
1528         weeks and days. Note that the weeks and days add together if both are
1529         given.
1530     */
1531     wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0);
1532
1533     /**
1534         Returns the sum of two date spans.
1535
1536         @return A new wxDateSpan object with the result.
1537     */
1538     wxDateSpan Add(const wxDateSpan& other) const;
1539     /**
1540         Adds the given wxDateSpan to this wxDateSpan and returns a reference
1541         to itself.
1542     */
1543     wxDateSpan& Add(const wxDateSpan& other);
1544
1545     /**
1546         Returns a date span object corresponding to one day.
1547
1548         @see Days()
1549     */
1550     static wxDateSpan Day();
1551
1552     /**
1553         Returns a date span object corresponding to the given number of days.
1554
1555         @see Day()
1556     */
1557     static wxDateSpan Days(int days);
1558
1559     /**
1560         Returns the number of days (not counting the weeks component) in this
1561         date span.
1562
1563         @see GetTotalDays()
1564     */
1565     int GetDays() const;
1566
1567     /**
1568         Returns the number of the months (not counting the years) in this date
1569         span.
1570     */
1571     int GetMonths() const;
1572
1573     /**
1574         Returns the combined number of days in this date span, counting both
1575         weeks and days. This doesn't take months or years into account.
1576
1577         @see GetWeeks(), GetDays()
1578     */
1579     int GetTotalDays() const;
1580
1581     /**
1582         Returns the number of weeks in this date span.
1583
1584         @see GetTotalDays()
1585     */
1586     int GetWeeks() const;
1587
1588     /**
1589         Returns the number of years in this date span.
1590     */
1591     int GetYears() const;
1592
1593     /**
1594         Returns a date span object corresponding to one month.
1595
1596         @see Months()
1597     */
1598     static wxDateSpan Month();
1599
1600     /**
1601         Returns a date span object corresponding to the given number of months.
1602
1603         @see Month()
1604     */
1605     static wxDateSpan Months(int mon);
1606
1607     /**
1608         Returns the product of the date span by the specified @a factor. The
1609         product is computed by multiplying each of the components by the
1610         @a factor.
1611
1612         @return A new wxDateSpan object with the result.
1613     */
1614     wxDateSpan Multiply(int factor) const;
1615     /**
1616         Multiplies this date span by the specified @a factor. The product is
1617         computed by multiplying each of the components by the @a factor.
1618
1619         @return A reference to this wxDateSpan object modified in place.
1620     */
1621     wxDateSpan& Multiply(int factor);
1622
1623     /**
1624         Changes the sign of this date span.
1625
1626         @see Negate()
1627     */
1628     wxDateSpan& Neg();
1629
1630     /**
1631         Returns a date span with the opposite sign.
1632
1633         @see Neg()
1634     */
1635     wxDateSpan Negate() const;
1636
1637     /**
1638         Sets the number of days (without modifying any other components) in
1639         this date span.
1640     */
1641     wxDateSpan& SetDays(int n);
1642
1643     /**
1644         Sets the number of months (without modifying any other components) in
1645         this date span.
1646     */
1647     wxDateSpan& SetMonths(int n);
1648
1649     /**
1650         Sets the number of weeks (without modifying any other components) in
1651         this date span.
1652     */
1653     wxDateSpan& SetWeeks(int n);
1654
1655     /**
1656         Sets the number of years (without modifying any other components) in
1657         this date span.
1658     */
1659     wxDateSpan& SetYears(int n);
1660
1661     /**
1662         Returns the difference of two date spans.
1663
1664         @return A new wxDateSpan object with the result.
1665     */
1666     wxDateSpan Subtract(const wxDateSpan& other) const;
1667     /**
1668         Subtracts the given wxDateSpan to this wxDateSpan and returns a
1669         reference to itself.
1670     */
1671     wxDateSpan& Subtract(const wxDateSpan& other);
1672
1673     /**
1674         Returns a date span object corresponding to one week.
1675
1676         @see Weeks()
1677     */
1678     static wxDateSpan Week();
1679
1680     /**
1681         Returns a date span object corresponding to the given number of weeks.
1682
1683         @see Week()
1684     */
1685     static wxDateSpan Weeks(int weeks);
1686
1687     /**
1688         Returns a date span object corresponding to one year.
1689
1690         @see Years()
1691     */
1692     static wxDateSpan Year();
1693
1694     /**
1695         Returns a date span object corresponding to the given number of years.
1696
1697         @see Year()
1698     */
1699     static wxDateSpan Years(int years);
1700
1701     /**
1702         Adds the given wxDateSpan to this wxDateSpan and returns the result.
1703     */
1704     wxDateSpan& operator+=(const wxDateSpan& other);
1705
1706     /**
1707         Subtracts the given wxDateSpan to this wxDateSpan and returns the
1708         result.
1709     */
1710     wxDateSpan& operator-=(const wxDateSpan& other);
1711
1712     /**
1713         Changes the sign of this date span.
1714
1715         @see Negate()
1716     */
1717     wxDateSpan& operator-();
1718
1719     /**
1720         Multiplies this date span by the specified @a factor. The product is
1721         computed by multiplying each of the components by the @a factor.
1722
1723         @return A reference to this wxDateSpan object modified in place.
1724     */
1725     wxDateSpan& operator*=(int factor);
1726
1727     /**
1728         Returns @true if this date span is different from the other one.
1729     */
1730     bool operator!=(const wxDateSpan&) const;
1731
1732     /**
1733         Returns @true if this date span is equal to the other one. Two date
1734         spans are considered equal if and only if they have the same number of
1735         years and months and the same total number of days (counting both days
1736         and weeks).
1737     */
1738     bool operator==(const wxDateSpan&) const;
1739 };
1740
1741
1742
1743 /**
1744     @class wxTimeSpan
1745
1746     wxTimeSpan class represents a time interval.
1747
1748     @library{wxbase}
1749     @category{data}
1750
1751     @see @ref overview_datetime, wxDateTime
1752 */
1753 class wxTimeSpan
1754 {
1755 public:
1756     /**
1757         Default constructor, constructs a zero timespan.
1758     */
1759     wxTimeSpan();
1760     /**
1761         Constructs timespan from separate values for each component, with the
1762         date set to 0. Hours are not restricted to 0-24 range, neither are
1763         minutes, seconds or milliseconds.
1764     */
1765     wxTimeSpan(long hours, long min = 0, wxLongLong sec = 0, wxLongLong msec = 0);
1766
1767     /**
1768         Returns the absolute value of the timespan: does not modify the object.
1769     */
1770     wxTimeSpan Abs() const;
1771
1772     /**
1773         Returns the sum of two time spans.
1774
1775         @return A new wxDateSpan object with the result.
1776     */
1777     wxTimeSpan Add(const wxTimeSpan& diff) const;
1778     /**
1779         Adds the given wxTimeSpan to this wxTimeSpan and returns a reference
1780         to itself.
1781     */
1782     wxTimeSpan& Add(const wxTimeSpan& diff);
1783
1784     /**
1785         Returns the timespan for one day.
1786     */
1787     static wxTimeSpan Day();
1788
1789     /**
1790         Returns the timespan for the given number of days.
1791     */
1792     static wxTimeSpan Days(long days);
1793
1794     /**
1795         Returns the string containing the formatted representation of the time
1796         span. The following format specifiers are allowed after %:
1797
1798         - @c H - Number of Hours
1799         - @c M - Number of Minutes
1800         - @c S - Number of Seconds
1801         - @c l - Number of Milliseconds
1802         - @c D - Number of Days
1803         - @c E - Number of Weeks
1804         - @c % - The percent character
1805
1806         Note that, for example, the number of hours in the description above is
1807         not well defined: it can be either the total number of hours (for
1808         example, for a time span of 50 hours this would be 50) or just the hour
1809         part of the time span, which would be 2 in this case as 50 hours is
1810         equal to 2 days and 2 hours.
1811
1812         wxTimeSpan resolves this ambiguity in the following way: if there had
1813         been, indeed, the @c %D format specified preceding the @c %H, then it
1814         is interpreted as 2. Otherwise, it is 50.
1815
1816         The same applies to all other format specifiers: if they follow a
1817         specifier of larger unit, only the rest part is taken, otherwise the
1818         full value is used.
1819     */
1820     wxString Format(const wxString& = wxDefaultTimeSpanFormat) const;
1821
1822     /**
1823         Returns the difference in number of days.
1824     */
1825     int GetDays() const;
1826
1827     /**
1828         Returns the difference in number of hours.
1829     */
1830     int GetHours() const;
1831
1832     /**
1833         Returns the difference in number of milliseconds.
1834     */
1835     wxLongLong GetMilliseconds() const;
1836
1837     /**
1838         Returns the difference in number of minutes.
1839     */
1840     int GetMinutes() const;
1841
1842     /**
1843         Returns the difference in number of seconds.
1844     */
1845     wxLongLong GetSeconds() const;
1846
1847     /**
1848         Returns the internal representation of timespan.
1849     */
1850     wxLongLong GetValue() const;
1851
1852     /**
1853         Returns the difference in number of weeks.
1854     */
1855     int GetWeeks() const;
1856
1857     /**
1858         Returns the timespan for one hour.
1859     */
1860     static wxTimeSpan Hour();
1861
1862     /**
1863         Returns the timespan for the given number of hours.
1864     */
1865     static wxTimeSpan Hours(long hours);
1866
1867     /**
1868         Returns @true if two timespans are equal.
1869     */
1870     bool IsEqualTo(const wxTimeSpan& ts) const;
1871
1872     /**
1873         Compares two timespans: works with the absolute values, i.e. -2 hours
1874         is longer than 1 hour. Also, it will return @false if the timespans are
1875         equal in absolute value.
1876     */
1877     bool IsLongerThan(const wxTimeSpan& ts) const;
1878
1879     /**
1880         Returns @true if the timespan is negative.
1881     */
1882     bool IsNegative() const;
1883
1884     /**
1885         Returns @true if the timespan is empty.
1886     */
1887     bool IsNull() const;
1888
1889     /**
1890         Returns @true if the timespan is positive.
1891     */
1892     bool IsPositive() const;
1893
1894     /**
1895         Compares two timespans: works with the absolute values, i.e. 1 hour is
1896         shorter than -2 hours. Also, it will return @false if the timespans are
1897         equal in absolute value.
1898     */
1899     bool IsShorterThan(const wxTimeSpan& ts) const;
1900
1901     /**
1902         Returns the timespan for one millisecond.
1903     */
1904     static wxTimeSpan Millisecond();
1905
1906     /**
1907         Returns the timespan for the given number of milliseconds.
1908     */
1909     static wxTimeSpan Milliseconds(wxLongLong ms);
1910
1911     /**
1912         Returns the timespan for one minute.
1913     */
1914     static wxTimeSpan Minute();
1915
1916     /**
1917         Returns the timespan for the given number of minutes.
1918     */
1919     static wxTimeSpan Minutes(long min);
1920
1921     /**
1922         Returns the product of this time span by @a n.
1923
1924         @return A new wxTimeSpan object with the result.
1925     */
1926     wxTimeSpan Multiply(int n) const;
1927     /**
1928         Multiplies this time span by @a n.
1929
1930         @return A reference to this wxTimeSpan object modified in place.
1931     */
1932     wxTimeSpan& Multiply(int n);
1933
1934     /**
1935         Negate the value of the timespan.
1936
1937         @see Negate()
1938     */
1939     wxTimeSpan& Neg();
1940
1941     /**
1942         Returns timespan with inverted sign.
1943
1944         @see Neg()
1945     */
1946     wxTimeSpan Negate() const;
1947
1948     /**
1949         Returns the timespan for one second.
1950     */
1951     static wxTimeSpan Second();
1952
1953     /**
1954         Returns the timespan for the given number of seconds.
1955     */
1956     static wxTimeSpan Seconds(wxLongLong sec);
1957
1958     /**
1959         Returns the difference of two time spans.
1960
1961         @return A new wxDateSpan object with the result.
1962     */
1963     wxTimeSpan Subtract(const wxTimeSpan& diff) const;
1964     /**
1965         Subtracts the given wxTimeSpan to this wxTimeSpan and returns a
1966         reference to itself.
1967     */
1968     wxTimeSpan& Subtract(const wxTimeSpan& diff);
1969
1970     /**
1971         Returns the timespan for one week.
1972     */
1973     static wxTimeSpan Week();
1974
1975     /**
1976         Returns the timespan for the given number of weeks.
1977     */
1978     static wxTimeSpan Weeks(long weeks);
1979
1980     /**
1981         Adds the given wxTimeSpan to this wxTimeSpan and returns the result.
1982     */
1983     wxTimeSpan& operator+=(const wxTimeSpan& diff);
1984
1985     /**
1986         Multiplies this time span by @a n.
1987
1988         @return A reference to this wxTimeSpan object modified in place.
1989     */
1990     wxTimeSpan& operator*=(int n);
1991
1992     /**
1993         Negate the value of the timespan.
1994
1995         @see Negate()
1996     */
1997     wxTimeSpan& operator-();
1998
1999     /**
2000         Subtracts the given wxTimeSpan to this wxTimeSpan and returns the
2001         result.
2002     */
2003     wxTimeSpan& operator-=(const wxTimeSpan& diff);
2004 };
2005
2006
2007
2008 /**
2009     @class wxDateTimeHolidayAuthority
2010
2011     @todo Write wxDateTimeHolidayAuthority documentation.
2012
2013     @library{wxbase}
2014     @category{data}
2015 */
2016 class wxDateTimeHolidayAuthority
2017 {
2018 public:
2019
2020 };
2021