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